Checkout 收款
接入前请查看接口开放状态,并在目标环境确认账户权限。
| 操作 | 方法与路径 | 开放状态 |
|---|---|---|
| 创建 Checkout | POST /v1/checkouts | 商户路由已确认 |
| 查询 Checkout | GET /v1/checkouts/{id} | 商户路由已确认 |
| 列出 Checkout | GET /v1/checkouts | 商户路由已确认 |
| 关闭 Checkout | POST /v1/checkouts/{id}/close | 商户路由已确认 |
| 查询付款明细 | GET /v1/checkouts/{id}/payments | 开放待确认 |
Checkout 表示一次收款会话。商户创建 Checkout 后,将返回的 url 展示给付款人;付款人在平台收银台选择付款网络并完成支付。商户通过服务端查询获取支付结果;Webhook 开放后可用于触发查询,无需管理底层付款尝试。
通用规则遵循商户 API 通用约定。
商户可用的币种与网络组合见商户收款方式 API;付款明细与退款见商户退款 API,通知接收及签名验证见商户 Webhook API。
Checkout Object
Attributes
| 属性 | 类型 | 说明 |
|---|---|---|
id | string | Checkout 的唯一标识 |
amount | string | 应收金额 |
currency | string | 收款币种:usdc、usdt |
transaction_speed | string | 支付确认速度:high、medium、low,默认 low,见下文 |
status | string | 会话主状态:open、processing、succeeded、failed,见下文 |
failure_reason | string / null | 结束原因:expired、closed;仅 failed 时有值,其他状态为 null |
exception_status | string / null | 当前资金异常:paidOver、paidPartial;无异常时为 null |
order_id | string / null | 商户订单号,不要求唯一;未设置时为 null |
description | string / null | 展示给付款人的收款说明;未设置时为 null |
metadata | object | 商户自定义的字符串键值对;无内容时为 {}。最多 50 对,键最长 40 个字符,值最长 500 个字符 |
url | string | 平台收银台地址;会话结束后仍可打开查看结果 |
return_url | string / null | 收银台“返回商户”按钮的目标地址;未设置时为 null,不显示该按钮 |
expires_at | string | 到期时间,创建时确定;未指定时为创建成功后 30 分钟 |
created_at | string | 创建时间 |
updated_at | string | 对外可见信息最后变化的时间,包括主状态及资金异常变化 |
Checkout 创建后不提供更新接口。重新打开页面、切换付款网络或重试,不延长有效期。
status
| 值 | 含义 |
|---|---|
open | 等待付款;尚未检测到付款上链时,付款人可选择或切换网络 |
processing | 已检测到付款上链,等待达到指定确认要求;收银台展示进度,不引导继续付款 |
succeeded | 平台在到期或主动关闭前已确认付款达到指定的 transaction_speed;履约前还须检查 exception_status,结合异常及订单规则判断是否履约 |
failed | 主动关闭或时间到期时仍未达到确认要求,本次收款会话结束;不表示付款人没有付出资金 |
切换网络后,仅当前付款尝试可以使会话成功;旧付款信息收到的资金按异常收款处理,不阻止当前付款。确认中的付款失效且会话尚未结束时,可恢复为 open,由付款人继续操作。
succeeded、failed 为终态,不因后续到账、退款或资金失效而翻转,也不再开放付款。已失败的会话后续收到到账或确认消息时,按资金异常处理,不追溯改为支付成功。结果以平台在到期或主动关闭前完成的确认判定为准。
failure_reason
| 值 | 含义 |
|---|---|
expired | 时间到期时仍未达到指定确认要求 |
closed | 商户服务端主动关闭时仍未达到指定确认要求 |
付款人关闭页面或返回商户网站不结束会话;尚未结束且仍在有效期内,可通过原 url 恢复付款或查看确认进度。
transaction_speed
用于选择何时将 Checkout 标记为 succeeded。确认越快,后续付款失效的风险越高;商户可根据商品或服务的追回难度选择,并在发生资金缺失异常时按订单规则处理。
| 值 | 含义 |
|---|---|
high | 快速:付款交易成功执行并进入区块(区块打包) |
medium | 标准:付款所在区块达到安全确认高度(safe) |
low | 稳妥:付款所在区块达到最终确认高度(finalized),默认值 |
有效期包含付款及等待确认的时间。即使付款已经上链,结束时仍未达到所选确认要求,也会进入 failed。
exception_status
主状态与资金异常独立。异常表达当前资金情况,不表示人工处理进度;商户应结合当前异常和订单履约情况处理,不仅根据主状态判断。
| 值 | 含义 |
|---|---|
null | 当前无资金异常,包括尚未付款 |
paidOver | 存在额外到账且尚未退净的资金,例如重复付款或会话失败后的到账 |
paidPartial | 已认定的正常收款资金因链上回滚、确认度下降等原因不再满足收款要求 |
首次成功认定的正常付款来源固定。该笔付款失效后,其他到账不能替代它;原付款恢复到指定确认要求时,可清除缺款异常。缺款与额外到账同时存在时,优先显示 paidPartial。
成功会话的额外资金全部退款成功后,可清除 paidOver;失败会话则需全部到账资金退款成功。退款处理中仅占用额度,不提前清除多收异常。正常售后退款相应减少需保留的正常款金额,本身不产生 paidPartial。
资金异常出现、变化或清除通过 checkout.exception_updated 通知商户;异常类型不变但异常资金情况发生变化时,也会通知。异常清除不改变会话主状态,也不代表商户的订单或售后事项已经处理完成。
url 与 return_url
url 仅提供收银台入口,不返回二维码。会话成功或失败后,原页面展示结果;存在资金异常时展示相应提示,不再引导付款。
return_url 仅用于“返回商户”按钮,不自动跳转。返回行为不改变支付状态;商户应通过服务端查询或 Webhook 确认支付结果,不将返回页面作为付款成功凭据。
对象示例
{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "open",
"failure_reason": null,
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:00:00Z"
}
创建 Checkout
POST /v1/checkouts
创建一次收款会话,返回状态为 open 的 Checkout。将 url 展示给付款人即可开始付款;付款人选择网络后,由收银台准备付款信息,商户无需额外确认。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 本次操作的唯一键;重试沿用原值 |
amount | body | string | 是 | 应收金额 |
currency | body | string | 是 | 收款币种:usdc、usdt |
transaction_speed | body | string | 否 | high、medium、low,默认 low |
expires_at | body | string | 否 | 到期时间,须晚于平台创建会话的时刻;默认创建成功后 30 分钟 |
order_id | body | string | 否 | 商户订单号,不要求唯一;同一订单可创建多个 Checkout |
description | body | string | 否 | 展示给付款人的收款说明 |
metadata | body | object | 否 | 商户自定义信息,限制见 Checkout Object |
return_url | body | string | 否 | 收银台“返回商户”按钮的目标地址 |
同一订单创建多个 Checkout 时,各会话独立。商户应保存订单与 Checkout 的关联,并按订单保证履约不重复。
请求示例
POST /v1/checkouts
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"amount": "10",
"currency": "usdc",
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"return_url": "https://merchant.example.com/orders/ORDER_001"
}
返回示例
200 OK,返回完整的 Checkout 对象。
{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "open",
"failure_reason": null,
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:00:00Z"
}
查询 Checkout
GET /v1/checkouts/{id}
查询会话的当前状态及资金异常,可用于轮询支付结果、页面恢复和 Webhook 回查。不返回付款明细。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
id | path | string | 是 | Checkout 的唯一标识 |
请求示例
GET /v1/checkouts/checkout_example
Authorization: Bearer inv_test_...
返回示例
200 OK,返回完整的 Checkout 对象。
{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "succeeded",
"failure_reason": null,
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:02:00Z"
}
列出 Checkout
GET /v1/checkouts
查询当前商户的会话列表,按创建时间倒序排列,创建时间相同时按 ID 倒序排列。多个筛选条件同时生效。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
order_id | query | string | 否 | 商户订单号,精确匹配,可返回多个 Checkout |
status | query | string | 否 | open、processing、succeeded、failed |
has_exception | query | boolean | 否 | true 仅返回有资金异常的会话,false 仅返回无异常的会话;不传则不限 |
created_from | query | string | 否 | 创建时间起点,包含 |
created_to | query | string | 否 | 创建时间终点,不包含 |
page_size | query | integer | 否 | 每页数量,默认 20,范围 1–100 |
page_token | query | string | 否 | 上一页返回的 next_page_token;第一页不传 |
请求示例
GET /v1/checkouts?order_id=ORDER_001&status=succeeded&page_size=20
Authorization: Bearer inv_test_...
返回示例
200 OK,data 中每项均为完整的 Checkout 对象,不附带付款明细。
{
"data": [
{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "succeeded",
"failure_reason": null,
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:02:00Z"
}
],
"next_page_token": ""
}
关闭 Checkout
POST /v1/checkouts/{id}/close
仅允许商户服务端主动关闭会话,请求体为 {}。
open、processing:进入failed,failure_reason=closed。- 已
failed:返回当前对象,不修改原失败原因。 - 已
succeeded:拒绝关闭,返回400 checkout_invalid_state。
关闭后仍识别后续到账,但按资金异常处理,不重新开放付款,也不转为成功。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 本次操作的唯一键;重试沿用原值 |
id | path | string | 是 | Checkout 的唯一标识 |
请求示例
POST /v1/checkouts/checkout_example/close
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: ec3a7e90-673e-41a1-94d0-6724fba6a339
{}
返回示例
200 OK,返回完整的 Checkout 对象。
{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "failed",
"failure_reason": "closed",
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:05:00Z"
}
查询付款明细
本节为接口约定,开放状态尚待确认。当前收款结果应通过服务端查询 Checkout 核对。
GET /v1/checkouts/{id}/payments
返回会话下已检测到到账的付款项,不展示尚未付款的尝试。字段定义见付款明细。
同一付款项重复到账时更新累计金额,不同付款项分别展示。主状态已成功或失败时,历史付款及后续到账仍可查询。明细按创建时间倒序排列,创建时间相同时按 attempt_id 倒序排列。
尚未最终确认的到账不计入 amount_received 或可退款金额;已检测到付款但尚未最终确认时,金额可以为 "0"。创建退款时平台重新校验可退款额度。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
id | path | string | 是 | Checkout 的唯一标识 |
page_size | query | integer | 否 | 每页数量,默认 20,范围 1–100 |
page_token | query | string | 否 | 上一页返回的 next_page_token;第一页不传 |
请求示例
GET /v1/checkouts/checkout_example/payments?page_size=20
Authorization: Bearer inv_test_...
返回示例
200 OK,返回付款明细列表。商户选择 attempt_id 后,通过创建退款指定退款金额。
{
"data": [
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount_received": "10",
"amount_refunded": "0",
"amount_refundable": "10",
"currency": "usdc",
"chain": 56
}
],
"next_page_token": ""
}
尚未检测到到账时,返回 {"data":[],"next_page_token":""}。
Checkout Webhook 事件
本节为接口约定,开放状态尚待确认。当前收款结果应通过服务端查询 Checkout 核对。
平台通过已配置的通知端点发送轻量事件。事件的 related_object.type 为 checkout,related_object.id 为会话标识;商户通过查询 Checkout获取当前状态。
type | 触发条件 |
|---|---|
checkout.succeeded | 会话首次进入 succeeded |
checkout.failed | 会话首次进入 failed |
checkout.exception_updated | 资金异常出现、类型变化、清除,或异常资金情况发生变化 |
每个 Checkout 只产生一次成功或失败事件;后续资金变化不再次产生终态事件。网络切换、付款尝试创建和确认进度不发送商户事件。
异常类型未变化,但新增异常到账、成功退款使待退异常金额减少,或付款资金失效、恢复时,仍会产生 checkout.exception_updated。退款处理中仅占用额度,不提前视为异常资金已退回;相同资金事实的重复处理不产生新事件。
事件示例
{
"id": "evt_example",
"type": "checkout.succeeded",
"related_object": {
"id": "checkout_example",
"type": "checkout"
},
"created_at": "2026-10-28T08:02:00Z"
}
通知可能重复或乱序到达。商户按事件 id 去重通知,回查会话确认当前状态,并按订单防止重复履约。成功事件到达时仍须检查当前 exception_status,不能仅凭事件类型履约。
签名、接收及投递规则见商户 Webhook API。
错误码
error.code | HTTP 状态码 | 含义 | 适用接口 |
|---|---|---|---|
checkout_not_found | 404 | 会话不存在或无权访问 | 查询、关闭、查询付款明细 |
checkout_invalid_state | 400 | 当前状态不允许操作,例如关闭已成功的会话 | 关闭 |