A payment gateway timeout means your application did not receive a usable response within its waiting window; it does not prove that the gateway, processor, or issuer did not act. Treat the payment as unknown, preserve one transaction identity, query or await the gateway’s status, and retry only with the provider’s idempotency mechanism. This avoids duplicate charges while giving the customer a clear next step.

What should a merchant do after a payment gateway timeout?
What causes a payment gateway timeout?
How can you retry a payment safely?
How do you prevent duplicate charges?
Which gateway statuses should trigger a retry?
What should the customer see during a timeout?
How should merchants test timeout and retry handling?
A timeout-handling checklist for merchants
Frequently Asked Questions

What should a merchant do after a payment gateway timeout?

The safest immediate response is to stop treating the checkout attempt as a simple failure. A timeout is a communication result: your system waited too long, the connection ended, or an intermediary returned an error before your application learned the final payment state. The request may not have arrived, may still be processing, or may already have authorized or captured funds.

Create a durable payment-attempt record before sending the gateway request. Give that attempt a merchant-side order ID, a unique payment-operation ID, the gateway’s idempotency key if supported, the amount and currency, and timestamps. When the response is missing, mark the attempt unknown or pending, not declined. Then use the gateway’s documented status endpoint, dashboard, or webhook to reconcile the result.

Stripe describes network errors as situations in which the client cannot know whether the server received the request and recommends retrying with the same idempotency key and parameters. [2]

Your customer-facing message should also reflect uncertainty. “We’re checking your payment—please don’t submit again” is more accurate than “Payment failed.” If the status later becomes successful, confirm the order and fulfillment. If it becomes declined or expired, explain that no completed payment was confirmed and offer a controlled retry. The exact state names, lookup methods, idempotency-key lifetime, and webhook behavior differ by gateway, so the gateway’s current documentation controls.

What causes a payment gateway timeout?

A gateway payment is a chain of network calls rather than one local database operation. The customer’s browser or app talks to your checkout, your server calls the gateway, the gateway may call an acquirer or payment network, and the response must travel back through the same or another path. A delay at any point can exceed a client, load balancer, gateway, or upstream timeout.

Client and browser timeouts

A shopper can close a tab, lose mobile connectivity, switch networks, or hit a browser-side deadline while the server continues working. A mobile app can also suspend in the background, so the browser should not be the sole source of payment truth. The server should own the payment attempt and expose a safe way to retrieve its current state rather than letting a second click create a new payment operation.

Merchant-server and infrastructure timeouts

Your application may time out while opening a TLS connection, waiting for a gateway response, resolving DNS, or passing through a reverse proxy. A load balancer can terminate a request before the gateway finishes. A slow database transaction can consume the same budget, leaving too little time for the outbound gateway call. Record gateway request IDs, idempotency keys, merchant order IDs, and correlation IDs, but never log full card numbers or security codes.

Gateway, processor, acquirer, or issuer delays

A gateway can be available while a downstream processor, acquirer, card network, or issuer is slow or unavailable. The gateway may return a 5xx response, a provider-specific temporary error, or no response at all. PayPal warns that a network timeout or 5xx from certain execute or capture endpoints may still have resulted in a transaction and recommends repeating the same call with the same PayPal-Request-Id. [8]

A timeout also can be produced by an intermediary. A 504 indicates that a gateway or proxy did not receive a timely response from an upstream server; it describes the response path, not necessarily the final payment outcome. [6] In practice, treat a 504 on a payment mutation as potentially indeterminate unless the gateway explicitly documents a definitive outcome.

Webhook and asynchronous-notification timeouts

A payment can be processed successfully while your webhook endpoint fails to acknowledge the event. That is a different timeout from the original payment API call, but it can create the same business problem: the gateway knows the state while your order system does not.

Stripe instructs webhook handlers to return a successful 2xx response quickly before complex work that could cause a timeout. It also documents automatic event retries, duplicate deliveries, and the need to track event IDs rather than assume events arrive in order. [4] Adyen similarly places unacknowledged webhook messages in a retry queue. [5] Your webhook handler should authenticate the event, persist it or enqueue it, acknowledge quickly, and make downstream fulfillment idempotent.

How can you retry a payment safely?

A safe retry is not “send the same button click again.” It is a controlled replay of the same payment operation using the gateway’s supported idempotency mechanism, the same business parameters, and a deliberate retry policy.

1. Assign one operation identity

Generate the payment-operation identity before the first charge or authorization request. A cart ID alone may be too broad if a customer legitimately starts a second attempt after a completed order. A practical key can combine your order ID, a specific payment attempt number, and a random component, provided it remains stable for retries of that one operation and does not expose personal data.

The key must not change merely because the first response timed out. Stripe saves the result associated with an idempotency key and compares later parameters; it says a connection error can be retried with the same key without creating a second object. [1] Adyen likewise supports retrying a timed-out POST with the same key without duplication. [5]

