Checkout 流程描述

当客户准备完成购买时，从您的客户端（client）向您的服务端（server）发起结账请求，您的服务端应该使用 Subotiz API 创建一个 Checkout Session。
Checkout Session 会提供一个结账页的 URL，您可以将客户重定向到 Subotiz 结账页。
客户会在 Subotiz 结账页输入支付信息并完成交易。
交易完成之后 Subotiz 会以 webhook 的方式通知您的服务端。

sequenceDiagram
    participant Client as Merchant Client
    participant Server as Merchant Server
    participant SubotizAPI as Subotiz API
    participant SubotizCheckout as Subotiz Checkout

    Client->>Server: 1. 发起订单
    Server->>SubotizAPI: 2. 创建 Checkout Session
    SubotizAPI-->>Server: 3. 返回结账页地址
    Server->>SubotizCheckout: 4. 重定向到结账页
    note right of SubotizCheckout: 5. 客户完成付款
    SubotizCheckout->>Client: 6. 客户重定向到应用程序
    SubotizAPI->>Server: webhook 通知支付结果

接入步骤

第一步：创建商品

在 Subotiz 管理平台中创建商品和商品定价，将商品信息和价格信息保存在服务端中。在创建 Checkout Session 需要依赖于商品定价的 price_id 来动态获取商品信息。

创建商品：

创建商品定价：

第二步：提供支付成功或取消页面

您的程序需要准备两个页面 URL，分别是顾客支付成功和取消支付时跳转的 URL，并确保能够在公网中访问，以便 Subotiz 能够将客户重定向到这些页面中。（两者允许使用同一页面）

第三步：提供 webhook 通知地址

创建一个事件接收地址，以接收您账户上发生的事件。当有事件发生时，Subotiz 会发送 HTTPS POST 请求将 Webhook 事件通知到该端点中，请求体内容是 JSON 格式的事件对象。您可以通过关注事件来同步变更您系统的业务数据。

第四步：提供创建 Checkout Session 的入口

您的系统客户端中需要提供一个用于发起结账的入口，例如在订单预览页的结账按钮。当客户点击按钮时，在您的服务端应该调用 Subotiz API 创建 Checkout Session ，并根据订单信息修改调用参数，创建 Checkout Session 时传入的参数决定客户在结账页看到的内容，例如：商品信息、订单价格等。待接口响应后，将客户重定向到 Subotiz 结账页。

Hosted 模式创建 Checkout Session 示例：

curl --location 'https://api.subotiz.com/api/v1/session' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_api_key}' \
--header 'Request-Id: 9913dca8-90f8-4e20-98bc-565f0222ffa8' \
--data-raw '{
		"access_no":       "77d52a21dc032b4",
		"sub_merchant_id": "2816433",
		"order_id":        "123e4567-zzzaa20daw11a",
    "payer_id": "customer_id_0012",
		"line_items": [
			{
				"price_id": "543321366326164797",
				"quantity": "1"
			}
        ],
		"email":           "[email protected]",
    "integration_method": "hosted",
    "cancel_url": "https://www.subotiz.com",
    "return_url": "https://www.subotiz.com"
	}'

关键参数：

order_id：为接入方订单 ID，用于后续关联业务数据
integration_method：设置为 hosted，表示使用托管式页面模式接入
cancel_url：客户在 Subotiz Checkout 页面取消支付时跳转的页面
return_url：客户在 Subotiz Checkout 页面支付成功之后跳转的页面

示例结账页面：

Subotiz 在客户完成结账之后会重定向回成功页面，完成一次完整的结账流程。并且 Subotiz 会以 Webhook 的形式通知到您的服务端，您可以在服务端处理成功订阅之后的逻辑。