ClearBank

API

GBP Accounts

GBP Payments

Multi-currency, FX, & SCT UK

Embedded Banking

Know Your Customer (KYC)

Retail customer KYC

Using our retail customer KYC endpoint makes it easy to meet your due diligence requirements when onboarding customers. By simply sharing key customer information, you can conduct know your customer checks and receive the results via webhook.

For convenience, we'll also use the provided information to register a new customer if the checks succeed.

If you'd like access to this product, please speak to your Client Director.

Message flow diagrams

A message flow diagram demonstrating a successful KYC check. The client requests a check using the POST /v1/customercheck/retail endpoint, which is acknowledged by ClearBank with a 202 Accepted response. ClearBank performs the checks, results a success, and creates a new retail customer. ClearBank then emits a Retail Customer Application Successful webhook to the client, which includes a customer ID and an application ID. A message flow diagram demonstrating a KYC check that required additional information before succeeding or failing. The client requests a check using the POST /v1/customercheck/retail endpoint, which is acknowledged with a 202 Accepted response. ClearBank identifies further information is required to complete this check, and emits one or two Retail Customer Additional Info Required webhooks containing the required actions of the client's customer. The retail customer uploads the information, which is received by ClearBank. KYC checks then proceed, and an application declined or application successful webhook is sent - depending on the outcome of the check. A message flow diagram demonstrating a declined KYC check. The client requests a check using the POST /v1/customercheck/retail endpoint, which is acknowledged by ClearBank with a 202 Accepted response. ClearBank performs the checks, which are declined. ClearBank then emits a Retail Customer Application Declined webhook to the client, which includes the original application ID.

KYC check and create a new retail customer

post/customer-due-diligence/v1/retail/onboard

Use this endpoint to conduct KYC checks for a new retail customer. If the checks pass, the provided details are then used to create a new retail customer.

Parameters

  • Authorization string, header, Required

    Your API token, retrieved from the web portal.

  • DigitalSignature string, header, Required

    Signed hash of the body of the request. The hash is signed by your private key.

  • X-Request-Id string, header, Required

    A unique identifier for the request.

Request Payload (application/json)

  • customerData object, Required

request

{
  "customerData": {
    "name": {
      "firstName": "Adrien",
      "middleName": "Edin",
      "surname": "Reed-Myers"
    },
    "dateOfBirth": "1976-01-26",
    "nationality": [
      "GBR",
      "IRL"
    ],
    "taxResidency": [
      "GBR"
    ],
    "nationalInsuranceNumber": "AB112233C",
    "email": "example@emailprovider.co.uk",
    "mobile": "+447725666777",
    "currentAddress": {
      "buildingNameNumber": "22(A)",
      "streetName": "Long Road",
      "city": "York",
      "county": "Yorkshire",
      "postalCode": "YO31 7UH",
      "countryCode": "GBR"
    },
    "idvEmailsEnabled": true
  }
}
Code copied

Response (application/json)

  • 202 Accepted
  • 400 Bad Request

Accepted

{
  "applicationId": "aac7c700-1ea6-5664-8804-ceeb066d3cf5"
}
Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}
Code copied

Associated Webhooks

Webhooks

Simulating KYC webhooks

You can simulate successful and declined KYC webhooks - as well as additional information webhooks or emails - in our simulation environment.
To do this, call the POST /customer-due-diligence/v1/retail/onboard endpoint with the customerData.name.surname property set to:

  • "pass" to simulate a successful KYC webhook.
  • "fail" to simulate a declined KYC webhook.
  • "info" to simulate a KYC check requiring additional information. To receive an Additional Info Required webhook instead of an email, ensure the customerData.idvEmailsEnabled property is set to false.