Account holder verification in payouts

As part of the EPC regulations around verification of a payee, every payout to an external beneficiary account undergoes a name check. If the result is a non-match result -- which means the result is partial_match, no_match or match_not_possible -- the payout automatically fails.

For these situations, you can choose to push through with the payout anyway, by creating a payout to that user with the beneficiary.type of verified_external_account. If you use this beneficiary type, you can also include two other fields:

• account_holder_verification_id (required), which is a unique ID attached to that instance of account verification.
• override_bank_matched_name (optional), which in the case of a partial_match indicates whether to use the account holder name on file at the bank or use the one you supplied in your verification check.

You can choose whether to proceed with a payout that has a non-match result. You could opt to take a more simple approach and proceed with all payouts that returned a partial_match account verification check, or you may choose to make more nuanced decisions based on other data sources available to you to proceed with a payout that returned partial_match.

Match scenarios

If a verification name check returns a match_result of match, the payout will be executed.

The payout_executed webhook will return the account_holder_verification_id. Using this id will allow you to make future payout requests without initiating an account holder name check, by using the beneficiary.type of verified_external_account.

Below is an example Create Payout request, with the verified_external_account beneficiary type.

{
  "id": "0a495e9f-2f41-4669-ba33-85407c0b26cb",
  "merchant_account_id": "24089aed-4fd4-9e13-f8b2-f458f30c836c",
  "amount_in_minor": 100,
  "currency": "EUR",
  "beneficiary": {
    "type": "verified_external_account",
    "account_holder_verification_id": "f8c3a9e0-69ae-4918-b5b2-4d8f91e4e1af",
    "override_bank_matched_name": true,
  }
}

You can get the account_holder_verification_id from a previously executed/failed external_account payout (which included an account holder verification check). This ID appears in the following webhooks:

• account_holder_verification_completed
• account_holder_verification_failed

You also receive this ID in successful responses from the Get Payout endpoint, inside the account_holder_verification object. Below is an example:

{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "merchant_account_id": "ae094a73-d874-4241-a65f-6dcda7ac07b1",
  "amount_in_minor": 100,
  "currency": "GBP",
  "beneficiary": {
    "type": "external_account",
    "reference": "a-reference",
    "account_holder_name": "John Doe",
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "123456",
        "account_number": "12345678"
      }
    ],
    "account_holder_verification": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "match_result": {
        "type": "match"
      }
    }
  },
  "scheme_id": "faster_payments_service",
  "created_at": "2021-12-25T14:00:00.000Z",
  "status": "executed",
  "executed_at": "2021-12-25T15:00:00.000Z",
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  }
}

You can also get the account_holder_verification.id from webhooks. You can then use this to perform a name check on a customer’s account before initiating a payout by using the beneficiary.type verified_external_account.

Non-match scenarios

If the verification check does not result in a match -- meaning you receive a partial_match, no_match or match_not_possible result -- the initial payout request will fail. Find details of the account verification result in both the Get payout endpoint and the payout_failed webhook.

For these situations, you can choose to push through with the payout anyway by creating a followup payout request and using the beneficiary.type of verified_external_account. If you use this beneficiary type, there are two additional fields that you must provide values for:

• account_holder_verification_id, which is a unique ID attached to that instance of account verification.

  You can get this ID from the following sources:

  • Payout webhooks
  • Get payout API request
  • Account holder verification API request
  • Account holder verification webhooks

• override_bank_matched_name, which in the case of a partial match indicates whether to use the account holder name on file at the bank or use the one you supplied in your initial verification check.
  If you don't provide this, the default is false and the bank matched name is used.

Below is an example Create Payout request, with the verified_external_account beneficiary type. In this case, the override_bank_matched_name value is set to true because the merchant wants to use the name on file they have at hand, not the name returned by the bank in the verification request.

{
  "id": "0a495e9f-2f41-4669-ba33-85407c0b26cb",
  "merchant_account_id": "24089aed-4fd4-9e13-f8b2-f458f30c836c",
  "amount_in_minor": 100,
  "currency": "EUR",
  "beneficiary": {
    "type": "verified_external_account",
    "account_holder_verification_id": "f8c3a9e0-69ae-4918-b5b2-4d8f91e4e1af",
    "override_bank_matched_name": true,
  }
}

You also receive this ID in successful responses from the Get Payout endpoint, inside the account_holder_verification object.

Below is an example:

{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "merchant_account_id": "ae094a73-d874-4241-a65f-6dcda7ac07b1",
  "amount_in_minor": 100,
  "currency": "EUR",
  "beneficiary": {
    "type": "external_account",
    "reference": "a-reference",
    "account_holder_name": "John Doe",
    "account_identifiers": [
      {
        "type": "iban",
        "iban": "FR1234567890123"
      }
    ],
    "account_holder_verification": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "match_result": {
        "type": "match"
      }
    }
  },
  "scheme_id": "faster_payments_service",
  "created_at": "2021-12-25T14:00:00.000Z",
  "status": "executed",
  "executed_at": "2021-12-25T15:00:00.000Z",
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  }
}