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:

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

Payments v3 webhook notifications