Transaction Retry

Transaction Retry enables you to automatically retry declined transactions on a backup gateway in the case of an outage or soft decline. This improves the chance that a transaction is ultimately successful and builds system resilience.

Transaction Retry will only retry transactions classified as soft declines or an outages and may be accepted at another gateway.

Note: Transaction Retry is in beta today and slated to be made Generally Available in Q3 2024. If you have interest in Transaction Retry please contact your account manager or reach out to [email protected].

Decline types and retry modes

When a transaction is declined, a gateway returns an error code that maps to a decline reason.

Error codes are specific to each payment service provider and are available in the gateway documentation.

Spreedly maps error codes to the following three decline types:

  • Hard error codes: Unlikely to be successful if retried on another gateway. This includes error codes tied to fraud suspicion, an incorrect card number, or a lost/stolen card.
  • Soft error code: This may be successful if retried on another gateway. This includes general error codes like do not honor, card or currency not supported.
  • Outage error code: Gateway is temporarily unavailable due to a technical issue, such as a server outage or connection timeout.

Spreedly has two modes of Transaction Retry, Standard and Outage-Only:

  • Standard: Retry both soft declines and outages. Recommended for customers that want the best chance of transaction success.
  • Outage-only: Retry on confirmed or suspected gateway outages only. This includes server outages, connection timeouts, and timeframes where gateway performance is degraded.

How Transaction Retry works

Spreedly customers can pass up to two retry gateways in the initial purchase or authorize requests to transact with the primary gateway. If the primary gateway responds with a success message or hard decline, transaction retry will not send a request to the retry gateway(s).

If the primary gateway responds with a soft decline or gateway outage error code, transaction retry will subsequently trigger a second attempt using the same transaction details on the first retry gateway. If the retry attempt fails on the first retry gateway for any reason, the transaction will try the transaction again on the second retry gateway.

How to use Transaction Retry

Before using Transaction Retry, you must have a minimum of two active gateways in your environment. To add a gateway to your environment, refer to the Add a Gateway guide. There are two options to use retry: use Routing Rules or add the retry object via API request.

Add Retry object via API request

When sending a purchase or an authorize request to your primary gateway, add the backup retry gateway token(s) in the transaction body in the gateway_tokens element nested within the retry element. The array can store up to two retry gateway tokens. Example:

