Payment statuses

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

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, but hasn't 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 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.
`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.

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

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

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",
  .
  .
  .
}

Status	Definition
`failure_reason`	The 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_stage`	The `status` of the payment just prior to the failure. The possible values are: • authorization_required • authorizing • authorized
`failed_at`	The 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.

More about failed payments

🚧Failure reasons

🚧
Failure reasons