Sandbox
Welcome to the developer documentation for the Yoti Doc Scan Sandbox.
With the Doc Scan sandbox, you are able to do the following:
- Set outcomes and mock text results
- Mock approvals and rejections
- Mock liveness and image upload
This guide assumes that you already have an existing Doc Scan environment set up to connect to Yoti’s production services, but wish to introduce sandbox testing on top. We recommend Getting started from the beginning to thoroughly understand the Doc Scan flow before integrating. This will ensure you create reliable tests that accurately simulate the production environment.
The Doc Scan Sandbox service 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.
For simplicity, an overview of the steps is shown below:
1 - Generating Sandbox Keys
2 - Creating a Sandbox session
3 - Setting the Doc Scan Sandbox Response Config
4 - Launching the user view
5 - Retrieving results and data
Endpoints
Sandbox - https://api.yoti.com/sandbox/idverify/v1Production - https://api.yoti.com/idverify/v1Generating Sandbox Keys
Our sandbox service requires its own set of sandbox keys. For further details on how to create these, please see Generate Sandbox API Keys.
Creating a Sandbox session
For details on how to create a Doc Scan session, please see Create a Session. A sandbox session will be created by substituting the Base URL for the Sandbox URL, and replacing your SDK ID and PEM file with your Sandbox keys.
Setting the Doc Scan Sandbox Response Config
Now you that have successfully created a session, the next step is to set the response config. Sandbox requires you to set an expected outcome for your tasks and checks. This will be an object with defined task_results and check_reports.
const { RequestBuilder, Payload } = require("yoti");const request = new RequestBuilder() .withBaseUrl("https://api.yoti.com/sandbox/idverify/v1") .withPemFilePath("<YOTI_KEY_FILE_PATH>") .withEndpoint("/sessions/<SESSION_ID>/response-config") .withPayload(new Payload(RESPONSE_CONFIG)) .withMethod("PUT") .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>") .build();//get Yoti responseconst response = request.execute();Task Results
Contains a result set for extracted text, defined by the document_fields property. This should be used to mock extracted text from documents. The format of the payload used here should contain properties listed from document fields explained.
{ "task_results": { "ID_DOCUMENT_TEXT_DATA_EXTRACTION": [ { "result": { "document_fields": { "full_name": "Test", "document_number": "TEST23123", "date_of_birth": "1980-12-20" } } } ] },}Check Results
A Doc Scan check can be one of the following:
- Document Authenticity
- Document Text Data Check
- Liveness
- Face Match
Sandbox will allow you to set a response for each of these checks.
Document Authenticity
{ "check_reports": { "ID_DOCUMENT_AUTHENTICITY": [ { "result": { "report": { "recommendation": { "value": "APPROVE" }, "breakdown": [ { "sub_check": "data_in_correct_position", "result": "PASS", "details": [] }, { "sub_check": "document_in_date", "result": "PASS", "details": [] }, { "sub_check": "expected_data_present", "result": "PASS", "details": [] }, { "sub_check": "fraud_list_check", "result": "PASS", "details": [] }, { "sub_check": "hologram" "result": "PASS", "details": [] }, { "sub_check": "hologram_movement", "result": "FAIL", "details": [] }, { "sub_check": "no_sign_of_tampering", "result": "PASS", "details": [] }, { "sub_check": "other_security_features", "result": "PASS", "details": [] }, { "sub_check": "real_document", "result": "PASS", "details": [] } ] } } } ], "async_report_delay": 1 } }Document Text Data Check
{ "check_reports": { "ID_DOCUMENT_TEXT_DATA_CHECK": [ { "result": { "report": { "recommendation": { "value": "APPROVE" }, "breakdown": [ { "sub_check": "text_data_readable", "result": "PASS", "details": [] } ] } } } ], "async_report_delay": 6 }}Liveness
{ "check_reports": { "LIVENESS": [ { "liveness_type": "ZOOM", "result": { "report": { "recommendation": { "value": "REJECT" }, "breakdown": [ { "sub_check": "liveness_auth", "result": "FAIL", "details": [] } ] } } }, { "liveness_type": "ZOOM", "result": { "report": { "recommendation": { "value": "APPROVE" }, "breakdown": [ { "sub_check": "liveness_auth", "result": "PASS", "details": [] } ] } } } ], "async_report_delay": 6 }}Face Match
{ "check_reports": { "ID_DOCUMENT_FACE_MATCH": [ { "result": { "report": { "recommendation": { "value": "APPROVE" }, "breakdown": [ { "sub_check": "ai_face_match", "result": "FAIL", "details": [ { "name": "confidence_score", "value": "0.53" } ] }, { "sub_check": "manual_face_match", "result": "PASS", "details": [] } ] } } } ], "async_report_delay": 6 }}Async report delay
The Async report delay is a timer (in seconds) which simulates a delay between the Doc Scan 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).
Full example response config
{ "task_results": {}, "check_reports": {}}Launching the user view
Once you have set your sandbox response config, you will need to fulfil the user view for Doc Scan. You may continue to render the Doc Scan Client through an iFrame, however the base_url will need to be updated first. The new sandbox iFrame URL is shown below:
https://api.yoti.com/sandbox/idverify/v1/web/index.html?sessionID=<inputsessionID>&sessionToken=<yoursessionToken>The user view must be completed. We are working on allowing this to be achieved programmatically instead of manually.
Retrieving results and data
Retrieving the media response is unchanged. You can still use the same get media endpoint, with the returning media ID from get session, but the base url should be updated to https://api.yoti.com/sandbox/idverify/v1 first.
For further details, please see Retrieve results and data.