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.

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`).
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`.
777-77-7777	Assigns 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-8888	Sends 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.

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.