Payment statuses
The stages in the lifecycle of a payment, and why payments fail.
Payment statuses
As a payment goes through its lifecycle, it transitions through payment statuses. Below are the definitions for each payment status and how payments move through each of them.
Payments into a merchant account can have a terminal status of either settled
or failed
.
Payments into an external account can have a terminal status of either executed
or failed
.
Status | Meaning | Terminal status? |
---|---|---|
authorization_required | The payment was created successfully and no further action has been taken. | No |
authorizing | The end user started the authorisation journey by interacting with the hosted payment page or your UI, but hasn't completed the journey yet. | No |
authorized | The end user completed the authorisation journey and the payment was authorised. TrueLayer submitted the payment to the bank. No further action is needed from the user. | No |
executed | TrueLayer submitted the payment to the bank and the payment was accepted successfully. The payment is executed by the bank. | Terminal for payments into an external account |
failed | The payment failed to transition to the next status. Learn about different failure reasons. | Terminal for all payments |
settled | The payment settled into your merchant account. This status only appears for closed-loop payments. These are payments into a TrueLayer merchant account. | Terminal for payments into a merchant account |
The diagram below shows how payments transition between statuses:
Account holder name behaviour
The account holder name returned in the webhooks you receive alongside the executed
and settled
payment statuses can be different.
For example, the name Jonathan Robert Sandbridge could differ as below for both statuses:
executed
status account holder name:MR JONATHAN ROBERT SANDBRIDGE
settled
status account holder name:SANDBRIDGE J R
An additional consideration is that accents on characters can be change (or be removed) between executed
and settled
statuses.
Generally, the behaviour varies between different countries, due to how providers process account holder names.
Failure reasons
Payments can fail due to a variety of reasons. If a payment has a status of failed
, the other fields when you get the payment can help you understand why and when the payment failed.
This code block shows an example of the information you receive about a failed payment, when you use a get request to see information about payment:
{
//...
"status": "failed",
"failed_at": "2021-12-25T15:00:00.000Z",
"failure_reason": "provider_rejected",
"failure_stage": "authorizing",
...//
}
failure_reason
object
failure_reason
objectThe failure_reason
object contains one of the following values, which explains why the payment failed.
Value of failure_reason | Meaning |
---|---|
authorization_failed | The PSU failed to authorise the payment successfully. |
blocked | The payment has been blocked due to a regulatory requirement. This may happen if the PSU fails one of our screening checks. |
canceled | The PSU cancelled the payment on the hosted payment page or the payment was cancelled using the /v3/payments/{id}/actions/cancel endpoint. |
constraint_violation | The constraints set up for the mandate were breached by this recurring payment. |
expired | The token of the payment expired before the payment got authorised, thus it won't be possible to execute the payment. |
insufficient_funds | The PSU did not have the required balance in their account to complete this payment. |
internal_server_error | An error has occurred within TrueLayer when processing the payment. |
invalid_account_details | The payment failed because either the payer's or payee's account details were invalid. |
invalid_account_holder_name | The payment failed because the account holder's name details were invalid. |
invalid_beneficiary_account | The payment failed because an invalid beneficiary account reference was provided. |
invalid_credentials | The banking credentials provided by the PSU to log into their bank were incorrect. |
invalid_mandate_state | The mandate was not in a valid status to create a recurring payment. |
invalid_otp | The PSU submitted an incorrect one-time password during the authorisation of the payment. |
invalid_remitter_account | The account details of the remitter bank account provided during the payment flow were incorrect. |
invalid_request | The payment failed due to invalid data in the request. |
invalid_sort_code | The payment failed due to an invalid sort code being provided. |
mandate_revoked | The mandate for a recurring payment is revoked. |
not_authorized | The PSU cancelled the payment or wasn't able to successfully authenticate on the provider's UI. |
payment_limit_exceeded | The PSU's payment limit amount with their bank was breached. |
provider_error | The provider has unexpectedly failed when creating the payment. |
provider_expired | The payment failed because the token or exchange code used to communicate with the bank expired. |
provider_rejected | The payment was rejected by the provider for an unspecified reason. |
rejected | The payment was rejected for an unspecified reason. |
scheme_unavailable | There is no scheme available given the provider selection configuration. |
unknown_error | The payment failed for an unknown reason. |
user_canceled_at_provider | The payment failed because the user cancelled the authorisation during the payment flow. |
verification_declined | The payment didn't pass an age- or name-based verification check. |
failure_stage
object
failure_stage
objectThe failure_stage
object shows the status that the payment transitioned to failed
from. There are four possible statuses:
authorization_required
authorizing
authorized
executed
A payment can only transition from executed
to failed
when a payment fails verification based on name or date of birth).
failure_time
object
failure_time
objectThe failed_at
object contains the time the payment failed at as a RFC-3339 timestamp.
Failure reasons
Make sure to handle any undocumented values as a generic failure reason.
As we learn more about provider behaviours, we will update the list of possible reasons returned on this field. This field won't always contain one of the values listed above.
Updated 4 months ago