Retries
Overview
With Payrails you can create workflow configurations to automatically retry failed payment authorization attempts, thereby improving the overall payment acceptance rate and enhancing customer experience.
Key Features:
Conditional, rules-based retry logic
You can create rules based on any fields related to the authorization request body or workflow execution context. This includes but is not limited to:
- Authorization request body fields
- Meta fields
- Workflow execution context fields, e.g.,
Current authorize attempt number
andLast authorize result
. Such fields can be used to create complex rules around conditional retry logic.
Flexible scheduling automation
Automatic retry scheduling allows you to flexibly schedule automated retries either immediately after the first failed attempt in case of CITs or on some defined delay or schedule in case of MITs. For example, you may configure:
- A simple automation delay, e.g., retry immediately after 0 seconds, or retry after 24 hours
- A scheduled retry attempt at a specific date and time, e.g., retry on 01.01.2025 at 01:00:00
![](https://files.readme.io/d5732ee-retryScheduling.png)
Fallback Mechanism
You can configure a retry either with the same PSP or a different PSP. In case you configure a retry with a different PSP, Payrails will handle transforming the request body and automatically making the authorization request with the configured fallback PSP.
Idempotency Handling
Retries can only be attempted with PSPs that support idempotency. In case of a configured retry with a provider that does not support idempotency, we will not attempt an authorization and instead will indicate in retries.stopReason
in a notification that Provider failed with Timeout and does not support idempotency
.
How to Configure Retries
With Payrails you can configure different retry strategies for different scenarios. Below are some strategies you may consider for different failure types and processing scenarios:
Failure type | Description | Strategy for customer initiated transactions (CITs) | Strategy for merchant initiated transactions (MITs) |
---|---|---|---|
Hard decline | Unlikely to be successful if retried on another gateway. Examples include suspected fraud, an incorrect card number, or a lost/stolen card. | No retry applicable; prompt user to try again with a different payment method. | Scheduled retry of MIT with same PSP: For example, if a MIT fails because of insufficient funds, you can automatically retry again after some time interval. |
Soft decline | May be successful if retried with another PSP. Examples include general error codes like "do not honor," "currency not supported," etc. | Immediate retry of CIT with fallback PSP | Immediate retry of MIT with same or fallback PSP |
Outages | Technical downtime from a PSP. | Immediate retry of CIT with fallback PSP | Immediate retry of MIT with same or fallback PSP Immediate retry of MIT with same or fallback PSP |
Use Payrails' operation result codes to configure rules for hard vs. soft declines
For every PSP we map their rejection reasons to abstracted operation result codes, e.g., GenericRejection
, InsufficientFunds
, ProviderTimeout
. We do not systematically label these as "hard" vs. "soft" decline reasons, but you can configure retry rules based on our operation result codes to achieve targeted retry strategies.
Specifically, you can create a rule based on the Last authorize result
execution context field to leverage operation result codes in retry strategies.
Workflow execution status and client-side handling for CIT retries
In case there are subsequent retries scheduled for a workflow execution, the status of that execution will remain in authorizeRequested
until all retry attempts are exhausted. Only then will the status change to, for example, authorizeFailed
.
If you are using the Payrails SDK in your client application, then no additional action is required to handle retries for CIT payments with an immediate, automatic retry configured.
If you have built a server-to-server integration with Payrails and are polling the execution status yourself in order to determine the final outcome of a payment, please be aware of this consideration.
Retry details in notifications
We will inform you via notifications when retries are scheduled or when an authorization attempt is made as a result of a configured retry.
In the retries
object in notifications you can find the following fields:
Field name | Type | Format | Description |
---|---|---|---|
nextScheduledAt | String | Date-time | Time when the next retry attempt will be performed. The field will be present any time there is a subsequent retry scheduled. |
startedAt | String | Date-time | Time when the retry is set up, but not performed yet. When it is scheduled to be perform can be checked in nextScheduledAt . The field will be present any time there is a subsequent retry scheduled. |
completedAttempts | Integer | Number of retry attempts completed so far. The field will be present any time > 0 retries have so far been attempted. | |
stopReason | String | Reason for stopping further retries. The field will be present any time a scheduled retry has been unscheduled, e.g., because of cancellation. | |
idempotencyKey | String | UUID | Idempotency key used to retry in case of timeout. The field will be present any time > 0 retries have so far been attempted. |
Authorization retry scheduled
When an authorization attempt fails and a subsequent retry is scheduled, you will receive a notification like the one below. The actionId
will relate both to the initial authorization attempt as well as subsequent retries.
{
"event": "executionActionScheduled",
"time": "2024-06-10T17:52:36.381273Z",
"details": {
"action": "authorizeRetry",
"actionId": "50c0af01-5f73-5bea-bf3e-1ecf603fe138",
"reason": "Automatic retry due to failure",
"scheduledAt": "2024-06-10T17:52:36.381273949Z"
},
"workspaceId": "0dcc19e0-2e78-4072-a636-84423df49755"
}
Retries object in notifications for failed authorization attempts
When an authorization attempt fails and triggers scheduling of another attempt, you will find in the retries
object an indication of when the next scheduled retry attempt will take place, as shown below:
"retries": {
"nextScheduledAt": "2024-07-10T09:21:58.931436499Z",
"startedAt": "2024-07-10T09:21:58.931436499Z"
Retries object in notifications for subsequent, retried authorization attempts
In subsequent, retried authorization attempts, the retries
object will indicate which retry attempt this is, as shown below:
"retries": {
"completedAttempts": 1,
"startedAt": "2024-07-10T09:21:58.931436499Z"
Updated about 2 months ago