Checkout B2C Payment Intent 指南
托管收银台、Payment Intent、Refund、Webhook 事件、状态附录和常见问题。接口细节见 API 参考。
概述
Stabo Checkout B2C Payment Intent API 面向 B2C 商户提供托管收银台能力。商户后端创建 Payment Intent 后，将客户跳转到 checkoutUrl 完成钱包支付；支付结果通过 Webhook 主动推送，商户也可以通过查询接口进行补查和对账。
通过本 API，您可以实现：
- Payment Intent 管理: 创建支付意图、查询支付详情、分页查询支付列表
- 托管收银台跳转: 使用
checkoutUrl引导客户完成钱包支付 - 退款管理: 创建退款、查询退款列表和退款详情
- 实时通知: 通过 Webhook 接收支付成功、取消等事件
- 对账补偿: 在 Webhook 异常或延迟时，通过查询接口补查最终状态
版本: v1.2
接口范围: Payment Intent、Refund、Webhook
特殊说明: 金额使用标准单位十进制字符串，时间使用带时区偏移的 ISO 8601，枚举使用大写码值。详见通用约定的数据格式。
标准支付链路
| 步骤 | 商户动作 | 结果 |
|---|---|---|
| 1 | 获取 Access Token | 获取 access_token |
| 2 | 创建 Payment Intent | 获取 checkoutUrl / clientSecret |
| 3 | 跳转托管收银台 | 客户完成钱包支付 |
| 4 | 接收 Webhook | 获得支付结果通知 |
| 5 | 主动补查 | 查询 Payment Intent / Refund 详情 |
API 一览
| 模块 | 接口 | 说明 |
|---|---|---|
| Payment Intent | POST /openapi/v1/payment-intents | 创建 Payment Intent |
| Payment Intent | GET /openapi/v1/payment-intents/{paymentIntentId} | 查询 Payment Intent 详情 |
| Payment Intent | GET /openapi/v1/payment-intents | 分页查询 Payment Intent |
| Refund | POST /openapi/v1/payment-intents/{paymentIntentId}/refunds | 创建 Refund |
| Refund | GET /openapi/v1/payment-intents/{paymentIntentId}/refunds | 分页查询 Refund |
| Refund | GET /openapi/v1/payment-intents/{paymentIntentId}/refunds/{refundId} | 查询 Refund 详情 |
| Webhook | 商户配置的 HTTPS URL | 接收 Payment Intent 与 Refund 事件 |
每个接口的参数、响应和在线调试见 API 参考。
Webhook 事件
Webhook 是商户接收支付结果的主链路，查询接口用于补偿和对账。商户应提供可公网访问的 HTTPS URL，收到通知后返回 2xx 状态码。通知机制、请求头和签名验证见 Webhook。
事件类型
| 事件类型 | 触发时机 | data.object |
|---|---|---|
checkout.payment_intent.processing | 发现链上付款，等待确认（状态 PROCESSING） | Payment Intent 对象 |
checkout.payment_intent.partially_paid | 已确认到账金额小于应付金额（状态 PARTIALLY_PAID） | Payment Intent 对象 |
checkout.payment_intent.paid | 已足额到账，等待合规检查与入账（状态 PAID） | Payment Intent 对象 |
checkout.payment_intent.succeeded | 已记入商户余额（状态 COMPLETED） | Payment Intent 对象 |
checkout.payment_intent.canceled | 已取消或已过期（状态 CANCELED） | Payment Intent 对象 |
checkout.refund.created | 退款已创建 | Refund 对象 |
checkout.refund.succeeded | 退款完成（状态 COMPLETED） | Refund 对象 |
checkout.refund.failed | 退款失败（状态 FAILED） | Refund 对象 |
事件类型 checkout.payment_intent.succeeded 对应的状态是 COMPLETED。请以 data.object.status 判断订单状态。
载荷
Payment Intent 事件的 data.object 与 GET /openapi/v1/payment-intents/{paymentIntentId} 返回的对象相同。
Refund 事件的 data.object 与查询 Refund 详情返回的对象相同。
载荷在状态变化提交后生成，反映已提交的状态。
处理建议
- 按
data.object.paymentIntentId或data.object.referenceNo更新本地订单。 - 处理逻辑必须幂等。同一事件可能重复投递。
- 未及时收到 Webhook 时，用查询接口补查。
通知示例
{
"id": "evt_1Mxxx",
"object": "event",
"type": "checkout.payment_intent.succeeded",
"created": 1778480710,
"data": {
"object": {
"paymentIntentId": "pi_MNOL0POUV8IDPXCD",
"status": "COMPLETED",
"amount": "20.00",
"currency": "USD",
"referenceNo": "ORD-20260511-0001",
"payments": [
{
"network": "Polygon",
"currency": "USDT",
"amount": "20.08",
"txHash": "0x5f2c...a91e",
"status": "CONFIRMED",
"confirmedAt": "2026-05-11T14:18:02+08:00"
}
],
"receivedAmount": "20.00",
"feeAmount": "0.30",
"refundedAmount": "0.00",
"hasRefund": false,
"completedAt": "2026-05-11T14:25:10+08:00",
"createdAt": "2026-05-11T14:12:34+08:00",
"metadata": {}
}
}
}附录
Payment Intent 状态
| 状态 | 说明 |
|---|---|
AWAITING_PAYMENT | 等待客户付款 |
PROCESSING | 已发现链上付款，等待确认 |
PARTIALLY_PAID | 已确认到账金额小于应付金额 |
PAID | 已足额到账，等待合规检查与入账 |
COMPLETED | 已记入商户余额 |
CANCELED | 已取消，含过期。原因见 cancellationReason |
Refund 状态
| 状态 | 说明 |
|---|---|
PENDING_APPROVAL | 等待运营审批 |
PROCESSING | 已审批，链上退款执行中 |
COMPLETED | 退款完成 |
FAILED | 退款失败、被拒或已取消。原因见 failureReason |
退款原因
| 枚举值 | 说明 |
|---|---|
DUPLICATE | 重复支付或重复订单 |
FRAUDULENT | 欺诈或风险原因 |
REQUESTED_BY_CUSTOMER | 客户主动要求退款 |
OTHER | 其他原因 |
错误响应
| HTTP 状态 | 说明 |
|---|---|
| 400 | 参数校验失败；资源不存在；当前资源状态不允许操作。具体原因见 message |
| 401 | 未授权或 Token 无效 |
| 500 | 服务内部错误 |
技术支持
如您在接入过程中遇到问题，可通过 Stabo 客户经理或技术支持渠道获取帮助。
常见问题
Q: Access Token 过期了怎么办？
A: Token 有效期为 2 小时。建议在应用中缓存 Token，并在过期前刷新。收到 401 错误时，重新获取 Token 即可。
Q: 如何确保 Payment Intent 或 Refund 不会重复创建？
A: 每个 POST 请求都必须提供唯一的 Idempotency-Key。同一业务请求重试时复用相同 Key，不同业务请求使用不同 Key。
Q: Webhook 通知没有收到怎么办？
A: 请检查 Webhook URL 是否正确配置且可公网访问、服务端是否返回 2xx 状态码、防火墙是否放行 Stabo 请求来源。必要时可通过查询接口补查 Payment Intent 或 Refund 状态。
Q: Payment Intent 的金额单位是什么？
A: 金额使用标准单位十进制字符串，按币种精度输出。例如 "20.00" 表示 20.00 USD，"2000" 表示 2000 JPY。请求中的小数位超出币种精度时，请求被拒绝。