Account holder verification

When you make a payout, an account holder verification check is performed on the beneficiary. In this process, the beneficiary’s name and account identifiers (sort code and account number) are checked against what is on file at the bank.

Make an account holder verification request

To verify a specific account holder, you need:

An account holder name
A sort code and account number, or an IBAN

Make a POST request to the /v3/account-holder-verifications/requests endpoint with this information:

{
  "account_holder_name": "John Doe",
  "account_identifier": {
	  "type": "sort_code_account_number",
    "sort_code": "123456",
    "account_number": "12345678"
  }
}

{
  "account_holder_name": "John Doe",
  "account_identifier": {
	  "type": "iban",
    "iban": "FR7630006000011234567890189"
}

In the API response, you receive an id for the request.

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

You do not receive any information on the status of the verification check in the response. To find out the result of the check, you need to make a GET request to the same endpoint, using the id you received in the response.

Monitor an account holder verification check

When you make an account holder verification check, it can have one of the following results:

Account holder verification is complete and the result was match
Account holder verification is complete and the result was partial_match , which also includes the account holder name
Account holder verification is complete and the result was no_match
Account holder verification is complete and the result was match_not_possible, which also includes a failure reason in plain English
The verification attempt failed.

You can Normally, the verification process takes a few seconds.

GET account holder verification

To see the status of a particular check, you can make a GET request to the /v3/account-holder-verifications/requests/{id} endpoint (where id is the ID of the request that you created earlier).

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "status": "pending"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "match_result": {
    "type": "match"
  }
}

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "completed",
  "match_result": {
    "type": "no_match"
  }
}

The response will contain:

the id of the verification request
You already submitted this in the previous step.
the status of the request
This can be pending, complete or failed.
the result of the check, if the check is completed or failed
This can be match, partial_match, no_match or match_not_possible.

If you receive a partial_match result, you also receive the account holder’s name in the response, so you can decide whether to move forward with the payout:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "completed",
  "match_result": {
    "type": "partial_match",
    "account_holder_name": "Jean D."
  }
}

If you receive a match_not_possible or failed response, you also receive a failure reason with information on why verification failed:

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "completed",
  "match_result": {
    "type": "match_not_possible",
    "failure_reason": "Bank unable to match"
  }
}

{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "status": "failed",
  "failure_reason": "provider_error"
}

If you receive a failed webhook or response to a GET request, we recommend retrying the check.

Webhooks

{
  "type": "account_holder_verification_completed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "account_holder_verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "match_result": {
    "type": "match"
  }
}

{
  "type": "account_holder_verification_completed",
  "event_version": 1,
  "event_id": "e2g7ggc3-h25f-74g7-d049-7798h8e77263",
  "account_holder_verification_id": "880h1733-h5ce-74h7-e049-7798h8e77263",
  "match_result": {
    "type": "no_match"
  }
}

{
  "type": "account_holder_verification_completed",
  "event_version": 1,
  "event_id": "d1f6ffb2-g14e-63f6-c938-6687g7d66152",
  "account_holder_verification_id": "770g0622-g4bd-63g6-d938-6687g7d66152",
  "match_result": {
    "type": "partial_match",
    "account_holder_name": "J Smith"
  }
}

{
  "type": "account_holder_verification_failed",
  "event_version": 1,
  "event_id": "c9e5eeb1-f03d-52e5-b827-5576f6c55041",
  "account_holder_verification_id": "660f9511-f3ac-52f5-c827-5576f6c55041",
  "failure_reason": "provider_error"
}

{
  "type": "account_holder_verification_completed",
  "event_version": 1,
  "event_id": "e2g7ggc3-h25f-74g7-d049-7798h8e77263",
  "account_holder_verification_id": "880h1733-h5ce-74h7-e049-7798h8e77263",
  "match_result": {
    "type": "match_not_possible",
    "failure_reason": "Bank unable to match"
  }
}