冪等性

StableOps 在建立類請求上使用顯式的 Idempotency-Key 請求頭。對付款單而言， merchantOrderId 仍然必填，但它屬於業務引用，不是重放鍵。

建立付款單

const input = {
  merchantOrderId: 'order_123',
  amount: '10.00',
  acceptedAssets: [{ chain: 'base', asset: 'USDC' }],
  expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
}

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 去重，保證重複投遞安全。