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 will have a terminal status of one of the following two:

  • failed
  • settled

For open-loop payments, the payment will have a terminal status of the following two:

  • executed
  • failed




The payment has been created successfully and no further action has been taken.


The end user has started the authorization journey by interacting with the Hosted Payments Page or the client's UI and have not completed the journey yet.


The end user has completed the authorization journey and the payment has successfully completed its authorization flow.


TrueLayer has submitted the payment to the bank and the payment has been accepted successfully. The payment will be executed by the bank.

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

For closed-loop payments, this is not a terminal status.


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


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

Here is a diagram describing the payment lifecycle of a payment in terms of its status transitions.

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



Failed Status

Any type of failure will cause the payment to transition into failed status. The reason for the failure can be found in failure_reason field in the json resource once the payment is fetched.

More about failed payments

You can find out more details about the failure by investigating two fields on a payment resource. A payment resource upon failure will look like this.

  "status": "failed",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "failure_reason": "provider_rejected",
  "failure_stage": "authorizing",
failure_reasonThe reason of the payment failure.

Possible values:
- canceled: The end user canceled the payment on the Hosted payment page or the payment was cancelled using Cancel Payment API.
- not_authorized: The end user canceled the payment or wasn't able to successfully authenticate on the provider's UI.
- expired: A payment was not authorised within the expiry of the initiation.
- provider_rejected: The payment was rejected by the provider for an unspecified reason.
- unsupported_action: The payment could not be completed as it requires an action not support by the client.

Implementations should be able to accommodate other values, since more failure reasons may be added in future.
failure_stageThe status of the payment at the time of the failure.

Possible values:
- authorization_required
- authorizing
- authorized
failed_atThe time of failure.


Failure stage

You can find out at which point of a status lifecycle the payment has failed by investigating the field named failure_stage. This field can only be one of the statuses that can be observed before failure.


Failure reason

[1] As we learn more about provider behaviors, we will be continuously updating the list of possible reasons returned on this field. You shouldn't expect this field to always contain one of the listed values. Make sure to handle any undocumented values as a generic failure reason.

Did this page help you?