POST /v1/gateways/<primary_gateway_token>/purchase.<format>HTTPS/1.1
  "transaction": {
    "payment_method_token": "<payment_method_token>",
    "amount": 100,
    "currency_code": "USD",
    “order_id”: 123,
    “retry”: {
     			"gateway_tokens": ["first_retry_gateway_token, second_retry_gateway_token"],
     			“mode”: “standard | outage_only”

Both the primary gateway and retry gateway(s) must be production gateways in the same Spreedly environment. To see all active gateways in your Spreedly environment, go to your Spreedly Dashboard and filter on the environment or use a List to see all created gateways in your environment.

Including a valid retry gateway token in the transaction body of the POST request will notify Spreedly that you would like to use Transaction Retry for a Payment. If the retry gateway token is invalid, the response will return an error and the request will not execute.

The optional mode field under the retry element defaults to standard if excluded.

Note: We recommend that you send us order_id in the request, as shown in the example above, for easier reporting in custom analytics. Order ID is defined by the merchant and can be used to tie a customer order number to a series of transaction attempts.

How to send gateway specific fields

Gateway-specific fields are contained within a top-level gateway_specific_fields attribute, and can be sent for transactions against certain gateways.

When using Transactions Retry, you should send all gateway-specific fields for both the primary gateway and all retry gateways. Here is an example of how to send gateway-specific fields for transaction retry.

  "transaction": {
    "gateway_specific_fields": {
      "gateway1_name": {
        "application_fee": "103",
        "receipt_email": "[email protected]"
      "gateway2_name": {
        "merchant_reference": "cb76a9ffcb",
        "transfer_group": "ORDER10"

Supported gateways

For Standard Retry mode, the primary gateway must be one of the following:

  • Adyen
  • Braintree
  • Conekta
  • CyberSource
  • Orbital
  • NMI
  • Stripe
  • Stripe Payment Intents
  • Checkout V2
  • D Local

The retry gateway(s) can be any one of Spreedly’s 120+ supported gateways. This includes the first retry gateway and the secondary retry gateway.

Outage Only Retry does not have gateways restrictions; both the primary gateway and retry gateway can be any one of Spreedly’s supported gateways.

Response structure

Transaction Retry introduces a new payment object in the response, labeled as payment_snapshot that ties together multiple transaction attempts and includes relevant retry details.

Here is a sample response for a payment that was attempted on the primary gateway but did not proceed to the retry gateway due to a hard error.

 "transaction": {
  "token": "transaction_token_1",
  "gateway_token": "primary_gateway_token",
  "state": "gateway_processing_failed", 
  "payment_snapshot": {
     "payment_token": "payment_token_identifier",
     "updated_at": "2023-11-13T02:14:38Z", 
     "gateway_tokens": ["primary_gateway_token", "first_retry_gateway_token"],
     "attempts": 1, //attempt = 1 indicates that only the primary gateway was attempted
     "previous_transaction_tokens": [], //empty array as this is the only attempt for the payment
     "mode": "standard"

Here is a sample response for a payment that failed at the primary gateway with a soft error and was retried on the first retry gateway.

 "transaction": {
  "token": "transaction_token_2",
  "gateway_token": "first_retry_gateway_token",
  "state": "succeeded", 
  "payment_snapshot": {
     "payment_token": "payment_token_identifier",
     "updated_at": "2023-11-13T02:14:38Z",  
     "gateway_tokens": ["primary_gateway_token", "first_retry_gateway_token"],
     "attempts": 2, //attempt = 2 indicates that only the first retry gateway was attempted
     "previous_transaction_tokens": ["transaction_token_1"], //reference to the first transaction attempt for the payment
     "mode": "standard"

As you can see above, each transaction attempt includes a payment_snapshot object that contains relevant details. payment_token uniquely identifies the payment object that is shared across attempts and gateway_tokens is the array of all gateways in the configured retry chain.

attempts refers to how many times the payment has been attempted and tells the user which transaction attempt response is being referenced. For example:

  • attempts = 1 refers to the primary gateway
  • attempts = 2 refers to the first retry gateway
  • attempts = 3 refers to the secondary retry gateway

The transaction tokens for previous attempts will be included in the previous_transaction_tokens field. Lastly

It's important to note that the full transaction transcript details will be included for only the last transaction token attempted in the payment. If you would like to refer to previous tokens you may look up the previous_transaction_tokens in your Spreedly dashboard or by using a show call.

If you would like to see the full history of a payment, including full transcripts for each transaction attempt, you can call the GET payment endpoint<payment_token>.json

How to test Transaction Retry using test gateways

Spreedly test gateways support the ability to trigger specific failure cases which can be used to simulate various transaction failures and the corresponding Transaction Retry behaviors.

Users can trigger a simulated hard decline, soft decline, or gateway outage on a Spreedly Test Gateway by including the simulate_decline gateway-specific field and one of the following values: hard_decline, soft_decline, or outage, in their transaction request. If the request is sent to a non-Spreedly Test gateway, the ‘simulate_decline’ gateway-specific field will be ignored.

A sample transaction request body might look as follows:

POST Request to /v1/gateways/{{test_gateway_token}}/purchase.json

POST /v1/gateways/{{test_gateway_token}}/purchase.json
    "amount": 9325,
    "currency_code": "USD",

When simulate_decline is included with a valid value (as noted above) the transaction will automatically fail. The mode specified by the value in simulate_decline will correspond to the error code returned by the failed transaction, and thus the action that will be taken by the Retry decision engine.

simulate_decline valueError codeRetry action taken
hard_declineinsufficient_fundsNot retried
soft_declinegeneric_declineRetried - only on standard retry mode
outagecircuit_breaker_openRetried - on both standard and outage_only modes

Note: You must have an active gateway account and a valid testing payment method with a payment service provider to test transaction retry outside of Spreedly’s test gateway. Refer to our testing guide for more information.


Q: Is there an extra cost to use Transaction Retry?

A: In Beta, there will be no additional charge for using Transaction Retry.

Once generally available, Spreedly will charge a percentage on the dollar amount of transactions successfully retried and authorized.

Q: Can I see which gateway error codes are classified as hard and soft?

A: Error codes are changing over time as gateways make updates. Please reach out to your account manager for the most recent mapping.

Q: My desired primary gateway is not supported, can I still use Transaction Retry?

A: For our Standard Retry, the primary gateway must be on the list of supported gateways. If your desire primary gateway is not supported, you can either integrate with a supported gateway or contact your account manager or [email protected] to request to add support for your primary gateway.

You can use Outage-only Retry for all gateways that Spreedly supports, but this will not work for gateway specific outage codes.

Q: How can I view a report of which transactions were retried?

A: Go to the ‘Smart Routing’ tab in your dashboard to run a report on which transactions were retried.

Can I use Transaction Retry for transactions that have 3DS2 SCA requirements?

A: Yes, transaction retry works for 3DS2 Global-supported gateways. However, both the primary and retry gateway must support Spreedly 3DS2 Global. Gateways that support Spreedly 3DS2 Gateway Specific will not be supported at this time.

Q: Can I use Transaction Retry with stored credentials?

A: Yes, as you can send storedcredential initiator and stored_credential_reason_type in the Transaction Retry request as described in the (add link) Stored Credential Guide. If the primary or retry gateway supports Stored Credentials, then the gateway will use Stored Credentials to supplement transaction decisions. If the gateway doesn’t support stored credentials, the Stored Credentials will be ignored and the transaction will proceed as usual.

Q: Can I use Transaction Retry with alternative payment methods?

A: At this time, Transaction Retry only works with credit and debit cards.

Q: Does Transaction Retry impact cardholders?

A: For the vast majority of transactions, there is no impact on cardholders. For the portion of transactions that are retried on another gateway, there will be a slight added latency.

In rare instances when a gateway sends us a soft error code but accepts an authorization and declines a capture, if the second gateway accepts the authorization the cardholder may see duplicate authorizations on their credit card statement. This is cosmetic and shouldn’t have an impact on settlement or money movement.

What happens if I send the Retry object in the request to the Routing Rules endpoint? 

Any requests sent to the Routing Rules endpoint,, will effectively ignore the gateway tokens referenced in the Retry object. All retries should be configured in the Routing Rules user interface.