前置条件

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

快速集成步骤

步骤 1：获取接入凭证

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

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

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

步骤 2：创建 Checkout Session

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

请求示例

curl --location 'https://api.stg.subotiz.com/api/v1/session' \
--header 'Content-Type: application/json' \
--header 'Hub-Timestamp: {生成签名使用的时间戳}' \
--header 'Hub-Access-No: {你的access_no}' \
--header 'Request-Id: 07949371-7868-2282-78af-2a8d5c043760' \
--header 'Hub-Signature: {生成的签名}' \
--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"
}'

签名生成说明

签名串格式：请求方法\n请求路径\n时间戳\n请求体\n

示例（POST 请求）：

func (ha *HmacAuth) CalcSignature(method string, url []byte, timestamp string, body []byte, secret string) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(method))
	mac.Write([]byte("\n"))
	mac.Write(url)
	mac.Write([]byte("\n"))
	mac.Write([]byte(timestamp))
	mac.Write([]byte("\n"))
	mac.Write(body)
	mac.Write([]byte("\n"))
	return hex.EncodeToString(mac.Sum(nil))
}

使用 access_secret 通过 HMAC-SHA256 算法生成签名，并将其填入 Hub-Signature 请求头中

示例：

func  CalcSignature(method string, url []byte, timestamp string, body []byte, secret string) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(method))
	mac.Write([]byte("\n"))
	mac.Write(url)
	mac.Write([]byte("\n"))
	mac.Write([]byte(timestamp))
	mac.Write([]byte("\n"))
	mac.Write(body)
	mac.Write([]byte("\n"))
	return hex.EncodeToString(mac.Sum(nil))
}

步骤 3：测试完成支付

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

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

支付完成后，将被重定向至return_url（成功）
同时，Subotiz 会发送 Webhook 通知（事件类型trades.succeeded）
验证 Webhook 合法性：

验证结果

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