Payout and refund statuses
The stages in the lifecycle of a payout or refund, from creation to execution or failure.
Both payouts and refunds have four possible statuses. This diagram shows the flow of possible statuses for payouts and refunds:

The payout and refund status flow. From authorized
, a payout or refund can transition to executed
or failed
.
Payout statuses
A payout has four possible statuses during its lifecycle:
Status | Meaning |
---|---|
pending | The payout has been created with TrueLayer's API but it has not yet been authorised and sent to the payment scheme for execution. |
authorized | The payout has been sent to the payment scheme for execution. |
executed | The payout has successfully been made to the beneficiary account. The payout amount has been deducted from your merchant account. |
failed | The payout failed. The payout amount has not been deducted from your merchant account. |
Payout failure reasons
If a payout fails, the failure_reason
object contains one of the following values, which explains why the payout failed:
Value of failure_reason | Meaning |
---|---|
blocked | The payout was blocked due to a regulatory requirement. This may happen if the payee fails a sanctions check. |
insufficient_funds | The merchant account did not contain enough funds to make this payout. |
scan_conversion | We could not convert beneficiary’s sort code and account number to an IBAN. |
scheme_error | There was an issue with the selected payment provider or payment scheme. |
server_error | TrueLayer encountered an error while processing the payment. |
This is an example of a payout in the sandbox environment that failed due to insufficient funds:
{
"id": "cbdb0fe4-22c6-4ac9-8446-8948458bfb4d",
"merchant_account_id": "2a485b0a-a29c-4aa2-bcef-b34d0f6f8d51",
"amount_in_minor": 1000000000,
"currency": "EUR",
"beneficiary": {
"type": "payment_source",
"user_id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
"payment_source_id": "c7022d14-3f53-4162-99de-1d615b77b960",
"reference": "PayOutRef",
"account_holder_name": "JOHN SANDBRIDGE",
"account_identifiers": [
{
"type": "iban",
"iban": "GB75CLRB04066800000871"
}
]
},
"scheme_id": "unknown",
"status": "failed",
"created_at": "2023-09-13T15:41:34.553255381Z",
"failed_at": "2023-09-13T16:13:15.318037412Z",
"failure_reason": "insufficient_funds"
}
Refund statuses
A refund has four possible statuses during its lifecycle:
Status | Definition |
---|---|
pending | The refund has been created via TrueLayer's API but has not yet been authorised and sent to the payment scheme for execution. |
authorized | The refund has been created and sent to the payment scheme for execution. |
executed | The refund was executed. The refund amount has been deducted from your merchant account. |
failed | The refund failed. The refund amount has not been deducted from your merchant account. |
Updated 15 days ago
Next steps