API 通用约定
本文定义商户 API 的通用约定。
1. 通用约定
请求与认证
| 环境 | Base URL |
|---|---|
| 正式环境 | https://connect.invisipay.fi/ |
| 测试环境 | https://connect-dev.invisipay.fi/ |
接口路径以 /v1 开头,使用 HTTPS。请求体和响应体使用 JSON。
商户调用平台接口时,使用 API Key,通过 Bearer 认证传入:
Authorization: Bearer inv_test_...
Content-Type: application/json
测试密钥以 inv_test_ 开头,正式密钥以 inv_live_ 开头。API Key 仅供商户服务端使用,请勿暴露给浏览器或移动客户端。
平台向商户发送的 Webhook 使用签名验证,不携带商户 API Key。
字段格式
| 项目 | 约定 |
|---|---|
| 字段名 | 使用 snake_case,枚举值以属性定义为准 |
| 金额 | 使用正十进制字符串,最多 8 位小数;不接受 JSON 数字、科学计数法或千位分隔符 |
| 币种 | 使用小写代码:usdc、usdt |
| 金额单位 | 以币种本身为单位;"10.12345678" 表示 10.12345678 USDT(currency=usdt),与付款网络无关 |
| 时间 | 使用带时区的 RFC 3339 格式;响应统一为 UTC,例如 2026-10-15T08:00:00Z |
创建或更新收款时校验金额,不自动舍入。响应移除多余的前导零和小数末尾的零,例如 "010.500" 返回 "10.5"。确认时,金额还需满足所选收款方式的精度和金额范围要求。
商户可用的币种与网络组合,通过查询可用收款方式获取。
幂等请求
网络超时、程序崩溃等情况可能导致无法确认请求是否成功。使用幂等键(Idempotency Key)可以安全重试,避免重复执行。
在请求头中传入 Idempotency-Key,建议使用 UUID v4;需要此请求头的接口会在 Attributes 中标明:
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
键为 1–255 字节的字符串,不得包含首尾空白、换行或空字符(NUL)。不要求固定前缀,也不强制 UUID 格式;请勿包含个人信息或密钥。
- 新操作用新键,重试用原键,并保持请求参数不变。
- 同一个键在 24 小时内不会重复执行操作;操作完成后,重试返回首次操作结果。
- 同一个键的请求参数不同,返回
400,错误码为idempotency_key_parameter_mismatch;请核对原请求。 - 原请求仍在处理时,可能返回
409,错误码为idempotency_key_in_flight;请稍后使用原键、原参数重试,不要换新键重复发起操作。 - 超过 24 小时,应先查询确认原操作结果,再决定是否发起新操作。
分页
列表接口使用游标分页(Cursor Pagination):
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
page_size | integer | 否 | 每页数量,默认 20,范围 1–100 |
page_token | string | 否 | 上一页返回的 next_page_token;第一页不传 |
{
"data": [],
"next_page_token": ""
}
data 是当前页的资源数组。next_page_token 为下一页游标,空字符串表示没有下一页。获取下一页时保持筛选条件不变。个别接口不分页,以接口定义为准。
错误响应
商户调用平台接口时,成功请求返回 200,失败请求使用 HTTP 状态码,并返回统一的 error 对象:
{
"error": {
"type": "invalid_request_error",
"code": "checkout_invalid_state",
"message": "This operation is not allowed in the current state.",
"param": "status"
}
}
| 属性 | 类型 | 说明 |
|---|---|---|
type | string | 错误分类,见下表 |
code | string | 具体错误码,使用小写 |
message | string | 可读的错误说明 |
param | string | 可选,关联的请求参数 |
details | object | 可选,补充错误信息 |
| HTTP 状态码 | error.type | 含义 |
|---|---|---|
400 | invalid_request_error | 参数错误或当前状态不允许操作 |
400 | idempotency_error | 同一幂等键对应的请求参数不同 |
401 | authentication_error | API Key 缺失或无效 |
403 | permission_error | 商户被停用或无操作权限 |
404 | not_found_error | 资源不存在或不可访问 |
409 | conflict_error | 原幂等请求仍在处理,或资源冲突 |
429 | rate_limit_error | 请求频率超限 |
5xx | api_error | 平台或上游服务异常 |
程序应根据 HTTP 状态码和 code 判断如何处理,不依赖 message 的具体措辞或语言。
响应头
每次请求都会在响应头 Request-Id 中返回唯一请求标识。联系平台排查问题时,请提供该值。
Request-Id: 4bf92f3577b34da6a3ce929d0e0e4736
请求标识由平台生成,商户无需传入。每次重试都会获得新的请求标识,即使使用相同的 Idempotency-Key。