Payment statuses

Learn how payments progress through their lifecycle.

As a payment goes through its lifecycle, it will transition through multiple payment statuses. Below are the definitions for each payment status and how they transition from one to another.

For closed-loop payments, using a TrueLayer merchant account the payment can have a terminal status of:

  • failed
  • settled

For open-loop payments, the payment can have a terminal status of:

  • executed
  • failed
StatusDefinition
authorization_requiredThe payment has been created successfully and no further action has been taken.
authorizingThe end user has started the authorization journey by interacting with the hosted payments page or the client's UI, but hasn't completed the journey yet.
authorizedThe end user has completed the authorization journey and the payment has successfully completed its authorization flow.
executedTrueLayer has submitted the payment to the bank and the payment has been accepted successfully. The payment should be executed by the bank.

For open-loop payments, this is a terminal status.

For closed-loop payments, this is not a terminal status.
failedThe payment has failed to transition to the next status.

If TrueLayer is able to identify the failure reason, it will be shared in the failure_reason field on the payment resource. The failure_stage field will share at which payment status the payment was transitioned to failed.

This is a terminal status.
settledThis status only applies to closed-loop payments i.e. when the beneficiary account is a merchant account created and held by TrueLayer.

The payment has settled into the client's merchant account held by TrueLayer.

See our documentation to find out how to make payments into merchant accounts.

This is a terminal status.

The diagram below shows the possible lifecycles of a payment, in terms of status.

Green arrows = closed-loop payments
Grey arrows = open-loop payments

2784

More about failed payments

Any type of failure causes the payment to transition to failed status. You can find the reason for the failure 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 of the payment failure. The possible values are:

authorization_failed: The PSU failed on authorizing the payment.
blocked: The payment has been blocked due to a regulatory requirement. This may happen if the PSU fails a sanctions check.
canceled: The PSU canceled the payment on the Hosted payment page or the payment was cancelled using Cancel Payment API.
expired: The token of the payment expired before the payment got authorized, thus it won't be possible to execute the payment.
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 PSU canceled the payment or wasn't able to 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.

Implementations should be able to accommodate other values, since more failure reasons may be added in future.
failure_stageThe status of the payment just prior to the failure. The possible values are:
authorization_required
authorizing
authorized
failed_atThe time of failure.

🚧

Failure reasons

As we learn more about provider behaviours, we will be continuously updating the list of possible reasons returned on this field. This field won't always contain one of the values listed above.

Make sure to handle any undocumented values as a generic failure reason.