本教程介绍了如何使用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续订的后端支付流程。按照详细步骤操作集成,您将获得在自己的系统中高效处理交易的技术能力。这将使您能够加速收入周期、降低开发成本,并提供无摩擦的支付体验,从而将我们的支付网关转化为您平台的竞争优势。