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

Payment statuses

Payments into a merchant account can have a terminal status of:

settled
failed

Payments into an external account can have a terminal status of:

executed
failed

Status	Definition	Terminal?
`authorization_required`	The payment has been created successfully and no further action has been taken.	No
`authorizing`	The end user has started the authorisation journey by interacting with the hosted payments page or your UI, but hasn't completed the journey yet.	No
`authorized`	The end user has completed the authorisation journey and the payment has successfully completed its authorisation flow.	No
`executed`	TrueLayer has submitted the payment to the bank and the payment has been accepted successfully. The payment is executed by the bank.	Terminal for payments into an external account
`failed`	The payment has failed to transition to the next status. If we can identify the failure reason, it will be indicated in the `failure_reason` field on the payment resource. The `failure_stage` field shows at which payment status the payment transitioned to `failed`.	Terminal for all payments
`settled`	This status only appears for closed-loop payments: when the beneficiary account is a merchant account created and held by TrueLayer. The payment has settled into your merchant account.	Terminal for payments into a merchant account

The diagram below shows how payments transition between statuses.

2784 — Green arrows indicate possible statuses for payments into a merchant account.
Grey arrows indicate possible statuses for payments into an external account.

Failure reasons

The reason for the failure is in the failure_reason field of the json resource after the payment is fetched.

The failure_stage field shows the status of the payment it transitioned to failed from.

{
  .
  .
  .
  "status": "failed",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "failure_reason": "provider_rejected",
  "failure_stage": "authorizing",
  .
  .
  .
}

Status	Definition
`failure_reason`	The reason for the payment failure. Possible values include: • authorization_failed: The end user did not authorise the payment. • blocked: The payment has been blocked because of a regulatory requirement. This may happen if the end user fails a sanctions check. • canceled: The end user cancelled the payment during authorisation (for example, on the hosted payment page) or the payment was cancelled using the cancel payment endpoint. • expired: The payment token expired before the end user authorised the payment, so the payment cannot be executed. • internal_server_error: An error has occurred within TrueLayer when processing the payment. • rejected: The payment was rejected for an unspecified reason. • not_authorized: The end user cancelled the payment or did not successfully authenticate on the provider's UI. • provider_error: The provider has unexpectedly failed when creating the payment. • provider_rejected: The payment was rejected by the provider for an unspecified reason. • scheme_unavailable: There is no scheme available given the [provider selection configuration]. Make sure to also include a generic failure reason for any values not on this list.
`failure_stage`	The `status` of the payment before it failed. The possible values are: • authorization_required • authorizing • authorized
`failed_at`	The time of failure.

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

Payment statuses

Failure reasons

🚧Failure reasons

🚧
Failure reasons