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 has successfully submitted the payment to the bank and the bank has confirmed it as accepted. This does not mean that the payment will settle in the creditor’s account.	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:

Blue arrows are possible status flows for payments into a merchant account.

Black arrows are possible statuses for payments into an external account. — Blue arrows are possible status flows for payments into a merchant account. A payment to a merchant account can transition from `executed` to `failed` if you have enabled name- or age-based verification.
Black arrows are possible status flows for payments into an external account.

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

The 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

The 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

The 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.