Prevent duplicate payments: make every retry resolve to one intended action.

Map every way the same payment can be submitted twice

Use three identities for three different jobs

These identifiers should be linked, not substituted for one another. A merchant reference may not be unique at the provider. A new idempotency key can represent a new operation. A provider transaction ID proves a record exists but does not by itself prove the related order was fulfilled once.

Design the payment as a state machine, not a success-or-failure button

Use explicit states such as created, submitting, action required, pending, succeeded, failed, canceled, and unknown. Permit only defined transitions. The order should not become unpaid merely because the browser lost a response, and it should not become paid merely because the customer returned from a redirect.

1. Create the merchant action once. Persist the order or invoice payment identity before calling the provider.
2. Reserve the operation. Atomically mark which worker owns the submission or use a uniqueness constraint that prevents a second active operation.
3. Send the supported idempotency key. Tie the key to the operation and normalized payload, not to a browser tab or random retry attempt.
4. Persist the response identifiers. Store the provider object, transaction, request, merchant account, amount, currency, and current state without retaining prohibited payment credentials.
5. Resolve uncertain outcomes. Query or safely replay using the original identity according to provider guidance. Do not create a fresh operation merely because the response was lost.
6. Advance fulfillment once. Use one durable transition from authorized or paid to the merchant's fulfillment workflow.

Reuse a key only for the same logical request

Provider documentation generally treats an idempotency key as the identity of one supported operation. Retrying the same operation should preserve the key and compatible payload. A genuinely new action—such as a second partial capture or a separate refund—needs its own business-action identity and provider request identity.

Do not generate a new key on every technical retry; that can defeat duplicate protection. Do not reuse a prior key for different parameters; providers can reject mismatched replays or return the earlier result. Key scope, length, expiration, regional behavior, supported endpoints, concurrent-request handling, and error recovery all vary. Record the provider and API version used when defining the rule.

Browser controls help, but the server owns correctness

Front-end controls can be bypassed by another tab, an old page, a direct API request, or backend retry. Treat them as customer-experience safeguards, not the ledger's source of truth.

Make webhook consumption idempotent too

Provider webhooks may arrive more than once, later than expected, or out of order. Verify the event using the provider's current security method, retain the event or delivery identifier, and make the downstream business transition conditional on current state. Marking one delivery as seen is useful, but the business operation must also resist a second event that describes the same outcome through a different delivery.

Capture, refund, void, and reversal need separate controls

The original payment key should not be recycled for every later modification. Each capture, refund, void, or reversal is its own business action with an amount, currency, reason, actor, approval, and provider result. Preserve the relationship to the original authorization while giving the modification a distinct identity.

Before retrying a modification, check whether the first request succeeded. Compare the total authorized, captured, refunded, reversed, and remaining eligible amounts. Provider-side limits can help, but the merchant ledger should not rely on an error response as its only control.

Use reconciliation as the backstop

Idempotency reduces duplicates at request time; reconciliation finds inconsistencies that still occurred. On a regular schedule, compare merchant orders and approved actions with provider authorizations, captures, payments, refunds, reversals, disputes, fees, and settlement records.

Resolve a customer-reported duplicate without guessing

1. Identify every visible entry. Ask for dates, amounts, descriptor text, and pending or completed status without requesting full card details or security codes.
2. Search all relevant routes. Check the order, provider, merchant account, payment method reference, alternate provider, and any manual or retry workflow.
3. Separate holds from completed charges. Two pending authorizations are not automatically two settled payments. Follow provider guidance for voids or reversals and avoid promising when an issuer display will update.
4. Stop duplicate fulfillment. Hold a second shipment, service activation, credit, or receipt when the facts support doing so.
5. Use the supported remedy. Void, reverse, or refund the actual transaction according to its current provider state and the merchant's approved policy.
6. Link the evidence. Retain the order, transaction IDs, action owner, timestamps, customer communication, remedy ID, and reconciled final status.
7. Fix the cause. Tag repeat click, timeout, concurrency, multiple session, webhook replay, operator action, or another root cause and assign an engineering or operating change.

Test failure paths before production traffic finds them

Run provider-documented scenarios in a representative test environment, then use controlled production verification only after approval. A successful test does not guarantee uninterrupted processing or that every provider route behaves identically.

Measure one order, not just many API calls

Track unique checkout attempts, business actions, provider requests, technical retries, duplicate blocks, unknown states, recovered orders, duplicate authorizations, duplicate completed charges, duplicate fulfillment events, corrective voids or refunds, customer contacts, disputes, and reconciliation exceptions.

A low API error rate can hide duplicate customer impact. A high number of idempotent replays may show resilience or a failing network. Review ratios by checkout version, provider route, merchant account, payment method, device, geography, and failure cause. Count final paid orders and corrected customer outcomes, not only successful responses.

Questions to ask the payment provider

1. Which create, authorize, capture, refund, void, and reversal endpoints support idempotency?
2. What is the key's scope, permitted format, retention period, and behavior across regional endpoints or merchant accounts?
3. What happens when the same key is sent with different parameters or while the first request is still processing?
4. How should the integration retrieve an authorization or payment after a timeout?
5. Does the provider also apply duplicate-transaction detection based on merchant references, amounts, payment methods, or time windows?
6. Which transaction, request, correlation, and webhook identifiers should be stored for investigation?
7. How can reports expose authorizations, captures, refunds, reversals, settlement, and duplicate blocks at transaction level?

Implementation details and availability vary by provider, API, region, merchant configuration, and payment method. PayFresco does not guarantee duplicate prevention, authorization, pricing, refund timing, settlement, or uninterrupted processing.