Skip to main content

Overview

Network failures happen: a request can time out after C2C has already created the order. The Idempotency-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.
Never reuse a key for a different order. A retry must send the same terms as the original request, or it’s rejected with 422. Keys created before this check was introduced aren’t checked: reusing one of those returns the original order whatever the terms.
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 signature and the same Idempotency-Key. There’s nothing to re-sign. Sending the same signed body with a new key is rejected as SIGNATURE_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

Persist the Idempotency-Key with your own order record before the first attempt. If your process crashes mid-request, you can resume with the same key and never create a duplicate deposit or payout.

Errors

Which errors are retryable

Signature Generation Guide

How retries and replays are told apart