Customising Sandbox Test Data

As a Smile ID partner, you will interact with our system in two different environments - Sandbox and Production. The Sandbox environment enables you to test and try out our products using the test data we have provided. However, you cannot query any live ID authority databases or lists. The Production environment lets you run jobs using real ID information.

We provide you with ID numbers that cater to multiple scenarios. However, there are times when you might want to customise the response we send back when you use our test data.

You can customise the test value returned for any of our standardised top-level keys.

Mocking Results in Sandbox Environment

The SmileID sandbox environment allows you to simulate various result states for testing purposes. By leveraging mock responses, you can ensure your integration handles all possible outcomes effectively. This guide outlines how to achieve successful, rejected or provisionally approved results using specific parameters in your requests.

How to Mock Results

To mock results, include the sandbox_result key as string value "0", "1" or "2" in the partner params section of your request payload. This parameter can be used across REST APIs, Web SDKs, and Mobile SDKs. The value assigned to sandbox_result determines the outcome returned by the sandbox.

Available States and Keys

Result State	Key Value
Approval	"sandbox_result":"0"
Rejection	"sandbox_result":"1"
Provisional	"sandbox_result":"2"

Below is an example of how to include the sandbox_result parameter in a request payload.

Example Usage

Use the following JSON payload as a base for testing. Update the sandbox_result value to "0", "1", or "2" depending on the result state you wish to simulate.

{
    "country": "NG",
    "id_number": "00000000004",
    "id_type": ​​"NIN_V2",
    "partner_id": "<your partner_id>",
    "partner_params": {
        "job_id": "985c594e-7e67-4f2e-a6e0-3be127dbb6a0",
        "job_type": 5,
        "user_id": "887ceeea-e9fd-4f96-aa58-d4b12d0b5f98",
        "sandbox_result": "0"
    },
    "signature": "--- generated signature ---",
    "timestamp": "2021-03-07T13:23:24.591Z"
}

Notes

• The sandbox_result parameter is only available in the sandbox environment and does not affect production.

• Ensure you remove the sandbox_result key when transitioning your integration to production.

• Use this functionality to test various scenarios and validate your application’s behavior under different conditions.

Customising the Response for Basic KYC and Enhanced KYC

Getting Started Checklist

To get started, please take note of the following:

• Identify the ID type you want to customise its data.

• Get the “custom-response” test ID number for your chosen ID type (note all custom-response test ID numbers end with a “4”). The test ID numbers for each ID type can be found on the documentation page dedicated to the ID type.

• Identify the top-level keys typically returned for the ID type. The information can be found on the documentation page dedicated to the ID type.

• Decide which top-level keys returned for the ID type you want to customise.

Running a Job with a Custom Data Request

Once you have all the items above, you can proceed to run the sandbox job with a custom request. To customise the value of any fields, you need to specify the top-level key in the partner params object of the request body.

Sample Request for an Enhanced KYC run with Custom Data

{
    "country": "NG",
    "id_number": "00000000004",
    "id_type": ​​"NIN_V2",
    "partner_id": "--",
    "partner_params": {
        "FullName": "Nelson Mandela",
        "job_id": "985c594e-7e67-4f2e-a6e0-3be127dbb6a0",
        "job_type": 5,
        "user_id": "887ceeea-e9fd-4f96-aa58-d4b12d0b5f98"
    },
    "signature": "---",
    "timestamp": "2021-03-07T13:23:24.591Z"
}

Response

