Idempotency

StableOps 在创建类请求上使用显式的 Idempotency-Key 请求头。对支付单而言， merchantOrderId 仍然必填，但它属于业务引用，不是重放键。

创建支付单

const input = {
  merchantOrderId: 'order_123',
  amount: '10.00',
  settlementAsset: 'USDC',
  acceptedAssets: [{ chain: 'base', asset: 'USDC' }],
}

const order = await client.paymentOrders.create(input, {
  idempotencyKey: 'order_123:create-payment-order',
})

使用同样的 Idempotency-Key 和同样的请求体重试，会拿到原始响应。 同样的 key 配上不同请求体则会返回冲突。

merchantOrderId

merchantOrderId 在组织 + 环境内全局唯一，防止两个不同的支付单声称指向同一个商户侧 订单引用。带上同样的 merchantOrderId 但换了 idempotency key 创建第二笔订单，API 会返回 409 merchant_order_id already used；不会重放第一次的响应。

使用规则

• 在发起第一次 API 调用前生成 key，并和本地订单一起持久化。
• 网络重试与 worker 重启都必须复用同一个 key。
• 不要用每次重试时新生成的时间戳或随机值。
• key 的作用域要小，例如 order_123:create-payment-order。

Webhook

Webhook 投递也会重试。在改写自家账本或履约状态前，先按 X-Event-Id 去重，保证重复投递安全。