Payment statuses

Learn how payments progress through their lifecycle.

Suggest Edits

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 three:

  • executed
  • failed
  • settled

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

  • executed
  • failed

Status

Definition

authorization_required

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

authorizing

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.

authorized

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

executed

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.

failed

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.

settled

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_reason

The reason of the payment failure.

Possible values:

  • canceled: The end user canceled the payment on the provider's UI.
  • 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.

failure_stage

The status of the payment at the time of the failure.

Possible values:

  • authorization_required
  • authorizing
  • authorized

failed_at

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

Updated 18 days ago

Did this page help you?