Make a verified payout

Verified Payouts enables you to pay out to a known, verified beneficiary. For example, you may want to make a payout to the same bank account previously used to make a deposit, even if the user initially paid with a debit card. This can reduce costs in a compliant way and reduce the risk of fraudulent payouts.

To do this, you can use our Verification API to verify a bank account is in the name of their user, and if so initiate a payout themselves via our Payouts API.

There are two different ways to use verified payouts:

• Account name check: verifies that the name on the gambling account matches the name on the bank account
• Transaction detection: verifies that a specific payment card deposit was made into the account being verified

To use each of these, you need to set different parameters.

📘

This feature is UK only

Before you start

Enable the correct scopes

To integrate with verified payouts, contact us to enable these scopes:

• payments
• info
• accounts
• transactions, if you are using the Transaction detection use case

Allowlist your redirect URI

Once a payout is created, redirect your user to the hosted page, and specify a return_uri as a parameter, to tell us where they want to redirect the end-user once the authorisation flow for the payout is completed.

The return_uri must be on the allowlist of redirect URIs for your client ID. You must also set your return_uri in Console.

To do this, contact us.

1. Create a payout including a verification object

First, initiate a Create Payout request. Set the beneficiary type to user_determined.

You must also include a verification object. This object represents the type of verification that they intend to run as part of the payout.

Within this object, specify which value you want to verify, and what you expect to see for that value.

Name only

If you are doing an account name check, specify a verification object as follows. Use the account_holder_name field within the verification object to

{
  ... Other payout fields ...
  
  "beneficiary": {
    "type": "user_determined",
    "reference": "a-sample-reference",
    "verification": {
      "account_holder_name": "John Doe" 
    },
    "provider_selection": { 
      "type": "user_selected"
    }
  }
}

Transaction verification

If you are using transaction detection, you need to include additional information. The transaction_search_criteria object contains the information that you are using to search for a specific transaction. Within this object, include an array of tokens such as a reference or beneficiary name. The array can include between 1 and 5 tokens.

"transaction_search_criteria": { 
        "tokens": [
          "18db38",
          "PoppyPower LTD",
          "LC PoppyPower"
        ],

The transaction description must contain an exact match of one of the tokens submitted. More than one matching transaction in a single account is acceptable.

You must also include an amount, currency and creation date for the transaction. We search within 5 days after the created_at date. For example, if the created_at date is 1 June 2024 (01-06-24), then all transactions from 1 June 2024 to 5 June 2024 may match. This also includes weekends and holidays.

This means that a full beneficiary object, with transaction verification, looks like this:

{
  ... Other payout fields ...
  
  "beneficiary": {
    "type": "user_determined",
    "reference": "a-sample-reference",
    "verification": {
      "transaction_search_criteria": {
        "tokens": [
          "18db38",
          "PoppyPower LTD",
          "LC PoppyPower"
        ],
        "amount_in_minor": 2000,
        "currency": "GBP",
        "created_at": "2024-05-07"
      }
    },
    "provider_selection": {
      "type": "preselected",
      "provider_id": "ob-barclays"
    }
  }
}

Example response

If the request succeeds, you receive a response that looks like this:

{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "status": "authorization_required",
  "resource_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

This response contains:

• a payout id
• an object indicating that the payout has the authorization_required status
• a resource_token for this specific payout, which you will use in the next step. Store this.

2. Create a link and send your user to the auth dialog

Next, you need to authorise the payout. To do this, you need to create a link,

1. Create a link to the auth dialog. Include:

• The payout_id (this is the id in the create payout response)
• The resource_token for the payout
• A return_uri where you want your user to be redirected.

https://app.truelayer.com/payouts?payout_id=92582476-69de-4ea8-baf2-e9a2972afbf9&resource_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c&return_uri=https://merchant-site.com/payout-return

2. When they follow the link, the user lands on the auth dialog, which displays a consent screen first with copy indicating what the user is consenting to. This will always include their full name and their account identifiers (sort code and account number). If you are using transaction detection, this will also include transaction history.

3. If the provider_selection object is set to user_selected in the Create payout request, the provider selection screen displays. The user selects the account that they want to receive the payout.
4. The user is redirected to the bank’s website or app, where they can authenticate by logging into their account.
5. The user is finally redirected to the return_uri that you specified earlier.

3. Wait for a verification result

When the user is redirected back to your site, the authorization process for the payout is already completed but the verification is typically still in progress. We recommend that you either wait for a payout webhook or poll the Get Payout endpoint using the id received as payout_id query parameter upon redirect.

4. Monitor a verified payout with webhooks

Terminal statuses for a payout are executed and failed. [Learn more about payout statuses]. If a payout fails, use the contents of the failure_stage and failure_reason fields to display meaningful error messages to users.

There are three failure reasons that can occur if verification fails:

Listen for webhooks to track the status of a verified payout. A successful payout results in a webhook like this:

{
    "type": "payout_executed",
    "event_id": "7183d229-f3c5-365f-6335-2be578a49cc3",
    "event_version": 1,
    "payout_id": "b0d2ab30-a9ef-4d8b-afea-0fd00cbb646e",
    "executed_at": "2025-05-20T10:16:11.517430Z",
    "beneficiary": {
      "type": "user_determined",
      "user": {
        "id": "755c1665-4916-439f-98af-024c7047e341"
      },
      "provider_id": "mock",
      "account_holder_name": "Transaction account 1", // This is usually a more significant AHN...
      "account_identifiers": [
        {
          "type": "sort_code_account_number",
          "sort_code": "040668",
          "account_number": "00003435"
        },
        {
          "type": "iban",
          "iban": "GB08CLRB04066800003435"
        }
      ]
    },
    "scheme_id": "faster_payments_service"
  }

The payout may fail at the verification stage, or it may pass verification but fail anyway. The differences between the webhooks are as follows:

{
   "type":"payout_failed",
   "event_id":"39d2377d-6d1d-327f-ac3c-7f96c0f145e6",
   "event_version":1,
   "payout_id":"e788dfe6-2dbc-4fad-9e0d-092f02726926",
   "failed_at":"2025-05-20T10:17:28.863946600Z",
   "failure_reason":"verification_name_mismatch",
   "beneficiary":{
      "type":"user_determined",
      "user":{
         "id":"8b178438-db0f-4807-a59f-6a432dc09fed"
      }
   }
}

{
    "type": "payout_failed",
    "event_id": "509aa1b4-f0b9-f8c7-0143-953dce019982",
    "event_version": 1,
    "payout_id": "570b4a2e-d393-446c-9aa5-2b9ebeff38b1",
    "failed_at": "2025-05-13T10:01:12.548168Z",
    "failure_reason": "insufficient_funds",
    "beneficiary": {
      "type": "user_determined",
      "user": {
        "id": "a5ae9bee-594f-432a-a4a9-23f1339bc59c"
      },
      "provider_id": "mock",
      "account_holder_name": "John Success",
      "account_identifiers": [
        {
          "type": "sort_code_account_number",
          "sort_code": "040668",
          "account_number": "00003435"
        },
        {
          "type": "iban",
          "iban": "GB08CLRB04066800003435"
        }
      ]
    }
  }