Idempotency

StableOps uses explicit Idempotency-Key headers for create-style requests. For payment orders, merchantOrderId is still required, but it is your business reference, not the replay key.

Payment order creation

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',
})

Retry the same request with the same Idempotency-Key and identical body to get the original response. Reuse the same key with a different body and the API returns a conflict.

merchantOrderId

merchantOrderId is unique per organization and environment. It prevents two different payment orders from claiming the same merchant-side order reference. If you create a second payment order with the same merchantOrderId but a new idempotency key, the API returns 409 merchant_order_id already used; it does not replay the first response.

Key rules

• Generate the key before the first API call and store it with your local order.
• Reuse the same key for network retries and worker restarts.
• Do not use timestamps or random values generated inside each retry attempt.
• Keep keys scoped to one operation, such as order_123:create-payment-order.

Webhooks

Webhook delivery is also retried. Store X-Event-Id before mutating your own ledger or fulfillment state so redeliveries are safe.