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:
failedsettled
For open-loop payments, the payment will have a terminal status of the following two:
executedfailed
Status | Definition |
|---|---|
| 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 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
failedstatus. The reason for the failure can be found infailure_reasonfield 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",
.
.
.
}
| Status | Definition |
|---|---|
failure_reason | The 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_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
Updated 8 days ago