Payout and refund statuses

The stages in the lifecycle of a payout or refund, from creation to execution or failure.

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.
invalid_ibanThe IBAN that your user provided at the creation of the pay-in this closed-loop payout is for was invalid.
invalid_scanWe could not convert the beneficiary’s sort code and account number to an IBAN.
returnedThe 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. However, the payout remains in a state of executed, not failed.
scheme_errorThere was an issue with the selected payment provider or payment scheme.
server_errorTrueLayer encountered an error while processing the payment.
unknownThe 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:

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.

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_reasonMeaning
blockedThe refund 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 refund.
invalid_ibanThe IBAN that your user provided at the creation of the pay-in this refund is for was invalid.
invalid_scanWe could not convert the beneficiary’s sort code and account number to an IBAN.
returnedThe refund was blocked or rejected by the beneficiary bank after it had entered the executed status.
scheme_errorThere was an issue with the selected payment provider or payment scheme.
server_errorTrueLayer encountered an error while processing the payment.
unknownThe 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.