Skip to main content
所有涉及资金变动的操作都需要一个幂等键(idempotency key)。 完整列表如下:

如何发送

两种等效方式(若两者都发送,以请求体为准):
未提供时返回 400 idempotency_key_required。

重试时会发生什么

幂等键在每个来源账户内唯一。若您用相同的键重复一次调用:
  • 不会创建新操作,资金也不会再次变动。
  • 您会收到 200 OK(而非 201/202),返回原始对象并附带 idempotency_hit: true。

该用哪个键重试?

完整的决策规则,让您永远不必猜测:

建议

  • 使用来自您自己系统的标识符(订单 ID、工资单 ID 等),而不是 时间戳或每次重试都重新生成的 UUID。
  • 在调用 API 之前先持久化该键;这样在超时后即可重试,且保证不会 产生重复。
  • 遇到网络错误或 5xx 时,用相同的键重试。遇到校验类 4xx 时, 修正请求并使用新的键。

幂等键会返回给您

操作的 webhook 会以 idempotency_key 字段带回您的键 (payout_status_changed、payin_credited、payin_settlement_scheduled、 payin_expired、payin_refunded、crypto_withdrawal_status_changed、 wallet_send_status_changed),payin 资源在 GET /v1/payins/{id} 中也会返回该字段——无需额外查询即可将通知与您自己的参考号对账。 当操作未携带键创建(或由平台自身创建——内部键永远不会暴露)时省略。 transfer_received 不携带该字段。参见 Webhooks。
最后修改于 2026年9月6日