Payout and refund statuses

Payouts and refunds have four possible statuses. This diagram shows the flow of possible statuses for payouts and refunds:

The possible statuses of a payout or refund. Note that executed payments can fail if they are returned by the bank. (light) — The possible statuses of a payout or refund. Note that executed payments can fail if they are returned by the bank.

payout returns (dark) — The possible statuses of a payout or refund. Note that executed payments can fail if they are returned by the bank.

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 been executed by TrueLayer. The payout amount has been deducted from your merchant account. This does not indicate that the payment amount has been credited to the destination account. In some rare cases, a bank can return a payout or refund, in which case an executed payout or refund can transition to failed.
`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 field 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.
`invalid_iban`	The IBAN that your user provided at the creation of the pay-in this closed-loop payout is for was invalid.
`invalid_scan`	We could not convert the beneficiary’s sort code and account number to an IBAN.
`returned`	The payout was blocked or rejected by the beneficiary bank after it had entered the `executed` status. When a payout fails with a status of `returned`, you receive the `payout_failed` webhook and the status of the payout changes from `executed`, not `failed`.
`scheme_error`	There was an issue with the selected payment provider or payment scheme.
`server_error`	TrueLayer encountered an error while processing the payment.
`unknown`	The payout failed for an unknown reason that does not belong to any of the other reasons.

Verified payout failure reasons

These failure reasons are exclusive to verified payouts.

Failure reason	When it happens
`verification_name_mismatch`	The account holder name does not match the one on file at the bank
`verification_transaction_not_found`	There is no transaction that matches the details of the transaction search criteria
`account_not_valid`	There are no, or more than one, current accounts associated with the AIS consent.
`expired`	The user took 10 minutes or more to authorise the payout.

Ensure that you handle any values not listed here as a generic failure reason. As we learn more about provider behaviours, we update the list of possible payout failure reasons that can be returned.

Failure_details object

In the payout_failed webhook and GET Payout responses, you also receive a failure_details object with more information about why a payout failed. This object can contain two fields:

Field	Format?	Required?	What it means
`error_code`	number	No	Contains a machine-readable classification of the failure (for example, `account_name_mismatch` or `insufficient_funds`.) Unlike `failure_reason`, which gives a broad category, `error_code` gives you the most precise reason available. Use it to build specific handling logic: for example, to display a targeted message to your user, or to decide whether to prompt them to update their account details. This field is not always present. It is only populated when the bank or payment scheme returned a definitive, classifiable reason. If the failure occurred during TrueLayer's internal processing — for example, due to a timeout before the payment reached the scheme — `error_code` will be absent.
`message`	string	Yes	Contains a description of the failure cause as reported by the bank or payment scheme — for example, "Beneficiary Account stopped" or "Insufficient funds in beneficiary account." This field is always present when a payout fails. It is intended for logging and support investigations, not for driving integration logic. The exact wording varies by bank and scheme, and may change without notice, so you should not write code that matches against specific message strings.

Example payout_failed webhook

This is an example of a payout in the sandbox environment that failed due to an account name mismatch:

{
  "type": "payout_failed",
  "event_version": 1,
  "failure_details": {
    "error_code": "account_name_mismatch",
    "message": "Beneficiary name does not match account holder"
  },
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "failure_reason": "insufficient_funds",
  "beneficiary": {
    "type": "payment_source",
    "payment_source_id": "example-ps-id",
    "user_id": "example-user-id"
  }
}

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.

Refund failure reasons

If a refund fails, the failure_reason object contains one of the following values, which explains why the refund failed:

Value of `failure_reason`	Meaning
`blocked`	The refund 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 refund.
`invalid_iban`	The IBAN that your user provided at the creation of the pay-in this refund is for was invalid.
`invalid_scan`	We could not convert the beneficiary’s sort code and account number to an IBAN.
`returned`	When a refund fails with the returned reason, you receive the `refund_failed` webhook and the status of refund changes from executed to failed.
`scheme_error`	There was an issue with the selected payment provider or payment scheme.
`server_error`	TrueLayer encountered an error while processing the payment.
`unknown`	The refund failed for an unknown reason that does not belong to any of the other reasons.
`payment_failed`	Your refund was created before the payment reached a terminal status, and that payment failed instead of settling.