通用约定
协议、请求头、统一响应格式、数据格式和幂等性。
协议规范
| 项目 | 说明 |
|---|---|
| 协议 | HTTPS (TLS 1.2+) |
| 方法 | GET 用于查询类接口，POST 用于操作类接口 |
| 请求格式 | application/json，Token 接口使用 application/x-www-form-urlencoded |
| 响应格式 | application/json |
| 编码 | UTF-8 |
| 超时 | 建议设置 30 秒 |
请求头
| Header | 说明 | 是否必需 |
|---|---|---|
Authorization | Bearer {accessToken} | 是 |
Content-Type | application/json | 是，POST 请求必填 |
Idempotency-Key | 唯一请求标识，建议使用 UUID 或业务唯一流水号 | 是，POST 请求必填 |
统一响应格式
成功响应示例
{
"code": 200,
"message": "OK",
"traceId": "trace-uuid-string",
"data": {}
}错误响应示例
{
"code": 500,
"message": "Payment intent not found: pi_MNOL0POUV8IDPXCD",
"traceId": "trace-uuid-string"
}请以 HTTP 状态码判断请求是否成功。错误响应体中的 code 不一定与 HTTP 状态码相同。联系技术支持时，请提供 traceId。各类错误的含义见错误码。
数据格式
| 类型 | 格式 | 示例 |
|---|---|---|
| 金额 | 标准单位十进制字符串，按币种精度输出；不使用最小货币单位 | "20.00"（USD）、"2000"（JPY） |
| 币种 | 大写代码。稳定币也按币种处理 | USD、USDT |
| 网络 | 平台链名 | Polygon、Ethereum |
| 时间 | ISO 8601，带时区偏移。解析时按 ISO 8601 处理，不要假定固定时区 | 2026-05-11T14:12:34+08:00 |
| 枚举 | 大写码值 | COMPLETED、REQUESTED_BY_CUSTOMER |
值为空的字段不返回。
幂等性 (Idempotency)
Stabo API 对 POST 操作使用 Idempotency-Key 防止重复执行。商户在网络超时或未收到响应时，可以使用相同的 Idempotency-Key 重试同一笔请求。
- 每个
POST请求必须提供Idempotency-Key - 同一业务请求重试时，应复用相同的
Idempotency-Key - 不同业务请求必须使用不同的
Idempotency-Key - 建议使用 UUID、订单号派生值或业务唯一流水号
超时后的重试方式见最佳实践。
各产品处理重复 Idempotency-Key 的方式不同。Payment 的转账接口会拒绝重复的 Key（HTTP 400，Duplicate request detected），不会返回首次结果。超时后用 referenceNo 调用结果查询接口确认状态，不要重新提交。详见 Payment 幂等性。
不要为不同交易复用同一个 Idempotency-Key，否则可能导致请求被识别为重复请求。