> ## 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 支持通过嵌入式表单（embedded 模式）完成结账流程。提供低代码支付集成方案，可便捷创建可定制的支付表单，助您快速完成支付流程。

## 场景演示

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

如果您需要完整的商品管理、定价与支付能力，请前往 [嵌入式结账模式](/zh/integration/embedded-form)。

#### 嵌入完整 Checkout 页面

<Frame caption="嵌入完整页面演示图">
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/fc2ab2ba-f0ef1c2281f598acf91c604aeeeb31890616d74c130c5ca7ea3dd3dc-Snipaste_2025-09-11_20-23-58.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=3801d6296c22cbb94acb5ce193b53565" width="1074" height="849" data-path="images/fc2ab2ba-f0ef1c2281f598acf91c604aeeeb31890616d74c130c5ca7ea3dd3dc-Snipaste_2025-09-11_20-23-58.png" />
</Frame>

#### 嵌入部分组件元素

<Frame caption="嵌入部分组件元素演示图">
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/33d02bc4-e8f34973c08c35d263f4a2c7c08d1a44cf4df4654bb4dc7e46a60b2b-Snipaste_2025-09-11_20-15-28.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=085247067c31abc09a51655837458bdd" width="781" height="826" data-path="images/33d02bc4-e8f34973c08c35d263f4a2c7c08d1a44cf4df4654bb4dc7e46a60b2b-Snipaste_2025-09-11_20-15-28.png" />
</Frame>

## 支付流程

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

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

## 接入步骤

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

  <Step title="集成嵌入式表单">
    您的客户端可以使用 [Subotiz SDK](/zh/resources/subotiz-sdk) 集成 Subotiz Checkout。

    #### 1. 加载 Subotiz.js

    ```html theme={null}
    <script src="https://checkout.subotiz.com/static/subotiz/v0/subotiz.js"></script>
    ```

    #### 2. 提供容器节点

    ```html theme={null}
    <div id="your_domElement">
        <!-- 结账页面将在这里显示 -->
    </div>
    ```

    #### 3. 创建 Checkout Session

    使用 [Subotiz API ](/zh/api/introduction-1)创建[Checkout Session ](/zh/api/v1-checkout-session-create-checkout-session) ，并将响应结果返回前端。

    **embedded 模式创建 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: 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":           "zhangsan@subotiz.com",
            "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. 初始化结账页面

    ```javascript theme={null}
    // 通过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');
    ```
  </Step>
</Steps>

## 续订收费

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

#### 续订流程

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

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