Do not reuse one key for unrelated orders. Do not reuse a key with a changed amount, currency, customer, or payment method unless the provider explicitly defines that behavior. A mismatched replay may be rejected, or worse, it may make your internal records difficult to reconcile.

2. Classify the outcome before choosing an action

Use a small decision model rather than a generic “retry on error” rule:

Confirmed success: finalize the order once, record the gateway transaction ID, and make any fulfillment step idempotent.
Confirmed decline or validation error: do not retry the same request unchanged. Correct the input or ask for another payment method.
Temporary provider or rate-limit error: follow the gateway’s retry instructions, usually with exponential backoff and jitter, while preserving the operation identity.
No response, network timeout, or ambiguous 5xx: keep the attempt unknown, query the payment status if possible, and retry only with the same idempotency key or provider request ID.
In-progress or asynchronous state: wait for the documented status transition or webhook. Do not create a second payment simply to make the interface look decisive.

Stripe’s low-level guidance distinguishes content, network, and server errors. It says network failures are indeterminate and that 500 responses should be treated as indeterminate because side effects may exist. [2] Adyen’s response guidance also notes that a successful HTTP response does not always mean a payment or modification has completed; the corresponding webhook may be the final confirmation. [6]

3. Use bounded exponential backoff

If the provider permits a retry, wait between attempts. A basic schedule might be a short initial delay followed by increasingly longer delays, capped by a maximum wait and a maximum number of attempts. Add jitter so many workers do not retry at exactly the same instant after an outage. The numbers must reflect the gateway’s documented limits, your checkout latency budget, and the payment method’s behavior; there is no universal timeout or retry interval that is safe for every gateway.

Adyen recommends exponential backoff for retries to avoid flooding its API and running into rate limits. [5] Its response guidance specifically calls for exponential backoff with jitter for 429 responses. [6] A retry budget should also stop when the gateway has supplied a definitive result. Continuing to retry after a confirmed success is not resilience; it is an operational defect.

4. Prefer status retrieval over repeated mutations

When a timeout leaves the result unknown, a read-only status lookup is usually safer than submitting a new charge. The lookup might use your merchant reference, a gateway payment ID returned before the timeout, an idempotency key, or a provider-specific request ID. If the gateway does not offer lookup by your reference, maintain enough correlation data to work with its support or reconciliation tools.

Stripe’s PaymentIntents guidance likewise recommends reusing the payment object for a resumed checkout and retrieving its current state rather than creating an unrelated payment. [3]

How do you prevent duplicate charges?

Duplicate-charge prevention has two layers: gateway-side idempotency and merchant-side business idempotency. You need both because the gateway may prevent two charges while your application still creates two orders, or your application may prevent two orders while two gateway objects are created.

Gateway-side controls

Use the exact mechanism the gateway documents. Stripe uses the Idempotency-Key header for POST requests and retains keys for at least 24 hours before automatic removal. [1] Adyen uses an idempotency-key header and documents a validity period of seven to fourteen days. [5] PayPal uses PayPal-Request-Id; omitting it can allow a repeated POST to duplicate the request, while repeating it returns the latest status for that request. [7]

Avoid simultaneous retries for the same operation. Two workers can wake up together after a queue delay, or a customer can click while a background retry is running. Use a database lock, compare-and-set state transition, or a single-flight mechanism around the payment attempt. If both requests reach the gateway, the shared idempotency key should provide a second line of defense, not the only one.

Merchant-side controls

Your order database should have a unique business key for the purchase and a separate unique key for each payment operation. The fulfillment worker should be able to receive the same “payment succeeded” event twice without shipping twice. Store gateway event IDs or transaction IDs and mark them processed atomically with the order update.

Do not treat a customer refresh as a new order. The confirmation page should load the existing order and payment state. If the customer starts over, make the distinction visible: “Resume payment,” “Try a different method,” or “Create a new attempt.”

A practical duplicate scenario

Suppose a customer pays $180 for an order. Your server sends an authorization request with operation key order-8421-attempt-1, but the connection closes before the response arrives. The customer sees a timeout and clicks Pay again. If the second request uses order-8421-attempt-2, the gateway may see two independent payment operations. If the second request reuses the first operation’s documented idempotency key and identical parameters, the gateway can return the first operation’s result instead of creating another one, subject to that provider’s rules.

Your application still needs to reconcile the response with order 8421, check whether fulfillment has already started, and show the customer one final state. Idempotency reduces duplicate processing; it does not automatically fix incorrect order-state transitions, repeated emails, or repeated shipment requests.

Which gateway statuses should trigger a retry?

Status handling should use both the HTTP layer and the gateway’s payment-level response. A 200 can mean “the API accepted and processed the request” without meaning the payment is finally captured. A 4xx may represent invalid input, authentication, a business decline, or a conflict that requires a status lookup. A 5xx or network timeout may be indeterminate.

