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.

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 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.
`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.

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.

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.

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.

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.