Skip to main content
Networks fail in the worst possible way: your request arrives, Numero moves the money, and the response is lost on the way back. You cannot tell that apart from the request never arriving — and retrying blind pays the recipient twice. An idempotency key removes the ambiguity. You generate a unique value per attempt and send it as the Idempotency-Key header. If Numero has already processed that key, it returns the original result instead of doing the work again. Retrying is then always safe.

​
When you must send it

Every endpoint that moves value requires the header. The API reference lists Idempotency-Key in its Headers table wherever it is mandatory:
  • Transfers — /business/single, /business/bulk, /business/usd/transfers
  • Payouts — /business/payout/initiate
  • VAS purchases — airtime, data, electricity, betting funding, cable TV (including add-ons)
  • Wallet money movement — /wallets/{walletReference} credit, debit, transfer and payout
Omitting it on one of those endpoints returns HTTP 400. That is deliberate: without a key, a client-side network retry has no way to be safe, so we would rather fail your first attempt than risk double-sending on your second. On other write endpoints the header is optional but honoured — send one and you get the same protection.

​
Generating a key

Any unique string up to 100 characters. A UUID is the obvious choice.
Generate the key once per logical operation and reuse it across every retry of that operation. A fresh key on each retry defeats the entire mechanism — that is the most common way this goes wrong. Store the key alongside your own record of the payment before you send the request. If your process dies mid-flight, you can then resume with the same key and discover what happened rather than guessing.

​
What Numero does with it

The 409 is a safety net, not something to work around. It means your code reused a key for a different payment, which almost always indicates a bug in how keys are generated.

​
Scope and lifetime

Keys are scoped per merchant, so you only need uniqueness within your own account — another merchant using the same string does not collide with you. Cached responses are retained for 24 hours by default. After that the key is forgotten and reusing it starts a new operation, so retries should happen well inside that window. Anything older should be resolved by querying transfer status rather than replaying.

​
Idempotency is not a substitute for checking status

If you are unsure whether a transfer went through and you no longer hold the key, do not send a fresh request to find out. Query transfer status with the reference you were given. Idempotency protects a retry of the same attempt; it cannot protect a new attempt you have chosen to make.