认证、金额与可靠重试
选择环境并保管密钥
| 环境 | API Base URL | Key 前缀 |
|---|---|---|
| 测试 | https://connect-dev.invisipay.fi | inv_test_ |
| 正式 | https://connect.invisipay.fi | inv_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" 时按十进制数值,而不是直接字符串比较,也不要转成浮点数。实际付款仍须满足所选收款方式、资产和网络的精度与范围,先查询收款方式。
持久化幂等操作
- 在本地事务中生成并保存操作 ID、幂等键和完整请求体。
- 用保存的键与请求体发送创建/关闭等操作。
- 请求超时或重启后加载同一记录;不改金额、不生成新键。
- 取得响应后关联资源 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 去重,结合自己的已保存订单和查询范围定期对账。