Idempotency
Idempotency in payment APIs is the property whereby submitting the same request multiple times produces the same result as submitting it once. This is typically implemented through idempotency keys that uniquely identify each API call, preventing duplicate payment processing in the event of network failures, timeouts, or retry logic.
Network failures are inevitable in distributed systems. When a platform submits a payment API call and receives no response, because of a network timeout, server error, or connection drop, it faces a dilemma: was the payment processed? Without idempotency, retrying the API call risks sending a duplicate payment. With idempotency, retrying is safe: the server recognizes the duplicate and returns the original response without processing a second payment.
Idempotency keys are unique identifiers included in API requests, typically as a request header. The payment infrastructure provider caches responses keyed by idempotency key for a defined period. If the same key is submitted again, the cached response is returned without reprocessing. This makes retry logic safe.
For high-volume payment operations, idempotency is a critical safety property. A batch payout system submitting 50,000 payments must handle the scenario where the API call succeeds on the server side but the response is never received by the client. Without idempotency, resubmitting the batch risks 50,000 duplicate payments. With idempotency, the resubmission returns the original results safely.
Duplicate payments are one of the most damaging failure modes in payment systems, causing recipient overpayment, reconciliation nightmares, and costly recovery operations. Idempotency is the primary mechanism preventing duplicate payment processing in API-based payment systems. It is a prerequisite for safe retry logic in production payment integrations.
- Generating truly unique idempotency keys at scale requires careful implementation (typically UUIDs)
- Idempotency key storage and lookup must be performant to avoid adding latency
- Idempotency windows have expiry times: resubmitting after expiry may process a new payment
- Concurrent submissions with the same key require server-side locking to prevent race conditions
- Client systems must persist idempotency keys durably in case of client restart before response receipt
A payroll platform processes 100,000 salary payments monthly via Nium's payout API. During peak processing, a network disruption causes 3,200 API calls to time out without response confirmation. The platform retries all timed-out calls with the original idempotency keys. Nium returns the cached results for the 3,200 calls that succeeded, processes the remainder as new payments. Zero duplicate payments occur.
Related Concepts
Nium's payment and payout APIs support idempotency through idempotency key headers. Submitting the same API request with the same idempotency key returns the original response without reprocessing, which enables safe retry logic in client integrations. Nium's developer documentation provides implementation guidance for idempotency in payout and payment workflows.
Answers you didn't know you needed.
What is an idempotency key?
An idempotency key is a unique string (typically a UUID) included in an API request header that identifies that specific request. If the same request is submitted again with the same key, the server returns the original response without reprocessing, preventing duplicate operations.
How long are idempotency keys valid?
Idempotency key validity periods vary by provider. After expiry, submitting the same key is treated as a new request. Check Nium's API documentation for the current idempotency window.
Do I need to use idempotency keys?
For payment initiation, yes: idempotency keys are strongly recommended and in some cases required. Without them, network failures or retry logic can cause duplicate payments.
What is a UUID and why is it used for idempotency keys?
UUID (Universally Unique Identifier) is a 128-bit identifier format that generates statistically unique IDs without central coordination. UUIDs are the standard format for idempotency keys because the same value will never accidentally be generated twice.
How does idempotency interact with webhooks?
Webhooks are also subject to duplicate delivery. Client webhook handlers should check whether they have already processed a given event ID before taking action, mirroring the same principle as API idempotency keys.