{
"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": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}创建支付会话
创建新的支付会话。服务端会按商户店铺配置解析来源系统，并生成收银台 URL。
{
"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": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}授权
Bearer API Key，例如 Bearer sk_live_xxx。
Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。
使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。
请求头
Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。
16 - 64使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。
请求体
支付金额，使用货币最小单位。
x >= 1商户账本币种，例如 USD。
商户订单 ID，同一商户下必须唯一。
用于按单笔支付会话覆盖 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订单描述，会写入会话 metadata。
商品明细。若传入，amount 必须等于商品小计 + 税费 + 运费。
Show child attributes
Show child attributes
税费金额，使用货币最小单位。
x >= 0运费金额，使用货币最小单位。
x >= 0支付成功后的跳转地址。
用户取消支付后的跳转地址。
支付用户邮箱，选填但强烈建议传入；用于支付通知、客户识别和售后对账，并会写入 metadata.email。
商户自定义元数据键值对。非字符串值会在响应中转为字符串。
Show child attributes
Show child attributes
响应
支付会话创建成功。
支付会话 ID。
订单总金额，使用货币最小单位。
商户账本币种，小写返回。
支付状态。confirming 会映射为 processing，completed 会映射为 paid。
pending, processing, paid, failed, expired, canceled 创建时间，Unix 秒。
过期时间，Unix 秒。
收银台 URL。
商品明细。
Show child attributes
Show child attributes
税费金额，使用货币最小单位。
运费金额，使用货币最小单位。
存在币种转换时返回的汇率值。
用户实际链上支付币种，例如 USDT。
目标支付金额，使用目标币种最小单位。
汇率锁定时间，Unix 秒。
关联订阅 ID，仅订阅场景返回。
关联发票 ID，仅发票/订阅场景返回。
商户自定义元数据。
Show child attributes
Show child attributes
此页面对您有帮助吗？