--- title: "Payout webhooks" method: POST path: "payouts" tags: ["Payouts"] --- # Payout webhooks `POST payouts` (webhook) Sent to the webhook URI you registered in Console when a payout succeeds or fails. ## Headers - `Tl-Signature` string, required ## Payload - union - WebhookPayoutExecuted - `type` 'payout_executed', required - `event_version` 1, required: The version of the event schema. - `event_id` string, required: Unique ID of the event. - `payout_id` string, required: Unique ID for the Payout - `executed_at` string, datetime, required: Date and time the payout was executed - `beneficiary` union, required - object - `type` 'payment_source', required: Type `payment_source` - `payment_source_id` string, required - `user_id` string - object - `type` 'business_account', required: Type `business_account` - object - `type` 'external_account', required: Type `external_account` - `account_holder_verification` union - AccountHolderVerificationCompleted - `id` string, uuid, required - `status` 'completed', required: A match result was returned. - `match_result` union, required - … - AccountHolderVerificationFailed - `id` string, uuid, required - `status` 'failed', required: A match result was not returned. - `failure_reason` string, required: The reason why the verification failed. There can be many reasons for this, for example: - `VoP scheme provider error`: Failure with one of the providers in the scheme - likely to be transitory. - `Internal error`: An internal error occurred while processing the request. - object - `type` 'verified_external_account', required: Type `verified_external_account` - `account_holder_verification_id` string, uuid, required: The ID of the account holder verification - object - `type` 'user_determined', required: Type `user_determined` - `user` PaymentUser, required - `id` string, required: Unique ID for the User - `provider_id` string, required: The ID of the banking provider associated to the account identifiers present in this object. - `account_holder_name` string, required: The name of the account holder. - `account_identifiers` AccountIdentifier[], required: Account routing information associated to the beneficiary of the payout. - union: A unique scheme identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - … - AccountIdentifierIban: The international bank account number. - … - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - … - object - `type` 'service_provider', required: Type `service_provider` - `scheme_id` string, required: The unique identifier for the scheme. - `trigger` WebhookPayoutTrigger: Optional field that shows what triggered the payout. - `type` 'automated_fee_collection', required: Type `automated_fee_collection` - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - WebhookPayoutFailed - `type` 'payout_failed', required - `event_version` 1, required: The version of the event schema. - `event_id` string, required: Unique ID of the event. - `payout_id` string, required: Unique ID for the Payout - `failed_at` string, datetime, required: Date and time the payout failed - `failure_reason` string, required: The reason the outbound payment failed. Example values to expect: - `insufficient_funds` - `scheme_error` - `server_error` - `blocked` - `returned` - `account_not_valid`: the bank accounts associated with the given AIS consent are not valid. Note that this error is only relevant for `user_determined` beneficiaries. - `expired`: the user did not authorize the payout within the required timeframe. This error applies only to `user_determined` beneficiaries. - `verification_name_mismatch`: the name provided as part of a payout verification does not match the one available on the connected bank account - `verification_transaction_not_found`: the transaction details provided as part of a payout verification are not found within the associated bank account's transactions - `invalid_iban`: the beneficiary IBAN is invalid - `invalid_scan`: the beneficiary SCAN is invalid - `reversed`: the payment was reversed after settling - `unknown`: the failure could not be classified into a more specific reason Clients should handle unexpected values gracefully as a unknown failure. - `beneficiary` union, required - object - `type` 'payment_source', required: Type `payment_source` - `payment_source_id` string, required - `user_id` string - object - `type` 'business_account', required: Type `business_account` - object - `type` 'external_account', required: Type `external_account` - `account_holder_verification` union - AccountHolderVerificationCompleted - `id` string, uuid, required - `status` 'completed', required: A match result was returned. - `match_result` union, required - … - AccountHolderVerificationFailed - `id` string, uuid, required - `status` 'failed', required: A match result was not returned. - `failure_reason` string, required: The reason why the verification failed. There can be many reasons for this, for example: - `VoP scheme provider error`: Failure with one of the providers in the scheme - likely to be transitory. - `Internal error`: An internal error occurred while processing the request. - object - `type` 'verified_external_account', required: Type `verified_external_account` - `account_holder_verification_id` string, uuid, required: The ID of the account holder verification - object - `type` 'user_determined', required: Type `user_determined` - `user` PaymentUser, required - `id` string, required: Unique ID for the User - `provider_id` string: The ID of the banking provider associated to the account identifiers present in this object. Not available if the payout failed during authorization or verification. - `account_holder_name` string: The name of the account holder. Not available if the payout failed during authorization or verification. - `account_identifiers` AccountIdentifier[]: Account routing information associated to the beneficiary of the payout. Not available if the payout failed during authorization or verification. - union: A unique scheme identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - … - AccountIdentifierIban: The international bank account number. - … - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - … - object - `type` 'service_provider', required: Type `service_provider` - `trigger` WebhookPayoutTrigger: Optional field that shows what triggered the payout. - `type` 'automated_fee_collection', required: Type `automated_fee_collection` - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - WebhookPayoutAttemptFailed - `type` 'payout_attempt_failed', required - `event_version` integer, required: The version of the event schema. - `event_id` string, required: Unique ID of the event. - `payout_id` string, required: Unique ID for the Payout - `failed_at` string, datetime, required: Date and time the payout attempt failed - `failure_reason` string, required: The reason the outbound payment failed. Example values to expect: - `insufficient_funds` - `scheme_error` - `server_error` - `blocked` - `returned` - `account_not_valid`: the bank accounts associated with the given AIS consent are not valid. Note that this error is only relevant for `user_determined` beneficiaries. - `expired`: the user did not authorize the payout within the required timeframe. This error applies only to `user_determined` beneficiaries. - `verification_name_mismatch`: the name provided as part of a payout verification does not match the one available on the connected bank account - `verification_transaction_not_found`: the transaction details provided as part of a payout verification are not found within the associated bank account's transactions - `invalid_iban`: the beneficiary IBAN is invalid - `invalid_scan`: the beneficiary SCAN is invalid - `reversed`: the payment was reversed after settling - `unknown`: the failure could not be classified into a more specific reason Clients should handle unexpected values gracefully as a unknown failure. - `beneficiary` union, required - object - `type` 'payment_source', required: Type `payment_source` - `payment_source_id` string, required - `user_id` string - object - `type` 'business_account', required: Type `business_account` - object - `type` 'external_account', required: Type `external_account` - `account_holder_verification` union - AccountHolderVerificationCompleted - `id` string, uuid, required - `status` 'completed', required: A match result was returned. - `match_result` union, required - … - AccountHolderVerificationFailed - `id` string, uuid, required - `status` 'failed', required: A match result was not returned. - `failure_reason` string, required: The reason why the verification failed. There can be many reasons for this, for example: - `VoP scheme provider error`: Failure with one of the providers in the scheme - likely to be transitory. - `Internal error`: An internal error occurred while processing the request. - object - `type` 'verified_external_account', required: Type `verified_external_account` - `account_holder_verification_id` string, uuid, required: The ID of the account holder verification - object - `type` 'user_determined', required: Type `user_determined` - `user` PaymentUser, required - `id` string, required: Unique ID for the User - `provider_id` string, required: The ID of the banking provider associated to the account identifiers present in this object. - `account_holder_name` string, required: The name of the account holder. - `account_identifiers` AccountIdentifier[], required: Account routing information associated to the beneficiary of the payout. - union: A unique scheme identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - … - AccountIdentifierIban: The international bank account number. - … - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - … - object - `type` 'service_provider', required: Type `service_provider` - `scheme_id` string, required: The unique identifier for the scheme. - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `retry` object, required: Details about the retry attempt - `attempts_made` integer, required: Number of retry attempts that have been made so far. - `attempts_remaining` integer, required: Number of retry attempts remaining - `scheduled_for_rerouting` boolean, required: Whether the payout is scheduled for rerouting to a different scheme - `next_attempt_at` string, datetime, required: Date and time of the next retry attempt ## Acknowledgement `200` Webhook Handled --- [API](https://skmtc.dev/truelayer/apis/payments-api-v3.md) - [All operations](https://skmtc.dev/truelayer/apis/payments-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/truelayer/apis/payments-api-v3/revisions/a7c585fc9b84?raw)