HTTP 约定和支付状态
认证和权限
Authorization 请求头 发送 API 密钥. 每个接口均列出所需作用域.401 表示凭据或 Webhook 签名密钥被拒绝. HTTP 403 表示 API 密钥缺少所需作用域. 未知或无法访问的 Payment 返回 404. 不得使用浏览器登录会话或 payment_id 替代 API 密钥.请求, 重试和幂等
Idempotency-Key. 该值不能为空白, 长度不超过 255 字节. 同一次意图及其网络重试必须保持幂等键不变. 使用同一幂等键提交不同输入会返回 409. order_ref 不能替代幂等键, 可以缺省或重复.Retry-After 时, 按其要求等待. 对于永久拒绝的请求, 先修正输入或凭据, 再重新提交.err, msg 和 retryable 字段, 可能附带接口特定的详情. 使用 err 进行程序分类. msg 是说明文字, 不是稳定的程序判断依据. API 故障可能返回 503 merchant_api_temporarily_unavailable, 该结果不能证明此前写操作是否成功.金额和时间
amount_raw 必须是规范的正整数字符串, 包含 1 到 78 位 ASCII 数字且无前导零. 不接受零, 正负号, 小数点或指数表示法. 小数位数来自已配置的货币或加密资产计价来源, 请求不提交小数位数. Fiat 是计价单位, 不代表支持银行卡或法币支付.X-Server-Time 表达权威响应时间, 格式为 UTC RFC 3339, 毫秒固定为三位. 标准 Date 仅用于传输诊断. 不要假定响应体 存在 server_time. 其它时间戳表示 Payment 的创建, 激活或更新时间.Payment 状态
| API 和后台 状态 | 集成处理方式 |
|---|---|
open | 等待支付事实. 已创建的 Payment 可能尚未首次激活. |
paid | 根据履约策略处理权威结果. |
partially_paid | 按少付策略处理, 不得视 为 paid. |
overpaid | 按超额支付策略处理, API 不会自动退款. |
expired | 激活期限或支付窗口已结束. 异常处理仍须依据权威事实. |
cancelled | 已记录符合条件的商户取消操作. |
review_required | 需要审核, 不得在缺少权威状态时推断成功. |
activated_at 为 null, payment_expires_at 表示首次打开 Checkout 的截止时间. 客户首次成功打开 Checkout 时, API 会设置 activated_at, 并将 payment_expires_at 重设为支付截止时间. 创建, 创建重试和服务端查询不会激活 Payment. 再次打开已激活的 Checkout 不会延长支付窗口.status_version, 也不会生成 payment.updated. 需要当前激活时间或支付截止时间时, 调用 GET /v1/payments/{payment_id}.status_version 只对同一 Payment 内的事实排序, 不是跨订单的全局时钟. 迟到或重复的事件不得覆盖更新的版本. Payment 状态来自权威事实, 不得将其视为不可变的浏览器成功标记.