本教程介绍了如何使用Subotiz的支付引擎完成首次订阅、一次性支付和订阅续订的后端流程，还为您提供了将嵌入式支付表单集成到您的平台的分步操作指南。
嵌入式支付流程
-
当客户准备完成购买时，从您的客户端（client）向您的服务器（server）发起结账请求。您的服务器应使用Subotiz API创建一个结账会话 (Checkout session)，并在创建Session时将
order_id（您平台的唯一订单标识符）作为参数传递，以便后续关联交易订单。 -
结账会话 (Checkout session)会返回一个会话ID（Session ID），您的客户端可以使用SDK来调用Subotiz支付表单，并向客户显示。
-
客户在Subotiz表单中输入其支付详细信息并完成交易。
- 交易完成后，Subotiz将通过Webhook通知您的服务端。此通知包含支付成功事件，该事件中包含在会话创建期间传递的
order_id，使您能够将您平台的订单与Subotiz的交易订单关联起来。
嵌入式支付时序图
订阅续订的支付流程
Subotiz支持订阅续费支付。客户完成首次支付后，系统会生成支付凭证（Token）。后续该客户产生的订阅费用可以使用这些支付凭证进行扣费，无需客户重新填写支付详情信息。
续订流程：
-
用户完成首次支付后，保存支付成功事件（trades.succeeded）中的
payment_token数据，用于发起续订扣费。 -
使用 Subotiz API 中的创建交易单（Trade）接口发起扣费。
- 主动查询交易单或等待异步通知以获取支付结果，并将支付结果通知顾客
续订支付时序图
接入步骤
第一步：提供 webhook 通知地址
创建一个事件接收地址，以接收您账户上发生的事件。当有事件发生时，Subotiz 会发送 HTTPS POST 请求将 Webhook 事件通知到该端点中，请求体内容是 JSON 格式的事件对象。您可以通过关注事件来同步变更您系统的业务数据。
第二步：集成嵌入式表单
您的客户端可以使用 Subotiz SDK 集成 Subotiz Checkout。
加载Subotiz.js
<script src="https://checkout.subotiz.com/static/subotiz/v0/subotiz.js"></script>提供容器节点
<div id="your_domElement">
<!-- 结账页面将在这里显示 -->
</div>创建结账会话（Checkout session）
使用 Subotiz API 创建Checkout Session ，并将响应结果返回前端。
示例：以嵌入式模式创建结账会话：
curl --location 'https://api.subotiz.com/api/v1/session' \
--header 'Content-Type: application/json' \
--header 'Hub-Timestamp: 1755695704350' \
--header 'Hub-Access-No: 77d52a21dc032b4' \
--header 'Request-Id: dd7fb126-be31-4144-a1af-e4bf4203eb92' \
--header 'Hub-Signature: 4830f629ff065be043c4f4b2f908ef6418d18e4ef9d6a288313ded21f1b0ec13' \
--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",
"callback_url": "https://webhook.site/2c889bcb-9923-4551-909a-d827f1c326e3",
"mode": "payment", # 无商品选择 Payment 模式
"total_amount": "10", # 传入需要收款的金额，payment 模式必传
"integration_method": "embedded", # 选择嵌入式集成
"redirect_on_completion": "if_required" # 根据业务场景选择是否跳转，这里示例仅在必要的时候进行自动跳转
}'关键参数：
order_id: 您平台的内部订单 ID，用于关联后续业务数据integration_method：设置为embedded，表示使用嵌入式表单集成方法return_url：在Subotiz结账页面成功付款后，用于将客户重定向的页面- mode：选择
Payment模式 total_amount：本次结账的金额
初始化结账页面
// 通过script标签引⼊后，Subotiz会⾃动挂载到window对象
const { Subotiz } = window;
// 创建SDK实例
const subotiz = Subotiz();
// 初始化结账
const checkout = await subotiz.initEmbeddedCheckout({
fetchSessionId: async () => {
// 从服务器获取session ID
const response = await fetch('/api/session');
const data = await response.json();
return data.sessionId;
},
environment: 'TEST', // 'TEST' | 'PRODUCTION'
// 支付完成时的回调函数仅在创建Checkout Session时将`redirect_on_completion` 设置为 `if_required` 时触发。
onComplete: () => {
console.log('Payment completed!');
}
});
// 挂载到⻚⾯
checkout.mount('#your_domElement');现在，您已全面了解一次性支付、首次订阅和通过Token续订的后端支付流程。按照详细步骤操作集成，您将获得在自己的系统中高效处理交易的技术能力。这将使您能够加速收入周期、降低开发成本，并提供无摩擦的支付体验，从而将我们的支付网关转化为您平台的竞争优势。