此保护机制的作用
部分银行通道会在银行近期拒绝某个目的地后保护该目的地。如果同一规范化 目的地最近被拒绝,CBPay 会在创建 payout、扣除余额或消耗幂等键之前停止 后续创建请求。 保护范围由账户以及规范化后的bank_code、account_number 和 tax_id
组合确定。改变大小写或格式不能绕过保护。
安全处理顺序
- 如果首次响应不明确,使用相同的
idempotency_key完整重放原请求。 这会返回原资源并带有idempotency_hit: true,不会创建第二个 payout。 - 如果响应为
destination_recently_rejected,原始幂等键没有被消耗。 查看银行拒绝信息,并决定是否需要重试该目的地。 - 明确重试必须使用新的幂等键,并将
options.destination_retry_ack设置为最近一次被拒 payout 的 ID。 - 使用旧键但修改选项会返回
409 idempotency_conflict,不会改变原操作。 - 没有近期拒绝的目的地以及其他通道继续走正常的校验和发送流程。
明确重试的请求
响应示例
近期拒绝
使用旧键修改选项
状态与处理方式
常见问题
422 会创建 payout 吗?
422 会创建 payout 吗?
不会。保护机制在插入 payout 和扣款之前执行,也不会消耗提交的幂等键。
收到 422 后可以使用相同的键重试吗?
收到 422 后可以使用相同的键重试吗?
可以,但只能用于完整重放原请求。查看拒绝后要明确重试时,必须使用新键和
确认值。
为什么只修改选项也会返回 409?
为什么只修改选项也会返回 409?
选项属于幂等 payload 的一部分。使用同一键提交不同选项代表另一项请求,因此
CBPay 会拒绝它,而不会静默修改原操作。
所有 payout 通道都适用吗?
所有 payout 通道都适用吗?
不适用。保护机制只在启用它的通道上执行。其他通道以及没有近期拒绝的目的地
继续使用原有的校验和发送流程。