Single payment statuses

The stages in the lifecycle of a payment, and why payments fail.

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
StatusDefinitionTerminal?
authorization_requiredThe payment has been created successfully and no further action has been taken.No
authorizingThe 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
authorizedThe end user has completed the authorisation journey and the payment has successfully completed its authorisation flow.No
executedTrueLayer 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
failedThe 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
settledThis 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",
  .
  .
  .
}
StatusDefinition
failure_reasonThe 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_stageThe status of the payment before it failed. The possible values are:
authorization_required
authorizing
authorized
failed_atThe 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.