创建支付会话

创建新的支付会话。服务端会按商户店铺配置解析来源系统，并生成收银台 URL。

POST /api/v1/checkout/sessions/create

200

{
  "id": "<string>",
  "amount_total": 123,
  "currency": "<string>",
  "payment_status": "pending",
  "created": 123,
  "expires_at": 123,
  "url": "<string>",
  "line_items": [
    {
      "price_data": {
        "currency": "<string>",
        "unit_amount": 2,
        "product_data": {
          "name": "<string>",
          "description": "<string>"
        }
      },
      "quantity": 2
    }
  ],
  "tax_amount": 123,
  "shipping_amount": 123,
  "exchange_rate": "<string>",
  "target_currency": "<string>",
  "target_amount_total": 123,
  "rate_locked_at": 123,
  "subscription_id": "<string>",
  "invoice_id": "<string>",
  "metadata": {}
}

授权

Authorization · string · header · 必填

Bearer API Key，例如 Bearer sk_live_xxx。

X-StablePay-Timestamp · string · header · 必填

Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce · string · header · 必填

防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。

X-StablePay-Signature · string · header · 必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。

请求头

X-StablePay-Timestamp · string · 必填

Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce · string · 必填

防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。

Required string length: 16 - 64

X-StablePay-Signature · string · 必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。

请求体

application/json

amount · integer<int64> · 必填

支付金额，使用货币最小单位。

必填范围: x >= 1

currency · string · 必填

商户账本币种，例如 USD。

order_id · string · 必填

商户订单 ID，同一商户下必须唯一。

allowed_shortfall · integer<int64>

用于按单笔支付会话覆盖 Merchant Portal 中配置的少付容差。

API 参数	实际生效规则
不传 allowed_shortfall	沿用 Merchant Portal 的少付容差配置
allowed_shortfall: 0	使用 API 配置，要求全额到账，不允许少付
allowed_shortfall > 0	使用 API 配置，实际到账金额与目标金额的差额不超过该值时，可判定支付成功

• 参数类型必须为 int64，且不能为负数。
• 参数使用实际链上结算币种（USDT 或 USDC）的最小单位，与 Merchant Portal 的固定金额容差语义一致。
• allowed_shortfall 必须小于汇率锁定后生成的稳定币目标支付金额。
• API 参数的优先级高于 Merchant Portal 配置；一旦传入，Portal 的百分比或固定金额少付容差不再参与该笔会话的少付判断。
• 该参数只影响少付判断，多付处理继续沿用 Merchant Portal 配置。
• 使用同一个 order_id 重复创建会话时，allowed_shortfall 必须与首次请求一致。

必填范围: x >= 0

description · string

订单描述，会写入会话 metadata。

line_items · object[]

商品明细。若传入，amount 必须等于商品小计 + 税费 + 运费。

Show child attributes

tax_amount · integer<int64>

税费金额，使用货币最小单位。

必填范围: x >= 0

shipping_amount · integer<int64>

运费金额，使用货币最小单位。

必填范围: x >= 0

success_url · string<uri>

支付成功后的跳转地址。

cancel_url · string<uri>

用户取消支付后的跳转地址。

email · string<email>

支付用户邮箱，选填但强烈建议传入；用于支付通知、客户识别和售后对账，并会写入 metadata.email。

metadata · object

商户自定义元数据键值对。非字符串值会在响应中转为字符串。

Show child attributes

响应

200

application/json

支付会话创建成功。

id · string · 必填

支付会话 ID。

amount_total · integer<int64> · 必填

订单总金额，使用货币最小单位。

currency · string · 必填

商户账本币种，小写返回。

payment_status · enum<string> · 必填

支付状态。confirming 会映射为 processing，completed 会映射为 paid。

可用选项: pending, processing, paid, failed, expired, canceled

created · integer<int64> · 必填

创建时间，Unix 秒。

expires_at · integer<int64> · 必填

过期时间，Unix 秒。

url · string<uri>

收银台 URL。

line_items · object[]

商品明细。

Show child attributes

tax_amount · integer<int64>

税费金额，使用货币最小单位。

shipping_amount · integer<int64>

运费金额，使用货币最小单位。

exchange_rate · string

存在币种转换时返回的汇率值。

target_currency · string

用户实际链上支付币种，例如 USDT。

target_amount_total · integer<int64>

目标支付金额，使用目标币种最小单位。

rate_locked_at · integer<int64>

汇率锁定时间，Unix 秒。

subscription_id · string

关联订阅 ID，仅订阅场景返回。

invoice_id · string

关联发票 ID，仅发票/订阅场景返回。

metadata · object

商户自定义元数据。

Show child attributes