跳到主要内容

Checkout 收款

接入前请查看接口开放状态,并在目标环境确认账户权限。

操作方法与路径开放状态
创建 CheckoutPOST /v1/checkouts商户路由已确认
查询 CheckoutGET /v1/checkouts/{id}商户路由已确认
列出 CheckoutGET /v1/checkouts商户路由已确认
关闭 CheckoutPOST /v1/checkouts/{id}/close商户路由已确认
查询付款明细GET /v1/checkouts/{id}/payments开放待确认

Checkout 表示一次收款会话。商户创建 Checkout 后,将返回的 url 展示给付款人;付款人在平台收银台选择付款网络并完成支付。商户通过服务端查询获取支付结果;Webhook 开放后可用于触发查询,无需管理底层付款尝试。

通用规则遵循商户 API 通用约定。

商户可用的币种与网络组合见商户收款方式 API;付款明细与退款见商户退款 API,通知接收及签名验证见商户 Webhook API。

Checkout Object​

Attributes​

属性类型说明
idstringCheckout 的唯一标识
amountstring应收金额
currencystring收款币种:usdc、usdt
transaction_speedstring支付确认速度:high、medium、low,默认 low,见下文
statusstring会话主状态:open、processing、succeeded、failed,见下文
failure_reasonstring / null结束原因:expired、closed;仅 failed 时有值,其他状态为 null
exception_statusstring / null当前资金异常:paidOver、paidPartial;无异常时为 null
order_idstring / null商户订单号,不要求唯一;未设置时为 null
descriptionstring / null展示给付款人的收款说明;未设置时为 null
metadataobject商户自定义的字符串键值对;无内容时为 {}。最多 50 对,键最长 40 个字符,值最长 500 个字符
urlstring平台收银台地址;会话结束后仍可打开查看结果
return_urlstring / null收银台“返回商户”按钮的目标地址;未设置时为 null,不显示该按钮
expires_atstring到期时间,创建时确定;未指定时为创建成功后 30 分钟
created_atstring创建时间
updated_atstring对外可见信息最后变化的时间,包括主状态及资金异常变化

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-Keyheaderstring是本次操作的唯一键;重试沿用原值
amountbodystring是应收金额
currencybodystring是收款币种:usdc、usdt
transaction_speedbodystring否high、medium、low,默认 low
expires_atbodystring否到期时间,须晚于平台创建会话的时刻;默认创建成功后 30 分钟
order_idbodystring否商户订单号,不要求唯一;同一订单可创建多个 Checkout
descriptionbodystring否展示给付款人的收款说明
metadatabodyobject否商户自定义信息,限制见 Checkout Object
return_urlbodystring否收银台“返回商户”按钮的目标地址

同一订单创建多个 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​

属性位置类型必填说明
idpathstring是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_idquerystring否商户订单号,精确匹配,可返回多个 Checkout
statusquerystring否open、processing、succeeded、failed
has_exceptionqueryboolean否true 仅返回有资金异常的会话,false 仅返回无异常的会话;不传则不限
created_fromquerystring否创建时间起点,包含
created_toquerystring否创建时间终点,不包含
page_sizequeryinteger否每页数量,默认 20,范围 1–100
page_tokenquerystring否上一页返回的 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-Keyheaderstring是本次操作的唯一键;重试沿用原值
idpathstring是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​

属性位置类型必填说明
idpathstring是Checkout 的唯一标识
page_sizequeryinteger否每页数量,默认 20,范围 1–100
page_tokenquerystring否上一页返回的 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.codeHTTP 状态码含义适用接口
checkout_not_found404会话不存在或无权访问查询、关闭、查询付款明细
checkout_invalid_state400当前状态不允许操作,例如关闭已成功的会话关闭