● 客户端会话 · /v1

客户端会话

把一笔待支付的上下文换成短时效 client token,交给前端 SDK 或托管收银台渲染,卡号不经过你的服务器。

创建客户端会话

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"
    }
  ]
}

查询客户端会话

GET /v1/checkout/sessions/{uid}

路径参数

uid必填 string

响应 200

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
请求
curl -X GET https://api.baton.example/v1/checkout/sessions/{uid} \
  -H "Authorization: Bearer sk_live_xxx"

更新客户端会话

POST /v1/checkout/sessions/{uid}/update

买家在收银台改了地址、用了优惠券导致金额变化时调用。已过期的会话不可更新。

路径参数

uid必填 string

请求体

amount integer
customer_uid string
metadata object

响应 200

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

错误

409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
curl -X POST https://api.baton.example/v1/checkout/sessions/{uid}/update \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 7900
}'