Back to all posts
Backend7 min read·November 1, 2026

How to Prevent Duplicate Transactions in API Integrations

TB
ThynkBlox Team
Engineering

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:

ActionKey decisionRequired outcome
Submit an orderCreate key ACreate the order once
Retry after losing the responseReuse key AResolve to the same order
Repeat the request concurrentlyReuse key APrevent a second order
Submit a separate orderCreate key BAllow a separate order
Change the amount while reusing key AReject the mismatchAvoid 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:

  1. Preserve the original key and request details.
  2. Look up the operation using the provider's supported status mechanism.
  3. If its documented guarantees permit a retry, resend the same operation with the same key.
  4. 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.

ScenarioAcceptance condition
Same key and payload submitted repeatedlyOne business transaction; attempts resolve to it
Matching requests arrive simultaneouslyOne transaction; other attempts receive a defined outcome
Same key, changed amount or recipientClear rejection without another transaction
Transaction completes but its response is lostRecovery finds the original transaction
Processing restarts during an operationRecovery produces neither a duplicate nor silently abandoned work
Same webhook arrives repeatedlyOne application of the intended business effect
Different events describe an already-applied transitionNo repeated fulfilment, receipt or credit
Retry arrives after key retention endsDefined recovery path before another submission
Separate legitimate operations have matching amountsBoth 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 →*

Ready to build?

Let's turn these ideas into your next product.

Start your project