跳到主要内容

认证、金额与可靠重试

选择环境并保管密钥​

环境API Base URLKey 前缀
测试https://connect-dev.invisipay.fiinv_test_
正式https://connect.invisipay.fiinv_live_

先确认账户可访问所选环境,Key 的环境须与接入环境匹配。服务端发送 Authorization: Bearer ...,JSON 请求加 Content-Type: application/json。商户身份由已验证 Key 决定,不接受前端传入的 merchant ID 作为权限依据。

将 Key 存在密钥管理系统,不放到浏览器、移动应用、日志或收银台 URL。轮换 Key 时保持各环境配置清晰。Webhook 使用其独立签名 secret,不使用商户 API Key 验签。

精确处理金额​

金额为币种单位的正十进制字符串,最多 8 位小数。例如 "10.5" 与 currency=usdc 表示 10.5 USDC。不接受 JSON 数字、科学计数法或千位分隔符,不自动舍入。

数据库使用精确十进制或定点数;比较 "10" 与 "10.00" 时按十进制数值,而不是直接字符串比较,也不要转成浮点数。实际付款仍须满足所选收款方式、资产和网络的精度与范围,先查询收款方式。

持久化幂等操作​

  1. 在本地事务中生成并保存操作 ID、幂等键和完整请求体。
  2. 用保存的键与请求体发送创建/关闭等操作。
  3. 请求超时或重启后加载同一记录;不改金额、不生成新键。
  4. 取得响应后关联资源 ID,再查询当前资源状态。

键为 1–255 字节,无首尾空白、换行或 NUL;推荐 UUID v4。平台在 24 小时内对相同操作重放首次结果。幂等重放响应可能仍是首次创建时的 open,当前状态要通过查询取得。

结果恢复动作
400 idempotency_key_parameter_mismatch恢复原参数;若需新业务操作,先完成业务核对再创建独立记录
409 idempotency_key_in_flight原操作仍在处理,退避后沿用原键与原参数
网络中断、超时、5xx结果未知;按操作性质重试原记录并查询资源
超过 24 小时先查询原资源或按订单列出核对,不能假设旧键仍能去重

order_id 不保证唯一;平台幂等只处理单次接口操作,商户仍需按订单去重履约。详细规则见 API 通用约定。

错误与限流​

程序根据 HTTP 状态码与 error.code 决定恢复,不匹配 message 文案。保留响应 Request-Id;日志不保存 Authorization 或完整密钥。401 先核对 Key 和环境,403 核对账户权限;404 可能是不存在或无访问权限,不能推断支付失败。

收到 429 按 Retry-After(如有)及运营方限流要求退避,加入抖动并限制并发。不要由每个浏览器页面独立高速轮询。没有拿到有效业务响应时,不把超时或解析失败改成 unpaid。

分页与对账​

列表请求用 page_size(默认 20,1–100)与 page_token。返回 data 和 next_page_token,空 token 表示结束。翻页保持筛选条件不变;对持续变化的资源按 ID 去重,结合自己的已保存订单和查询范围定期对账。

可用资源客户端见确认与履约,完整错误格式与每个接口的业务错误在 API 参考中。