Overview
Network failures happen: a request can time out after C2C has already created the order. TheIdempotency-Key header makes retries safe. If C2C has already created an order for a key, it returns that order instead of creating a new one.
POST /api/merchant/orders (deposits and withdrawals) requires an Idempotency-Key. Requests without one are rejected with 400.
How it works
The terms compared are
orderType, amount, walletType, currency, merchantOrderRef, customerAccountNumber and customerAccountName. Other fields (for example callbackUrl or metadata) aren’t compared.
The
Idempotency-Key protects against duplicate requests. Your merchantOrderRef also protects against duplicate payments: only one order that is in progress or completed can use a reference, and a second one is rejected with 409. See merchantOrderRef rules.Key rules
- Format: any string up to 100 characters. Use one key per order, for example your own order ID or a UUID that you store with your order, and reuse it for every attempt at that order.
- Lifetime: keys don’t expire. A key stays bound to its order permanently.
- Signature: retry with the same body, the same
signatureand the sameIdempotency-Key. There’s nothing to re-sign. Sending the same signed body with a new key is rejected asSIGNATURE_REPLAYED, even if the first attempt was rejected, so don’t switch keys between attempts at the same order. - Concurrent duplicates: if several requests with the same key arrive at the same time, only one order is created and every request gets that order back.
Safe retry pattern
Related
Errors
Which errors are retryable
Signature Generation Guide
How retries and replays are told apart