快速入门

本指南帮助您完成 Subotiz 支付功能的基础集成——通过托管式结账页面（hosted mode）快速实现支付流程。Subotiz 提供完整的支付能力，支持订阅管理、交易处理等核心功能，适用于 AI、SaaS 等各类业务场景。

前置条件

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

集成步骤

获取接入凭证

1. 配置支付回调地址

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

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

2. 获取平台接入信息

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

获取商品信息

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

创建 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"
}'

测试完成支付

1. 获取支付页面 URL

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

2. 访问支付页面

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

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

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

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

处理支付结果通知

1. 重定向回 return_url

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

2. 接收 Webhook 通知

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

3. 验证 Webhook 签名

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

// 计算签名
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))
}

验证结果

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

快速开始

集成指南

AI 开发者

开发者资源

Webhook

前置条件

集成步骤

1. 配置支付回调地址

2. 获取平台接入信息

1. 获取支付页面 URL

2. 访问支付页面

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

1. 重定向回 return_url

2. 接收 Webhook 通知

3. 验证 Webhook 签名

验证结果

​前置条件

​集成步骤

​1. 配置支付回调地址

​2. 获取平台接入信息

​1. 获取支付页面 URL

​2. 访问支付页面

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

​1. 重定向回 return_url

​2. 接收 Webhook 通知

​3. 验证 Webhook 签名

​验证结果

前置条件

集成步骤

1. 配置支付回调地址

2. 获取平台接入信息

1. 获取支付页面 URL

2. 访问支付页面

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

1. 重定向回 return_url

2. 接收 Webhook 通知

3. 验证 Webhook 签名

验证结果