> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 托管式页面

Subotiz 支持以托管页面（hosted 模式）的方式完成结账流程。当客户需要结账时，您可以使用 Subotiz API 创建一个 Checkout Session ，然后重定向到 Subotiz 支付页面来完成整个支付过程。

## Checkout 流程描述

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

```mermaid theme={null}
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 通知支付结果
```

## 接入步骤

<Steps>
  <Step title="创建商品">
    在 Subotiz 管理平台中创建商品和商品定价，将商品信息和价格信息保存在服务端中。创建 Checkout Session 时需依赖商品定价的 price\_id 来动态获取商品信息。

    <Frame caption="创建商品">
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/741e16c5-c08ad293dd06e2211804d3dcba417c1db81ad2ca254ebe0ebebe2f58-81ba9a45-ab9e-4ead-85dc-8bf25de2c690.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=0c8e48d0f7f0d4d7790f2b3a8f3195e4" width="1280" height="565" data-path="images/741e16c5-c08ad293dd06e2211804d3dcba417c1db81ad2ca254ebe0ebebe2f58-81ba9a45-ab9e-4ead-85dc-8bf25de2c690.png" />
    </Frame>

    <Frame caption="创建商品定价">
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/de93b89d-f4ba26ba606fced1dcd1d319da0169296f9a2056408de3cd5bc15976-output.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=f0f43fa5826422ae1802b0c0588feab0" width="1914" height="854" data-path="images/de93b89d-f4ba26ba606fced1dcd1d319da0169296f9a2056408de3cd5bc15976-output.png" />
    </Frame>
  </Step>

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

  <Step title="提供 webhook 通知地址">
    创建一个事件接收地址，以接收您账户上发生的事件。当有事件发生时，Subotiz 会发送 HTTPS POST 请求将 [Webhook](/zh/webhook/introduction-2) 事件通知到该端点，请求体内容是 JSON 格式的事件对象。您可以通过关注事件来同步变更您系统的业务数据。
  </Step>

  <Step title="提供创建 Checkout Session 的入口">
    您的系统客户端中需要提供一个用于发起结账的入口，例如在订单预览页的结账按钮。当客户点击按钮时，在您的服务端应该调用 [Subotiz API ](/zh/api/introduction-1)创建 [Checkout Session ](/zh/api/v1-checkout-session-create-checkout-session)，并根据订单信息修改调用参数，创建 Checkout Session 时传入的参数决定客户在结账页看到的内容，例如：商品信息、订单价格等。待接口响应后，将客户重定向到 Subotiz 结账页。

    #### Hosted 模式创建 Checkout Session 示例

    ```bash theme={null}
    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":           "zhangsan@subotiz.com",
        "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 页面支付成功之后跳转的页面

    <Frame caption="示例结账页面">
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/2e9cbd86-c11fee2d8c380ec87af075e9b36cdb449982f9da05dbe874c11e5c5e-20250911-194207.jpeg?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=e4fca732739f104d1b0295670433fb99" width="1137" height="713" data-path="images/2e9cbd86-c11fee2d8c380ec87af075e9b36cdb449982f9da05dbe874c11e5c5e-20250911-194207.jpeg" />
    </Frame>

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