Adyen documents 202 Accepted as accepted but not yet processed, 408 Request Timeout as retryable, 409 Conflict as retryable only when its transient-error header is true, 429 Too Many Requests as a signal to use exponential backoff with jitter, and 504 Gateway Timeout as an upstream response delay. [6] It also says a 200 response can still require a webhook to learn whether a capture succeeded. [6]

PayPal’s guidance is similarly explicit for supported calls: a network timeout or 5xx can have created a transaction, so repeat the call with the same PayPal-Request-Id rather than starting an unrelated request. [8] These examples illustrate a rule, not a universal cross-gateway status matrix: read each provider’s endpoint-specific documentation before coding.

Map provider-specific values into a small internal state model without losing the original raw status. A status should be terminal only when the provider says it is terminal for that payment action. Record transitions with timestamps so support staff can explain what happened without asking the customer to pay again.

What should the customer see during a timeout?

Good timeout UX reduces repeat submissions without falsely promising an outcome. The message should identify the order or attempt, state that the payment result is being checked, and tell the customer what to do next. It should not display raw gateway error codes, suggest that a card is declined when the outcome is unknown, or instruct the shopper to click repeatedly.

A useful three-stage experience is:

During the wait: disable the pay control, show progress, and make clear that the customer should not refresh or resubmit.
After the local timeout: show “We could not confirm the payment yet.” Provide a status-check action and a safe way to return to the order. Do not imply that funds definitely moved or definitely did not move.
After reconciliation: show the final result. For success, provide the order number and receipt. For a confirmed decline, explain that the payment was not completed according to the gateway response and offer another method. For a still-pending payment, explain when the customer should check again and how to contact support.

If the customer’s bank app shows a pending authorization while your site shows an unknown state, do not promise an immediate reversal. A pending authorization is not necessarily a captured payment, and release timing depends on the gateway, issuer, payment method, and transaction state. Tell the customer what your system knows and provide a support path with the order reference.

How should merchants test timeout and retry handling?

Test the payment state machine, not only the happy-path API response. In a sandbox, simulate a delayed response, a dropped connection after request transmission, a 408 or 504, a 429, a 5xx, a confirmed decline, an asynchronous pending state, a duplicate webhook, and an out-of-order webhook. Confirm that each case produces the intended internal state and customer message.

Test the dangerous boundary in which the gateway completes the payment but your application times out. Then replay the same request with the same idempotency key and verify that your system records one payment and one order. Test two simultaneous retries, a browser refresh, a worker restart, and a webhook arriving before the API response is recorded locally.

Use observability that connects the whole attempt: order ID, payment-operation ID, gateway request ID, idempotency key, provider payment ID, response class, raw provider status, retry count, and elapsed times. Alert on elevated unknown states, repeated 5xx or timeout rates, webhook backlog, and mismatches between gateway transactions and local orders. These are operational signals, not proof that a gateway is at fault; compare them with provider status pages and reconciliation data.

Before launch, review the gateway’s live-mode documentation, run a controlled verification plan where appropriate, and agree on an incident procedure with the gateway or processor. This is implementation guidance, not a guarantee that every duplicate, authorization hold, or delayed response can be prevented.

A timeout-handling checklist for merchants

Before deploying a gateway integration, confirm that:

The payment attempt is persisted before the mutation request is sent.
One stable idempotency key or provider request ID is reused for retries of that operation.
Amount, currency, order, and payment parameters are unchanged on an idempotent replay.
Unknown outcomes trigger status lookup or webhook reconciliation rather than a new charge.
Retry attempts use a bounded exponential-backoff policy with provider-approved limits.
Concurrent workers and repeated customer clicks cannot create uncontrolled parallel attempts.
Webhook receipts, order updates, and fulfillment are idempotent.
Raw card data and security codes are excluded from logs.
Support staff can search by order ID, gateway reference, and operation key.
The customer is told whether the payment is confirmed, declined, pending, or still unknown.

Frequently Asked Questions

What is a payment gateway timeout?

It is a failure to receive a usable response within the configured time window. It does not by itself prove that the payment failed. The merchant should preserve the payment attempt, check the gateway’s status, and avoid submitting a new payment without the gateway’s idempotency protection.

Should I retry a payment after a gateway timeout?

Only under the gateway’s documented retry rules. For an ambiguous network timeout or 5xx, use the same idempotency key or provider request ID, the same payment parameters, and bounded backoff. Prefer status retrieval or webhook confirmation before sending another mutation.

How can I prevent a customer from being charged twice?

Use gateway-side idempotency and merchant-side uniqueness controls. Reuse one operation key for retries, block concurrent attempts for the same purchase, make webhook and fulfillment processing idempotent, and show an unknown or pending message instead of inviting repeated clicks.

Payment Gateway Timeouts and Retry Handling: A 2026 Guide

Table of Contents