Sandbox Integration Guide

Welcome to the free Identity verification Sandbox! The sandbox is an isolated test environment, intended to easily create test cases using dummy data where it's not feasible to test your integration with live data.

The sandbox environment will allow you to:

• Set outcomes and mock text results
• Mock approvals and rejections
• Mock liveness and image upload

The main difference between our Yoti production services and sandbox is the sandbox bypasses real world checks and tasks. Instead, you must specify the outcome beforehand, as opposed to it being returned from Yoti’s production systems.

This is achieved by using an additional response-config endpoint. A response-config must be set before proceeding with the user view for sandbox setups.

An overview of the steps is shown below:

Step 1: Generating sandbox keys

Step 2: Installing the sandbox SDK

Step 3: Generating a sandbox session

Step 4: Configuring the response(breakdown version available too)

Step 5: Launching the user view

Supported Languages

Just like the normal Yoti Client, the Yoti Sandbox Client SDK is available in seven languages:

• Javascript (Node.js)
• Ruby
• PHP
• Python
• .NET

Install the Sandbox SDK

Once you have generated your keys, you can continue with installing the Sandbox SDK into your backend.

Just like our production integration, the Yoti Sandbox Client SDK is available in seven languages and installing is easy through popular package managers.

// Doc Scan Client (skip if already installed)

npm install -S -E yoti

​

// Sandbox

npm install -S -E -D @getyoti/sdk-sandbox

The sandbox client is packaged separately to the production Yoti client enabling it to be used as a development dependency.

Initialising the sandbox client

You will need your Sandbox Client SDK ID and PEM file created from the Yoti Hub to initialise the sandbox client.

Please do not open the pem file as this might corrupt the key and you will need to create a new sandbox key.

// Point the IDV Client at the sandbox by setting environment variable 

// YOTI_IDV_API_URL to https://api.yoti.com/sandbox/idverify/v1

​

const { IDVClient } = require('yoti');

const fs = require('fs');

​

const SANDBOX_CLIENT_SDK_ID = 'SANDBOX_CLIENT_SDK_ID';

const PEM = fs.readFileSync('/path/to/your-pem-file.pem', 'utf8');

​

const idvClient = new IDVClient(SANDBOX_CLIENT_SDK_ID, PEM);

// Alternatively - const idvClient = new IDVClient(SANDBOX_CLIENT_SDK_ID, PEM, { apiUrl: 'sandbox-api-url' });

Configuring the sandbox client

const { SandboxIDVClientBuilder } = require('@getyoti/sdk-sandbox');

​

const sandboxClient = new SandboxIDVClientBuilder()

  .withClientSdkId(SANDBOX_CLIENT_SDK_ID)

  .withPemString(PEM)

  .build();

Generating a sandbox session

A sandbox session will be created by

1) Replace the base URL with the Sandbox URL.

2) Replace the SDK ID

3) Replacing the pem file.

Sandbox - https://api.yoti.com/sandbox/idverify/v1

Production - https://api.yoti.com/idverify/v1

Configure the responses

Sandbox requires you to set an expected outcome for your tasks and checks.

Below is a snippet of a full response config for all checks and tasks. These values are provided to mock the return output of fetching the completed session. For a further explanation there is a breakdown version below.

const {

  SandboxIDVClientBuilder,

  SandboxBreakdownBuilder,

  SandboxRecommendationBuilder,

  SandboxDocumentAuthenticityCheckBuilder,

  SandboxCheckReportsBuilder,

  SandboxResponseConfigBuilder,

  SandboxDocumentTextDataCheckBuilder,

  SandboxTaskResultsBuilder,

  SandboxZoomLivenessCheckBuilder,

  SandboxDocumentFaceMatchCheckBuilder,

  SandboxDocumentTextDataExtractionTaskBuilder,

} = require('@getyoti/sdk-sandbox');

​

const sandboxClient = new SandboxIDVClientBuilder()

  .withClientSdkId('YOUR_SANDBOX_SDK_ID')

  .withPemString('YOUR_PEM_FILE')

  .build();

​

const sessionId = "YOUR_SANDBOX_SESSION_ID"

​

async function configureSessionResponse() {...}

​

configureSessionResponse();

Async report delay

The Async report delay is a timer (in seconds) which simulates a delay between the Identity verification iFrame user journey and the result of the report, set by your expectation. By using this facility you can effectively handle pending states, or results that are not returned instantly (such as manual checks).

Sandbox Breakdown

This section will go into detail on each task and check with the configuration split out.

Task Results

Data extraction task (ID Document)

The task result contains the extracted text, defined by the document_fields property. This should be used to mock extracted text from documents.

const {

  SandboxDocumentTextDataExtractionTaskBuilder,

} = require('@getyoti/sdk-sandbox');

​

const textExtractionConfig = new SandboxDocumentTextDataExtractionTaskBuilder()

  .withDocumentFields({

    full_name: 'John Doe',

    nationality: 'GBR',

    date_of_birth: '1986-06-01',

    document_number: '123456789',

  })

  .build();

Data extraction task (Supplementary Document)

The supplementary task result contains the extracted text from the supplementary document, also defined by the document_fields property. This should be used to mock extracted text from supplementary documents.

​

Check Results

Sandbox will allow you to set a response for each of the checks Identity verification offers. Below are examples of the check result.

Document Authenticity

Yoti performs a numerous amount of sub checks on the document submitted, in order to simulate this report request you will need to understand the document report. Yoti will provide a recommendation for the authenticity of the document which you can mock using this service.

Data extraction check (ID Document)

Yoti will provide a recommendation for the text data extraction which will contain the sub-check text_data_readable which will either be a PASS or a FAIL.

Data extraction check (Supplementary Document)

Similar to ID Document data entry, a Text data check may be generated if a Supplementary document goes for manual data entry. This block would mock the relevant response:

Liveness

Liveness checks can be retried if failed, depending on specified limited set when generating the session. Each try will generate a new breakdown in the response. The check will either be approved or rejected based on the result of the liveness check which is a pass/fail result. For more information head over to our production service.

Face Match

The face match check will give a recommendation based on these as either APPROVE or REJECT which can be mocked on sandbox.

A pass/fail result is returned if a manual check is also done, along with a confidence score (between 0 and 1) depending on how successful the match is, Yoti offers a PASS score if the confidence score is over 0.7. or more information head over to our production service documentation.

Completing the session

Once you have set your sandbox response config, you will need to complete the session for Identity verification. This will populate the media and will complete the session.

The Agent endpoint /agent uses the SDK ID and .PEM file for authorisation.

Body

Responses

Retrieving images and user information

Retrieving the media response is the same as production. Please ensure your base URL is updated to the below:

For further details, please see Understanding the report.