在本教程中，我们将了解后端的嵌入式结账流程以及逐步的集成指南，包括如何初始化 Subotiz.js、透传设置和商品信息，以及更新页面信息。
结账流程
- 当客户准备完成购买时，会从您的客户端（Client）应用程序向您的服务端（Server）发起结账请求。您的服务端应使用Subotiz API创建一个结账会话 (Checkout Session)，并在创建过程中传递您平台的唯一业务标识符（
order_id）作为参数。这个order_id对于后续关联交易订单至关重要。 - 结账会话提供一个会话ID (Session ID)。然后，您的客户端应用程序可以使用SDK来调用并向客户显示Subotiz支付表单。
- 客户将在Subotiz表单中输入支付信息并完成交易。
-
交易完成后，Subotiz将通过Webhook向您的服务器发送通知。此通知包括支付成功事件，其中包含会话创建期间最初传递的
order_id。这允许您将平台的订单与Subotiz的交易订单相关联。
嵌入式结账时序图
开始之前
创建商品和定价
在 Subotiz 管理平台中创建商品和商品定价，将商品信息和价格信息保存在服务端中。结账会话会使用商品定价的
pricing_id来动态获取商品信息，因此你需要创建一个商品和至少一个相关的商品定价，以便将这些信息透传到结账页面中。
-
创建商品：
- 创建商品定价：
提供支付成功页面
- 您的程序需要提供一个公开可访问的页面（ return-url），以便在支付成功后显示。客户完成支付后，Subotiz 将把他们重定向到这个页面。
- 同时，商家也可以根据自己的需求自定义成功流程。只有在创建结账会话期间将
redirect_on_completion设置为if_required时，回调函数才会自动触发。Subotiz将回调此函数，允许商家自定义自己的成功流程。这样，客户可以在不自动重定向的情况下进入支付成功页面。
提供Webhook通知地址
创建一个事件接收地址来接收您账户的事件。当事件发生时，Subotiz将向此Webhook地址发送一个包含JSON格式事件对象的HTTPS POST请求。您可以关注这些事件来保持您系统的业务数据同步。
接入步骤
您的客户端可以使用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创建结账会话，并将响应返回给前端。
- 示例 1：创建包含商品的结账会话
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",
"line_items": [ # 商品信息，checkout 模式必传
{
"price_id": "543321366326164797",
"quantity": "1"
}
],
"return_url": "https://www.subotiz.com",
"cancel_url": "https://www.subotiz.com",
"callback_url": "https://webhook.site/2c889bcb-9923-4551-909a-d827f1c326e3",
"mode": "checkout", # 有商品选择 checkout 模式
"integration_method": "embedded", # 选择嵌入式集成
"redirect_on_completion": "if_required" # 根据业务场景选择是否跳转，这里示例仅在必要的时候进行重定向
}'关键参数：
order_id：您平台的内部订单ID，用于关联后续业务数据integration_method：设置为embedded以使用嵌入式表单集成模式return_url：客户成功付款后重定向到的 URL。mode：有商品数据时，选择Checkout模式。
- 示例2：创建无商品/定价的结账会话
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" # 根据业务场景选择是否跳转，这里示例仅在必要的时候进行自动跳转
}'初始化结账页面
// 通过script标签引入后，Subotiz会自动挂载到window对象
const { Subotiz } = window;
// 创建SDK实例
const subotiz = Subotiz();
// 初始化结账
const checkout = await subotiz.initEmbeddedCheckout({
fetchSessionId: async () => {
// 从你的服务器获取sessionId
const response = await fetch('/api/session');
const data = await response.json();
return data.sessionId;
},
environment: 'TEST', // 'TEST' | 'PRODUCTION'
onComplete: () => {
console.log('支付完成！');
}
});
// 挂载到页面
checkout.mount('#your_domElement');按照上述指南集成Subotiz嵌入式结账页，即可为您的数字产品和服务实现线上收款。它通过避免重定向来减少弃单率，能完全掌控客户体验，将支付转化为竞争优势。