Documentation
Console

Make a verified payout

Suggest Edits

Verified payouts enable merchants to pay out to the same bank account as the debit card used to deposit (ie close the loop with debit card payment). This can reduce costs in a compliant way and reduce the risk of fraudulent payouts.

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 payment card deposit was made into the account being verified

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

Before you start

Enable the correct scopes

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

Note that the client is only expected to use the payments one while creating a verified payout.

[you only need payments to make the payment, but you need all the scopes to be enabled]

Allowlist your redirect URI

Once a payout is created, redirect their end-users to the HPP, 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.

If you are doing an account name check, specify a verification object as follows:

{
  ... Other payout fields ...
  
  "beneficiary": {
    "type": "user_determined",
    "reference": "a-sample-reference",
    "verification": {
      "account_holder_name": "John Doe" //account holder name as expected by the customer
    },
    "provider_selection": { 
      "type": "user_selected"
    }
  }
}

If you are using transaction detection, you need to include additional information about

  • XXX
  • XXX
  • XXX

Set the parameters of the verification object as follows:

{
  ... Other payout fields ...
  
  "beneficiary": {
    "type": "user_determined",
    "reference": "a-sample-reference",
    "verification": {
      "account_holder_name": "John Doe",
      "transaction_search_criteria": { // Check the specs for details about this object
        "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"
    }
  }
}

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
  1. 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.

[image]

  1. 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.

[image]

  1. The user is redirected to the bank’s website or app, where they can authenticate by logging into their account.

🚧

If the user selects multiple bank accounts at provider selection, the payout fails.

  1. 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.

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

Updated 2 months ago