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-2222 causes KYC to generate a request for two ID documents, government_id and proof_of_address, 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.

SSN

Triggered action

000-00-0000

Assigns the under review status to the KYC attempt and sends a kyc.verification.under_review webhook event.

111-11-1111

Assigns a status of document_required and sends a kyc.verification.document_required webhook event with a document request for a social security card (ssc).

222-22-2222

Assigns a status of document_required and sends a kyc.verification.document_required webhook event with a document request for a utility_bill.

333-33-3333

Assigns a status of document_required and sends a kyc.verification.document_required webhook event with a document request for a government_id.

333-33-2222

Causes KYC to generate a request for two ID documents, government_id
and proof_of_address. Also used for testing document uploads.

777-77-7777

Assigns a status of document_required and sends a kyc.verification.document_required webhook event with a request for three documents; government_id, proof_of_address, and ssc.

888-88-8888

Sends a kyc.verification.timeout webhook event.

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.

Parameter

Type

Description

customer_id
required

string

The unique ID used to reference a customer resource, for example 931e2341-c3eb-4681-97d4-f6e09d90da14.

program_id
required

string

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

Triggering KYB conditions

You can use the ein and legal_business_name properties of a Business resource to trigger various KYB events in the sandbox environment, as shown in the table below.

Mock event

Business resource

kyb.verification.warning

{
"ein": "11-0000099"
}

kyb.verification.rejected

{
"ein": "11-0000099",
"legal_business_name": "Unregistered Business"
}

kyb.verification.approved

Any


Did this page help you?