Triggering KYC Scenarios

How to trigger various KYC scenarios in the sandbox, for example a request for verification documents.

Overview

As a way to trigger certain actions in the sandbox, Bond provides predefined Social Security Numbers. Using a specific SSN causes the related action to be triggered. For example, using the SSN 333-33-3333 causes KYC to generate a request for government_id, and can also be used for document upload testing.

In general, running a KYC in the sandbox results in a passing status and a corresponding kyc.verification.success webhook event. However, for testing purposes you might want to trigger other KYC scenarios.

The table below shows the predefined SSNs and what each of them triggers.

SSNTriggered action
000-00-0000Assigns the under review status to the KYC attempt and sends a kyc.verification.under_review webhook event.
111-11-1111Assigns a status of document_required and sends a kyc.verification.document_required webhook event with a document request for a social security card (ssc).
333-33-3333Assigns a status of document_required and sends a kyc.verification.document_required webhook event with a document request for a government_id.
777-77-7777Assigns a status of document_required and sends a kyc.verification.document_required webhook event with a request for two documents: government_id and social security card (ssc).
888-88-8888Sends a kyc.verification.timeout webhook event.

For information on triggering KYB scenarios, see Triggering KYB Scenarios.

Manually overriding KYC status

Bond gives you the ability to manually override the KYC status of a customer or Beneficial Owner in the sandbox to either passed or failed, and sending a corresponding webhook event. Doing so can assist you in testing your apps that require a customer or Beneficial Owner to have a specific KYC status.

To trigger KYC pass/failure, use the POST /simulate/kyc-pass or POST /simulate/kyc-fail operation and provide the body parameters as shown in the following table.

ParameterTypeDescription
customer_id
required
stringThe unique ID used to reference a customer resource, for example 931e2341-c3eb-4681-97d4-f6e09d90da14.
program_id
required
stringProgram UUID, for example 72585109-8222-4221-b15b-48e87ffed790.

An example of a request to change the KYC status to passed is shown below.

curl --request POST \
     --url https://sandbox.bond.tech/api/v0/simulate/kyc-pass \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '
{
     "customer_id": "931e2341-c3eb-4681-97d4-f6e09d90da14",
     "program_id": "b1dc430b-3892-47f0-a27c-ec05f8c428db" 
}
'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/simulate/kyc-pass")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'
request.body = "{\"customer_id\":\"931e2341-c3eb-4681-97d4-f6e09d90da14\",\"program_id\":\"b1dc430b-3892-47f0-a27c-ec05f8c428db\"}"

response = http.request(request)
puts response.read_body
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  },
  body: JSON.stringify({
    customer_id: '931e2341-c3eb-4681-97d4-f6e09d90da14',
    program_id: 'b1dc430b-3892-47f0-a27c-ec05f8c428db'
  })
};

fetch('https://sandbox.bond.tech/api/v0/simulate/kyc-pass', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://sandbox.bond.tech/api/v0/simulate/kyc-pass"

payload = {
    "customer_id": "931e2341-c3eb-4681-97d4-f6e09d90da14",
    "program_id": "b1dc430b-3892-47f0-a27c-ec05f8c428db"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0/simulate/kyc-pass");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
request.AddParameter("application/json", "{\"customer_id\":\"931e2341-c3eb-4681-97d4-f6e09d90da14\",\"program_id\":\"b1dc430b-3892-47f0-a27c-ec05f8c428db\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"customer_id\":\"931e2341-c3eb-4681-97d4-f6e09d90da14\",\"program_id\":\"b1dc430b-3892-47f0-a27c-ec05f8c428db\"}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/simulate/kyc-pass")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

Response response = client.newCall(request).execute();

When the request is submitted a webhook event is sent, an example of which is shown below.

{
  "event": "kyc.verification.success",
  "customer_id": "931e2341-c3eb-4681-97d4-f6e09d90da14",
  "occurred_at": "2021-10-17T11:25:37.369236+00:00"
}

An example of a response to a successful request to change the KYC status is shown below.

{
  "customer_id": "931e2341-c3eb-4681-97d4-f6e09d90da14",
  "kyc_status": "passed"
}
{
  "customer_id": "931e2341-c3eb-4681-97d4-f6e09d90da14",
  "kyc_status": "failed"
}

For a complete specification and interactive examples, see Simulate KYC passed and Simulate KYC failed in the Bond API Reference.