跳转到主要内容
POST
/
api
/
v1
/
checkout
/
sessions
/
create
{
  "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": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt

Use this file to discover all available pages before exploring further.

授权

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,同一商户下必须唯一。

description
string

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

line_items
object[]

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

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

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

响应

支付会话创建成功。

id
string
必填

支付会话 ID。

amount_total
integer<int64>
必填

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

currency
string
必填

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

payment_status
enum<string>
必填

支付状态。confirming 会映射为 processingcompleted 会映射为 paid

可用选项:
pending,
processing,
paid,
failed,
expired,
canceled
created
integer<int64>
必填

创建时间,Unix 秒。

expires_at
integer<int64>
必填

过期时间,Unix 秒。

url
string<uri>

收银台 URL。

line_items
object[]

商品明细。

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

商户自定义元数据。

Last modified on April 30, 2026