{
  "Actions": {
    "Return_Personal_Info": "Returned",
    "Verify_ID_Number": "Verified"
  },
  "Address": "10, Workbox, Ojora Close, Victoria Island, Lagos, Lagos Island, Lagos",
  "Country": "NG",
  "DOB": "2000-09-20",
  "Document": "Not Available",
  "ExpirationDate": "Not Available",
  "FullData": {
    "birthcountry": "Not Available",
    "birthdate": "2000-09-20",
    "birthstate": "",
    "centralID": "",
    "documentno": "",
    "educationallevel": "tertiary",
    "email": "",
    "employmentstatus": "",
    "firstname": "Nelson",
    "FirstName": "Nelson",
    "FullName": "Nelson Mandela",
    "gender": "Male",
    "height": "****",
    "LastName": "Mandela",
    "maidenname": "",
    "maritalstatus": "single",
    "message": "Results Found",
    "middlename": "",
    "MiddleName": "",
    "nationality": "Nigeria",
    "nin": "00000000000",
    "nok_address1": "10, Workbox, Ojora Close, Victoria Island, Lagos",
    "nok_address2": "10, Workbox, Ojora Close, Victoria Island, Lagos",
    "nok_firstname": "Joe",
    "nok_lastname": "Leo",
    "nok_lga": "Lagos Island",
    "nok_middlename": "",
    "nok_postalcode": "",
    "nok_state": "Lagos",
    "nok_town": "Lagos",
    "nspokenlang": "YORUBA",
    "ospokenlang": "",
    "othername": "",
    "pfirstname": "",
    "photo": "/9j/4AAQSk---",
    "place": "Victoria Island",
    "pmiddlename": "",
    "profession": "STUDENT",
    "psurname": "",
    "residence_AddressLine1": "10, Workbox, Ojora Close, Victoria Island, Lagos",
    "residence_AddressLine2": "10, Workbox, Ojora Close, Victoria Island, Lagos",
    "residence_lga": "Lagos Island",
    "residence_state": "Lagos",
    "residence_town": "Lagos State",
    "residencestatus": "birth",
    "self_origin_lga": "",
    "self_origin_place": "",
    "self_origin_state": "",
    "state": "",
    "success": true,
    "surname": "Mandela",
    "telephoneno": "0123456789",
    "title": "mr",
    "trackingId": ""
  },
  "FullName": "Nelson Mandela",
  "Gender": "Male",
  "IDNumber": "00000000004",
  "IDType": "NIN",
  "IssuanceDate": "2000-01-01",
  "PhoneNumber": "0123456789",
  "PhoneNumber2": "Not Available",
  "Photo": "/9j/4AAQSk --- truncated",
  "ResultCode": "1012",
  "ResultText": "ID Number Validated",
  "SmileJobID": "0000000164",
  "PartnerParams": {
    "FirstName": "Nelson",
    "FullName": "Nelson Mandela",
    "job_id": "985c594e-7e67-4f2e-a6e0-3be127dbb6a0",
    "job_type": 5,
    "LastName": "Mandela",
    "MiddleName": "",
    "user_id": "887ceeea-e9fd-4f96-aa58-d4b12d0b5f98"
  },
  "signature": "---",
  "Source": "ID API",
  "timestamp": "2021-03-07T13:23:24.591Z"
}

Customising the Response for Biometric KYC

To receive successful Biometric KYC responses in the Sandbox, the image returned using the test data must match the selfie provided. This means the test data photo returned must be customised.

Getting Started Checklist

To get started, please take note of the following:

• Identify the ID type whose data you want to customise.

• Obtain the "custom-response" test ID number for your chosen ID type (note all custom-response test ID numbers end with a “4”). The test ID numbers for each ID type can be found on the documentation page dedicated to that ID type.

• Identify the top-level keys typically returned for the ID type. This information can be found on the documentation page dedicated to that ID type.

• In addition to the Photo key, identify other top-level keys returned for the ID type you want to customise.

Running a Successful Sandbox Biometric KYC Job with Custom Data

• Add a "Photo" key and its base64 string, along with other keys you intend to customise, to the "partner_params" object when making an upload URL request. See the JSON sample below.

{
    "callback_url": "webhook.example.site",
    "file_name": "Archive.zip",
    "model_parameters": {},
    "partner_params": {
      "job_id": "job_58627dfc-dc6b-4ce2-8dad-d906219c79b8",
      "job_type": 1,
      "Photo": "/9j/4AAQSkZJRgA- SAMPLE Base64 - LISOad5n1/OolQYz607YK/2Q==",
      "user_id": "user_a1d60852-5d82-4875-ac40-c76c64e2593a"
    },
    "signature": "--",
    "smile_client_id": "--",
    "source_sdk_version": "1.0",
    "source_sdk": "rest_api",
    "timestamp": "2021-03-07T13:23:24.591Z",
    ...
}

You can only use photos that are smaller than 300KB in size.

• If you are using the REST API, in your "info.json" file, provide another base64 image string of the same person, but not the identical image, as using the exact same image will trigger a spoof detection and the job will be rejected.

If you are using one of the mobile SDKs, you can skip editing the info.json section.

Ensure you use "id_number" values from our provided test data for your tests, specifically, the ones ending in "4".

Your "info.json" file should look like this before it is zipped.

{
  "id_info": {
    "country": "NG",
    "dob": "",
    "entered": true,
    "first_name": "",
    "id_number": "00000000004",
    "id_type": "NIN",
    "last_name": "",
    "middle_name": ""
  },
  "images": [
    {
      "file_name": "",
      "image_type_id": 2,
      "image": "base64 encoded image string"
    }
  ],
  "package_information": {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  }
}