Payment statuses

As a payment goes through its lifecycle, it will transition through multiple states.

Status

Description

authorization_required

Payment with this status is on its initial phase where no action beyond the creation of the payment was taken.

authorizing

Payment has its authorization_flow started, but the authorization has not completed yet

authorized

Payment has successfully completed its authorization flow

executed

Payment has been accepted by the bank

failed

Payment has failed. The reason for failure can be observed in failure_reason field on the payment resource

settled

Payment can transition into this state if the beneficiary account was a merchant account within Truelayer, and Truelayer has observed the money to be settled.
See this document to find out how to make payments into merchant accounts

Here is an image describing the status lifecycle of a payment. Green arrows represent happy path, meanwhile reds are the opposite. A blue arrow represents conditional transitions that may not always happen.

Status lifecycle of a payment. Settled status can only be observed if the payment was made into a merchant account managed by Truelayer.Status lifecycle of a payment. Settled status can only be observed if the payment was made into a merchant account managed by Truelayer.

Status lifecycle of a payment. Settled status can only be observed if the payment was made into a merchant account managed by Truelayer.

🚧

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 why the payment failed.

Values:

  • canceled
  • 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 failure.

Values:

  • authorization_required
  • authorizing
  • authorized

failed_at

Time of failure

🚧

Failure stage

You can find out at what 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] 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?