跳到主要内容

创建 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"
}

业务错误码