快速入门

前置条件

已注册 Subotiz 商户账号（注册地址）
完成 Subotiz 支付入网及支付方式配置
完成商品和定价创建

快速集成步骤

步骤 1：获取接入凭证

登录 Subotiz 管理平台
配置支付回调地址
- return_url：客户支付成功之后跳转的 URL，创建 checkout session 时的默认值
- cancel_url：客户取消支付之后跳转的 URL，创建 checkout session 时的默认值

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

获取平台提供的接入信息：
- access_no：接入方唯一识别号
- merchant_id：商户唯一标识
- API Key：API 鉴权密钥，获取方式参阅鉴权（严格保密，勿暴露在客户端）

步骤 2：获取商品信息

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

创建商品：

创建商品定价：

步骤 3：创建 Checkout Session

通过 API 创建结账会话，获取支付页面 URL，引导用户完成支付。

请求示例

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": "[email protected]",
  "line_items": [
    {
      "price_id": "{商品定价ID}",
      "quantity": "1"
    }
  ],
  "return_url": "https://your-app.com/success",
  "cancel_url": "https://your-app.com/cancel"
}'

步骤 4：测试完成支付

接口响应成功后，获取data.session_url（支付页面 URL）
在浏览器中访问该链接，将看到 Subotiz 托管的支付页面
使用测试卡号完成支付测试：（Subotiz Payment 支付渠道）
- 支付成功：使用卡号4242424242424242，CVC 为任意 3 位，有效期需为未来日期
- 支付失败：使用卡号4000000000000002，CVC 为任意 3 位，有效期需为未来日期

步骤 5：处理支付结果通知

支付完成后，将被重定向至return_url（成功）
同时，Subotiz 会发送 Webhook 通知（事件类型trades.succeeded）
验证 Webhook 合法性：
1. 提取参数：从请求头获取 X-Timestamp 时间戳（记为timestamp），并获取原始请求体内容（记为body）；
2. 构造签名原串：格式为${timestamp}.${body}；
3. 计算签名：使用 Subotiz 分配的 API Key 作为密钥，通过 HMAC-SHA256 算法计算签名值；
```
  // 计算签名
  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))
  }
```
4. 比对验证：将计算得到的签名与请求头中的 X-Signature 值比对，一致则为合法请求。

验证结果

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