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:

1632

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:

StatusMeaning
pendingThe payout has been created with TrueLayer's API but it has not yet been authorised and sent to the payment scheme for execution.
authorizedThe payout has been sent to the payment scheme for execution.
executedThe payout has successfully been made to the beneficiary account. The payout amount has been deducted from your merchant account.
failedThe 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_reasonMeaning
blockedThe payout was blocked due to a regulatory requirement. This may happen if the payee fails a sanctions check.
insufficient_fundsThe merchant account did not contain enough funds to make this payout.
scan_conversionWe could not convert beneficiary’s sort code and account number to an IBAN.
scheme_errorThere was an issue with the selected payment provider or payment scheme.
server_errorTrueLayer 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:

StatusDefinition
pendingThe refund has been created via TrueLayer's API but has not yet been authorised and sent to the payment scheme for execution.
authorizedThe refund has been created and sent to the payment scheme for execution.
executedThe refund was executed. The refund amount has been deducted from your merchant account.
failedThe refund failed. The refund amount has not been deducted from your merchant account.