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