创建客户端会话
POST
/v1/checkout/sessions 把金额、订单号、客户绑定成一个 client token。前端 SDK 拿 token 渲染收银台, 卡号直接进金库,不经过你的服务器——你的 PCI 范围因此可以降到 SAQ-A。 token 默认 24 小时过期,不要落库、不要复用。
请求头
Idempotency-Key必填 | string | 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。 |
请求体
reference_id必填 | string | |
amount必填 | integer | |
currency必填 | string | |
customer_uid | string | |
country | string | 买家国家,影响可用支付方式与路由 |
metadata | object |
响应 201
uid | string | |
client_token | string | 交给前端 SDK 的短时效令牌,不可落库、不可复用 |
expires_at | string<date-time> | 默认 24 小时 |
reference_id | string | |
amount | integer | |
currency | string | |
customer_uid | string | |
available_payment_methods | object[] | 按金额、币种、国家、客户已绑卡算出来的可用方式,前端直接渲染 |
└type | string | |
└token | string | 已绑卡时返回 |
└label | string |
错误
| 400 | 参数不合法 | |
| 401 | 密钥缺失、无效、与环境不匹配,或签名校验失败 | |
请求
curl -X POST https://api.baton.example/v1/checkout/sessions \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
-H "Content-Type: application/json" \
-d '{
"reference_id": "OR20261116000104",
"amount": 8900,
"currency": "USD",
"customer_uid": "CUS20261116000041",
"country": "US"
}' 响应 · 201
{
"uid": "CS20261116000093",
"client_token": "ct_live_eyJhbGci...",
"expires_at": "2026-11-17T08:12:00Z",
"reference_id": "OR20261116000104",
"amount": 8900,
"currency": "USD",
"available_payment_methods": [
{
"type": "card",
"token": "pm_7c2a91f4",
"label": "Visa •••• 4242"
},
{
"type": "paypal"
}
]
}