How to Prevent Duplicate Transactions in API Integrations
To prevent duplicate transactions in an API integration, give each intended operation a stable identity and require the receiving system to recognise repeat attempts. Reuse that identity when retrying, handle duplicate webhooks before applying their effects, and investigate uncertain outcomes before starting another operation. Retrying safely depends on the receiver's guarantees: sending an idempotency key alone does not establish protection.
How does idempotency prevent a second transaction?
Idempotency means repeating an operation has the same intended effect as performing it once. For an order-creation request, that means repeated attempts create one order. It does not mean every response must be identical or every attempt must succeed. HTTP semantics define it the same way: the intended effect of repeated identical requests matches a single request, though the response might differ (RFC 9110, section 9.2.2).
Treat the business operation and its delivery attempts separately. “Create this order” is one operation; sending the request again after losing a connection is another attempt at that operation.
For your product requirements, define the outcome explicitly: repeated attempts must resolve to the original order, payment or record, without creating another business effect.
This belongs in the integration agreement from the start. The broader decisions are covered in what to plan for in a third-party API integration.
What should an idempotency key identify?
Assign a key to one intended operation before sending its first request. Keep it with the local operation record and reuse it for every retry of that operation.
Use a fresh key for a genuinely new operation. Do not generate a new key merely because a request timed out, a worker restarted or a user pressed “Try again.”
An illustrative example:
| Action | Key decision | Required outcome |
|---|---|---|
| Submit an order | Create key A | Create the order once |
| Retry after losing the response | Reuse key A | Resolve to the same order |
| Repeat the request concurrently | Reuse key A | Prevent a second order |
| Submit a separate order | Create key B | Allow a separate order |
| Change the amount while reusing key A | Reject the mismatch | Avoid silently changing the operation |
Do not use the amount alone as the identity. Two legitimate purchases may have the same amount. Prefer an operation identifier whose purpose is to distinguish business intent.
Keep sensitive information out of keys. Use an opaque identifier and retain the relationship to the customer or order in your own records.
What guarantees should the receiving API provide?
Ask for the contract for the specific endpoint you will call. Require answers to these questions:
- Scope: Does the key belong to one account, customer, endpoint or another boundary?
- Retention: How long will the receiver remember it?
- Payload matching: What happens if the same key arrives with different transaction details?
- Concurrency: What happens when matching requests arrive together?
- Failure handling: Which failures allow another attempt, and which outcomes are remembered?
- Recovery: Can you retrieve the original operation and its current status?
Require duplicate detection and the business change to survive failures together. For a receiver you control, have the team explain what happens if processing stops between recording the key and creating the order, or between creating the order and recording its result.
For a receiver you do not control, obtain documented guarantees and test the stated behaviour. Do not infer support from a header name or a successful demonstration.
If the receiver lacks suitable protection, require another enforceable safeguard, such as a unique business reference that it rejects when reused. Otherwise, define an investigation path for uncertain outcomes instead of promising automatic safe retries.
What should happen after an ambiguous timeout?
A timeout can leave the caller unable to tell whether the receiver completed the transaction. Losing the response is not proof that the operation failed. The HTTP standard makes the same point: a connection can fail before the client reads the response even though the original request succeeded (RFC 9110, section 9.2.2).
Design a separate “outcome unknown” state. Avoid immediately labelling the transaction failed and inviting another purchase.
Require the integration to follow this recovery sequence:
- Preserve the original key and request details.
- Look up the operation using the provider's supported status mechanism.
- If its documented guarantees permit a retry, resend the same operation with the same key.
- If the outcome remains uncertain, keep it pending and route it for reconciliation.
Reconciliation means comparing your records with the receiver's records to establish what actually happened.
Also define recovery after the receiver's key-retention period ends. Do not assume an old key still protects a replay. Require a status check, an enforceable business reference or manual resolution before another submission.
How should duplicate webhooks be handled?
Treat incoming notifications as a separate duplicate-prevention problem. A provider may deliver the same event more than once; verify its delivery and retry contract. The Standard Webhooks specification keeps one event identifier across retries so receivers can process an event once even when it is sent several times.
Require the webhook handler to authenticate the notification using the provider's supported mechanism, then identify the event within the correct provider and account scope.
For processing:
- Store the event identity durably.
- Coordinate the duplicate check with the business update.
- Mark work complete only when its required effects have completed.
- Make recovery safe if processing stops partway through.
Do not record an event as fully processed before updating the order. That would make a retry look unnecessary even though work remains.
Also distinguish an event from a business transition. Two different event identifiers might describe the same payment reaching the same state. Require a rule that prevents that repeated transition from issuing another receipt or starting another shipment.
If handling a webhook triggers another API call, carry an appropriate operation identity into that call too. Learn more about delivery choices in webhooks vs API polling.
Which acceptance scenarios should you require?
Ask for observable results, including the receiver's records and downstream effects. A success message alone is insufficient evidence.
| Scenario | Acceptance condition |
|---|---|
| Same key and payload submitted repeatedly | One business transaction; attempts resolve to it |
| Matching requests arrive simultaneously | One transaction; other attempts receive a defined outcome |
| Same key, changed amount or recipient | Clear rejection without another transaction |
| Transaction completes but its response is lost | Recovery finds the original transaction |
| Processing restarts during an operation | Recovery produces neither a duplicate nor silently abandoned work |
| Same webhook arrives repeatedly | One application of the intended business effect |
| Different events describe an already-applied transition | No repeated fulfilment, receipt or credit |
| Retry arrives after key retention ends | Defined recovery path before another submission |
| Separate legitimate operations have matching amounts | Both remain possible with distinct identities |
Test the whole path. For an illustrative order flow, inspect the order, payment, stock change and fulfilment request. Require one of each intended effect.
These scenarios can become contract acceptance criteria using the approach in software acceptance criteria examples.
What common mistakes leave duplicates possible?
Creating a new key on every attempt. Require retries to recover the persisted operation identity, including after a restart.
Checking before creating without coordinating concurrent requests. Require the simultaneous-request scenario to pass; sequential demonstrations are insufficient.
Relying on a disabled button. Keep the button behaviour for usability, while requiring duplicate protection at the receiving boundary.
Treating every error as permission to retry. Define retry eligibility from the endpoint's documented behaviour and the operation's known state.
Protecting only the first system. Review every business effect, including downstream payment, email and fulfilment calls.
Ignoring retention. Set a recovery policy for delayed work and old queued requests before enabling automatic replay.
Frequently asked questions
Is an idempotency key the same as a transaction ID?
Use them as separate concepts. The key identifies the intended operation before submission; the receiver's transaction ID identifies the resulting record. Store both when available.
Can idempotency stop a customer placing two separate orders?
Define that as a separate product rule. If the customer submits two operations with different keys, require an explicit business check if those orders should be treated as duplicates.
Should every failed request be retried?
No. Require a documented decision for validation errors, authentication failures, temporary failures and unknown outcomes. Resolve uncertainty about an existing transaction before creating a replacement.
Does one idempotent endpoint protect an entire workflow?
Require evidence for every step. Acceptance should cover the complete business outcome, including effects triggered after the original request.
Retries often happen inside background workers; see background jobs and queues, explained for founders.
*Need an integration with clear retry and recovery rules? Start a conversation →*