跳到主要内容

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_sizeinteger否每页数量,默认 20,范围 1–100
page_tokenstring否上一页返回的 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"
}
}
属性类型说明
typestring错误分类,见下表
codestring具体错误码,使用小写
messagestring可读的错误说明
paramstring可选,关联的请求参数
detailsobject可选,补充错误信息
HTTP 状态码error.type含义
400invalid_request_error参数错误或当前状态不允许操作
400idempotency_error同一幂等键对应的请求参数不同
401authentication_errorAPI Key 缺失或无效
403permission_error商户被停用或无操作权限
404not_found_error资源不存在或不可访问
409conflict_error原幂等请求仍在处理,或资源冲突
429rate_limit_error请求频率超限
5xxapi_error平台或上游服务异常

程序应根据 HTTP 状态码和 code 判断如何处理,不依赖 message 的具体措辞或语言。

响应头​

每次请求都会在响应头 Request-Id 中返回唯一请求标识。联系平台排查问题时,请提供该值。

Request-Id: 4bf92f3577b34da6a3ce929d0e0e4736

请求标识由平台生成,商户无需传入。每次重试都会获得新的请求标识,即使使用相同的 Idempotency-Key。