> ## 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 mode](/zh/integration/hosted)）快速实现支付流程。Subotiz 提供完整的支付能力，支持订阅管理、交易处理等核心功能，适用于 AI、SaaS 等各类业务场景。

## 前置条件

1. 已注册 Subotiz 商户账号（<a href="https://admin.subotiz.com/" target="_blank">注册地址</a>）
2. 完成 Subotiz 支付入网及支付方式配置
3. 完成商品和定价创建

## 集成步骤

<Steps>
  <Step title="获取接入凭证">
    登录 [Subotiz 管理平台](https://admin.subotiz.com/)，完成以下两项配置：

    #### 1. 配置支付回调地址

    * `return_url`：客户支付成功之后跳转的 URL，创建 checkout session 时的默认值
    * `cancel_url`：客户取消支付之后跳转的 URL，创建 checkout session 时的默认值

    <Info>
      优先级规则：创建会话时传入的地址将覆盖此处的默认设置。为确保灵活性，建议在此设置通用默认地址，并在特定场景下通过 API 传入自定义地址。
    </Info>

    <Frame>
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/b04db868-d1f6e3f9f64988c937604ed58a416d9798a0f0daef1783aebc3671cc-image.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=d950fc40c1c8b0d72ac2bf8e2adcfa18" width="1917" height="806" data-path="images/b04db868-d1f6e3f9f64988c937604ed58a416d9798a0f0daef1783aebc3671cc-image.png" />
    </Frame>

    #### 2. 获取平台接入信息

    * `access_no`：接入方唯一识别号
    * `merchant_id`：商户唯一标识
    * `API Key`：API 鉴权密钥，获取方式参阅 [鉴权](/zh/api/authentication-1)（**严格保密，勿暴露在客户端**）

    <Frame>
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/cc21b08b-b15eb3371e91b2d199fd99e49e61fa71da307d85974af35d88918ce9-image.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=89e21a37afa43fb2a2e1f604c461d15f" width="1914" height="744" data-path="images/cc21b08b-b15eb3371e91b2d199fd99e49e61fa71da307d85974af35d88918ce9-image.png" />
    </Frame>
  </Step>

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

    <Frame caption="创建商品">
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/919226c2-4a27220aee724032220c3ae62529bca50bbe65b8b0b3fc4c14ade6f3-image.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=19126fd7b7251751bc035017301efb77" width="1917" height="806" data-path="images/919226c2-4a27220aee724032220c3ae62529bca50bbe65b8b0b3fc4c14ade6f3-image.png" />
    </Frame>

    <Frame caption="创建商品定价">
      <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/ce7beb96-3a4a97253f27264d7af270661a6a0fddb7a9368aed9bbaff6e4ab179-image.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=62ece1790f8329fe876bd8f1b61a2afc" width="1895" height="795" data-path="images/ce7beb96-3a4a97253f27264d7af270661a6a0fddb7a9368aed9bbaff6e4ab179-image.png" />
    </Frame>
  </Step>

  <Step title="创建 Checkout Session">
    通过 API 创建结账会话，获取支付页面 URL，引导用户完成支付。

    **请求示例：**

    ```bash theme={null}
    curl --location 'https://api.sandbox.subotiz.com/api/v1/session' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {your_api_key}' \
    --header 'Request-Id: 07949371-7868-2282-78af-2a8d5c043760' \
    --data-raw '{
      "access_no": "{您的access_no}",
      "sub_merchant_id": "{您的merchant_id}",
      "order_id": "test_order_001",
      "email": "customer@example.com",
      "line_items": [
        {
          "price_id": "{商品定价ID}",
          "quantity": "1"
        }
      ],
      "return_url": "https://your-app.com/success",
      "cancel_url": "https://your-app.com/cancel"
    }'
    ```
  </Step>

  <Step title="测试完成支付">
    #### 1. 获取支付页面 URL

    接口响应成功后，取 `data.session_url`（支付页面 URL）。

    #### 2. 访问支付页面

    在浏览器中打开该链接，即可看到 Subotiz 托管的支付页面。

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

    #### 3. 使用测试卡号完成支付

    使用测试卡号完成支付（Subotiz Payment 渠道）：

    * 支付成功：卡号 `4242424242424242`，CVC 为任意 3 位，有效期需为未来日期
    * 支付失败：卡号 `4000000000000002`，CVC 为任意 3 位，有效期需为未来日期
  </Step>

  <Step title="处理支付结果通知">
    #### 1. 重定向回 return\_url

    支付完成后，用户被重定向至 `return_url`（成功场景）。

    #### 2. 接收 Webhook 通知

    Subotiz 同时发送 Webhook 通知（事件类型 `trades.succeeded`）。

    #### 3. 验证 Webhook 签名

    1. **提取参数**：从请求头获取 X-Timestamp 时间戳（记为 `timestamp`），并获取原始请求体内容（记为 `body`）。
    2. **构造签名原串**：格式为 `${timestamp}.${body}`。
    3. **计算签名**：使用 Subotiz 分配的 `API Key` 作为密钥，通过 HMAC-SHA256 算法计算签名值（示例见下）。
    4. **比对验证**：将计算得到的签名与请求头中的 X-Signature 值比对，一致则为合法请求。

    ```go theme={null}
    // 计算签名
    func CalcSignature(timestamp int64, body []byte, secret string) string {
        mac := hmac.New(sha256.New, []byte(secret))
        mac.Write([]byte(fmt.Sprintf("%d", timestamp)))
        mac.Write([]byte("."))
        mac.Write(body)
        return hex.EncodeToString(mac.Sum(nil))
    }
    ```
  </Step>
</Steps>

## 验证结果

1. 登录 Subotiz 管理平台，查看交易记录和订阅记录
2. 验证订单金额、商品信息是否正确