Gateway Selection
Part of Checkout performance
Designing a fallback when a payment service is unavailable
Plan truthful payment states, safe retries and an alternative route when a payment service is unavailable.
A payment fallback should give the buyer a truthful next step without risking an unexplained second charge. Distinguish an attempt known to have failed from one still processing or of unknown outcome.
Offer a new attempt only when the integration can establish or safely resolve the first attempt's state. Otherwise, pause payment and explain how the buyer will learn what happened.
Separate outage from refusal
A timeout or lost connection means the store did not receive a dependable answer; it does not prove that no payment occurred. A documented refusal or cancellation is different.
Use the provider's available status and later payment events to resolve an uncertain attempt. If the provider is unavailable for status checks too, keep the order unresolved until a dependable outcome is available. Retain the order and payment-attempt references for investigation.
| Known state | Fallback to design |
|---|---|
| Attempt confirmed unsuccessful, with no outstanding partial payment | Allow another attempt where the integration supports it, retaining the basket and current total. |
| Payment still processing | Say it is processing and explain how the buyer will learn the outcome. |
| Outcome unknown after a timeout | Hold the order unresolved and check the provider before inviting another charge. |
| Service unable to accept new requests | Explain that payment is temporarily unavailable and offer a safe later return or another verified route. |
These are design categories, not universal provider status labels. Authorisation, capture and partial-payment rules depend on the method and configuration. Match the store's fulfilment rule to the outcome it actually receives.
Check whether another route works
An alternative method helps only if the platform can present it, its supporting service works, and the store can recognise its final outcome. A second button using the same unavailable backend is no fallback.
If another provider is configured, link its attempt to the original order and check the first attempt before opening the second. An idempotency key at one provider does not coordinate charges across providers.
For retries to the same provider, follow its documented idempotency rules. Adyen supports idempotency for POST requests using the same key after a timeout. Its keys are scoped to a company account, remain valid for 7 to 14 days and are not checked for duplication across regional endpoints.
A request can remain in progress even when no response has been received. These limits do not replace checking the eventual payment outcome or preventing a second store order.
If no safe route is available, retain the basket or unpaid order under the store's stock and retention policy. Tell the buyer whether an order was placed, whether stock is reserved, and whether to wait for a message or return later. Do not promise a reservation the system does not make or issue a paid confirmation before the required outcome is known.
Adyen Idempotency Key Rules for Retry Handling
- Scope of key
- Company account level
- Validity period
- 7 to 14 days
- Cross-region duplication check
- Not checked
- Applies to
- POST requests only
Rehearse the interruption
In a provider's permitted test setup, exercise an unavailable request, a timeout after submission and a later outcome event where supported. Check the customer message, order state, retry control and staff view. Include a page refresh and return after interruption. Test a separate route if one exists; a sandbox cannot prove how a production outage will behave.
Assign an owner to unresolved attempts and a way to contact affected buyers when a final result arrives. After service recovers, compare store orders with provider records before reopening automatic retries.
