场景演示

本页介绍如何使用支付模式，即仅调用 Subotiz 的支付引擎，自行构建前端界面与业务逻辑。

如果您需要完整的商品管理、定价与支付能力，请前往嵌入式结账模式。

嵌入完整checkout页面

嵌入部分组件元素

支付流程

当客户准备完成购买时，从您的客户端（client）向您的服务端（server）发起结账请求。您的服务端应使用 Subotiz API 创建一个 Checkout Session，并在创建 Session 时以参数形式传入 order_id（接入方订单 ID，业务唯一），以便后续关联交易单。
Checkout Session 会提供一个 Session ID，您的客户端可使用 SDK 唤起 Subotiz 的支付表单并展示给客户。
客户会在 Subotiz 表单中输入支付信息并完成交易。
交易完成后，Subotiz 会以 webhook 方式通知您的服务端，通知包含支付成功事件，该事件中包含创建 session 时传入的 order_id，借此可关联接入方订单和 Subotiz 的交易单。

sequenceDiagram
    participant Customer as 顾客
    participant Client as Merchant Client
    participant Server as Merchant Server
    participant SubotizAPI as Subotiz API

    Customer->>Client: 1. 发起订单
    Client->>Server: 2. 获取 session ID
    Server->>SubotizAPI: 3. 创建 Checkout Session
    SubotizAPI-->>Server: 4. 返回session 信息
    Server-->>Client: 5. 返回 session id
    Client->>Client: 6. 使用 SDK 唤起表单
    Client-->>Customer: 7. 展示支付表单
    Customer->>Client: 8. 填写支付信息并确认
    Client->>Client: 9. 处理支付
    Client-->>Customer: 10. 返回支付结果
    SubotizAPI->>Server: webhook 通知支付结果

接入步骤

第一步：提供 webhook 通知地址

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

第二步：集成嵌入式表单

您的客户端可以使用 Subotiz SDK 集成 Subotiz Checkout。

1. 加载Subotiz.js

<script src="https://checkout.subotiz.com/static/subotiz/v0/subotiz.js"></script>

2. 提供容器节点

<div id="your_domElement">
    <!-- 结账页面将在这里显示 -->
</div>

3. 创建 Checkout Session

使用 Subotiz API 创建Checkout Session ，并将响应结果返回前端。

embedded 模式创建 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: dd7fb126-be31-4144-a1af-e4bf4203eb92' \
--data-raw '{
        "access_no":       "77d52a21dc032b4",
        "sub_merchant_id": "2816433",
        "order_id":        "123e4567-e89b-12-a456-426622201a",
        "payer_id": "customer_id_001",
        "customer_id":     "",
        "email":           "[email protected]",
        "return_url":   "https://www.subotiz.com",
        "cancel_url":   "https://www.subotiz.com",
        "mode": "payment",            # 无商品选择 payment 模式
        "total_amount": "10",         # 传入需要收款的金额，payment 模式必传
        "integration_method": "embedded",    # 选择嵌入式集成
        "redirect_on_completion": "if_required" # 根据业务场景选择是否跳转，这里示例仅在必要的时候进行自动跳转
    }'

关键参数：

order_id：为接入方订单 ID，用于后续关联业务数据
integration_method：设置为 embedded，表示使用嵌入式模式接入
return_url：客户在 Subotiz Checkout 页面支付成功之后跳转的页面
mode：选择 payment 模式
total_amount：本次结账的金额

4. 初始化结账页面

// 通过script标签引⼊后，Subotiz会⾃动挂载到window对象
const {
    Subotiz
} = window;
// 创建SDK实例
const subotiz = Subotiz();
// 初始化结账
const checkout = await subotiz.initEmbeddedCheckout({
    fetchSessionUrl: async() => {
        // 从服务器获取sessionId
        const response = await fetch('/api/session');
        const data = await response.json();
        return data.sessionUrl;
    },
    environment: 'SANDBOX', // 'SANDBOX' | 'PRODUCTION'
		// 支付完成时的回调函数仅在创建Checkout Session时将`redirect_on_completion` 设置为 `if_required` 时触发。
    onComplete: () => {
        console.log('⽀付完成！');
    }
});
// 挂载到⻚⾯
checkout.mount('#checkout-container');

续订收费

Subotiz 支持续订付款功能。用户完成首次支付后，系统将生成支付凭证，后续该用户产生的订阅费用可使用此支付凭证进行扣费，无需用户重新填写支付信息。

续订流程：

用户完成首次支付后，保存支付成功事件（trades.succeeded）中的 payment_token 数据，用于发起续订扣费。
使用 Subotiz API 中的创建交易单（Trade）接口发起扣费。
主动查询交易单或等待异步通知以获取支付结果，并将支付结果通知顾客。

sequenceDiagram
    participant Customer as 顾客
    participant AccessSystem as 接入方系统
    participant Subotiz as Subotiz

    Customer->>AccessSystem: 1. 完成首次支付
    Subotiz->>AccessSystem: 2. webhook 通知支付结果
    AccessSystem->>AccessSystem: 3. 保存支付结果
    Customer->>AccessSystem: 4. 续订支付
    AccessSystem->>Subotiz: 5. 创建交易单发起支付
    Subotiz->>AccessSystem: 6. 返回提交支付结果
    AccessSystem->>Subotiz: 7. 查询交易单获取支付结果
    Subotiz->>AccessSystem: 8. 返回支付结果
    AccessSystem->>Customer: 9. 通知支付结果
    Subotiz->>AccessSystem: webhook 通知支付结果