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

StatusMeaningTerminal status?
authorization_requiredThe payment was created successfully and no further action has been taken.No
authorizingThe end user started the authorisation journey by interacting with the hosted payment page or your UI, but hasn't completed the journey yet.No
authorizedThe end user completed the authorisation journey and the payment has successfully completed its authorisation flow.No
executedTrueLayer 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
failedThe payment failed to transition to the next status.

Learn about different failure reasons.
Terminal for all payments
settledThe 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.

Black arrows are possible status flows for payments into an external account.

📘

Different account holder names

Please note that the account holder name returned in the webhook for a settled payment can be different to the name for an executed payment.

Account holder name behaviour

The account holder name returned in the webhooks for an executed and settled payment can be different.

For example, the name Johnathon Robert Sandbridge could differ as below for both statuses:

  • executed status account holder name: MR JOHNATHON 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 get a 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_reasonMeaning
authorization_failedThe PSU failed to authorise the payment successfully.
blockedThe payment has been blocked due to a regulatory requirement. This may happen if the PSU fails a sanctions check.
canceledThe PSU cancelled the payment on the hosted payment page or the payment was cancelled using Cancel Payment API.
constraint_violationThe constraints set up for the mandate were breached by this recurring payment.
expiredThe token of the payment expired before the payment got authorised, thus it won't be possible to execute the payment.
insufficient_fundsThe PSU did not have the required balance in their account to complete this payment.
internal_server_errorAn error has occurred within TrueLayer when processing the payment.
invalid_account_detailsThe payment failed because either the creditor's or debtor's account details were invalid.
invalid_account_holder_nameThe payment failed because the account holder's name details were invalid.
invalid_beneficiary_accountThe payment failed because an invalid beneficiary account reference was provided.
invalid_credentialsThe banking credentials provided by the PSU to log into their bank were incorrect.
invalid_mandate_stateThe mandate was not in a valid status to create a recurring payment.
invalid_otpThe PSU submitted an incorrect one-time password during the authorisation of the payment.
invalid_remitter_accountThe account details of the remitter bank account provided during the payment flow were incorrect.
invalid_requestThe payment failed due to invalid data in the request.
invalid_sort_codeThe payment failed due to an invalid sort code being provided.
mandate_revokedThe mandate for a recurring payment is revoked.
not_authorizedThe PSU cancelled the payment or wasn't able to successfully authenticate on the provider's UI.
payment_limit_exceededThe PSU's payment limit amount with their bank was breached.
provider_errorThe provider has unexpectedly failed when creating the payment.
provider_expiredThe payment failed because the token or exchange code used to communicate with the bank expired.
provider_rejectedThe payment was rejected by the provider for an unspecified reason.
rejectedThe payment was rejected for an unspecified reason.
scheme_unavailableThere is no scheme available given the provider selection configuration.
unknown_errorThe payment failed for an unknown reason.
user_canceled_at_providerThe payment failed because the user cancelled the authorisation during the payment flow.
verification_declinedThe payment did not satisfy the requested 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 status can only transition from executed to failed for payments to the merchant account and 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.