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 three:
executed
failed
settled
For open-loop payments, the payment will have a terminal status of the following two:
executed
failed
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
failed
status. The reason for the failure can be found infailure_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",
.
.
.
}
| The reason of the payment failure. Possible values:
|
---|---|
| The Possible values:
|
| 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 18 days ago