Triggering KYC Scenarios

How do you 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 special case, 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.

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

SSN

Triggered action

999-99-0000

Simulates a kyc.verification.failure event due to a bureau failure.

999-99-1111

Simulates an ofac failure.

999-99-2222

Simulates a bureau and an ofac failure.

111-11-1111

Simulates a kyc.verification.document_required with a request for a ssc
(social security card).

222-22-2222

Simulates a kyc.verification.document_required with a request for a utility_bill,
(property tax statement, gas, phone, electricity bill, and so on).

333-33-3333

Simulates a kyc.verification.document_required with a request for a government_id,
(driver’s license, passport, and so on).

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

Simulates a kyc.verification.document_required with a request for all three
document types, (ssc, utility_bill, and government_id).

123-45-6789

Triggers the Knowledge Based Authentication process.

Manually overriding KYC status

Bond Studio gives you the ability to manually override the KYC status of a customer or Beneficial Owner in the sandbox to either passed or failed. 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?