User ID verification by SDK

Fraud is always spearheading. Luckily, so is our technology. Using the best combination of human and machine learning fraud spotting, we protect your business against the 6 key types of document fraud:

• Forged documents

• Counterfeit documents

• Blank stolen documents

• Fantasy or camouflage documents

• Impostor or ‘look-a-like’ documents

• Compromised documents

Conventionally, you have to rely on signals to trust a new user - on a device IP, a phone number, or credit database look-up. But these signals can also be exploited by imposters. This creates constant uncertainty, so you can’t focus on the user's experience, and instead start treating them with doubt.

nCore platform integrated with the document verification service provider called Onfido which lets your users scan a photo ID from their mobile device, before checking if it's genuine.

Please note that the Identity verification is applicable only for a user type INDIVIDUAL. In addition to that, user identity verification is only applicable for the customers who are using the SDK to upload documents.

High level identity verification steps

The high level identification verification steps are given below:

1. Enable tenant level settings

2. Create webhook i.e. IDENTITY_VERIFICATION

3. Create a user

4. Receive webhook having applicant ID and SDK token

5. Initialize SDK and Upload documents via Mobile SDK

6. Inform document uploaded successfully after a successful upload

7. Identification verification processing started by nCore platform

8. Identification verification processing finished successfully, the user is transitioned from PENDINGIDVERIFICATION to PENDINGKYC

9. nCore platform Inform by a webhook notification that the process is completed successfully

Step by Step process

Step by step process is given below to configure and perform a successful identification verification process.

Tenant level settings

Following are the settings that are required to be enabled at tenant level for Identity Verification.

Field Name	Field Type	Description
require_document_verification	boolean	This check enables the identity verification process.
checks	enum	Following are the checks you can request to enable at tenant level as per your business need DOCUMENT FACIAL_SIMILARITY_VIDEO
privacy_notices_read_consent_given	boolean	This parameter indicates that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido. This parameter should be set to true after gaining the necessary consent, and if it's set to false the request will fail with a validation error.

Create a webhook

Now create a webhook event as “IDENTITY_VERIFICATION” for receiving a webhook event for applicant id and SDK token generation as shown below:

POST /webhooks

{ "endpoint": "https://example.com/", "events": [ "IDENTITY_VERIFICATION" ], "config": { "basic_auth_username": "username", "basic_auth_password": "password", "custom_headers": [ { "header_name": "apikey", "header_value": "306e38e4-54be-469f-beca-4297129289d6" } ], "created": "2012-05-04T19:42:32.987Z", "modified": "2012-05-04T19:42:32.987Z" } }

Create a user

After enabling webhook endpoint, you can create a user by sending a POST request to /users endpoint. Since the parameter require_document_verification is enabled as true at tenant level which means that the user will be created with a user status as PENDINGIDVERIFICATION.

POST /users

{ "first_name": "John", "middle_name": "Anthony", "last_name": "Smith", "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57", "user_type": "INDIVIDUAL", }

The above sample is given just for reference, please refer to the API Catalog for a complete payload.

Below you can find important restrictions:

1. 'first_name' and 'last_name' parameters are required in the user profile.

2. If address is provided in the user profile, then 'postal_code' and 'country' become required. You can use a postal code of "00000" for countries that do not support postal codes.

3. The 'postal_code' of the applicant's address. For UK postal codes, specify the value in the following format: SW4 6EH.

4. USA as a country is not supported ('address' > 'country').

5. For addresses, the following characters are forbidden: !$%^*=<>.

6. For names, the following characters are forbidden: ^!#$%*=<>;{}".

Receive a notification

Once the user is created successfully, you will receive a webhook notification along with the following details as given below:

Webhook notification sample

{ "event": "IDENTITY_VERIFICATION", "user_id": "055ef899-9650-4700-9497-e71826dd2825", "applicant_id": "generated applicant id", "sdk_token": "generated token", "note": "", "status": "PENDINGIDVERIFICATION", "old_status_reason_code": "", "status_reason_code": "I0", "status_description": "", "created": "2018-01-02T19:42:32.987Z", "modified": "2018-01-02T19:42:32.987Z" }

The system will send a webhook notification event "IDENTITY_VERIFICATION" along with a status_reason_code as "B1" if the user is not verified.

Please note that the SDK token expires in 90 mins.

To renew the SDK token, send a PUT request to /user/{id}:changeStatus endpoint with a value as “B2” in 'status_reason_code' field and ”PENDINGIDVERIFICATION” in 'status' field as shown below:

PUT /user/{id}:changeStatus

{ "status": "PENDINGIDVERIFICATION", "status_reason_code": "B2", }

Be aware that the 'status_reason_code' B2 has been added just for testing purposes, the system should not update the 'status_reason_code' from I0 to B2.

Upload the documents for verification

Now your mobile app user can start uploading the documents.

Prerequisite for this step: The integration between the mobile app user and your backend system.

Trigger user status change for a successful document upload

Once the documents are uploaded successfully, you can send a PUT request to /user/{id}:changeStatus endpoint with a value as “B0” in status_reason_code field and ”PENDINGIDVERIFICATION” in status field as shown below:

PUT /user/{id}:changeStatus

{ "status": "PENDINGIDVERIFICATION", "status_reason_code": "B0", "note": "Users documents are uploaded successfully" }

IDV re-initiation flow

Below you can find IDV re-initiation flow:

• At first you send PUT request to /user/{id}:changeStatus endpoint to re-initiate IDV process by changing user status from PENDINGIDVERIFICATION B1, B5 or B6 to PENDINGIDVERIFICATION B2.

• Documents are re-uploaded; then you send PUT request to /user/{id}:changeStatus endpoint to change user status from PENDINGIDVERIFICATION B2 to PENDINGIDVERIFICATION B0.

• System will decline IDV re-initiation in case Onfido replies back with "SUSPECTED" or "REJECTED" status. In this case, user status will be updated to "TERMINATED".

Document verification internal process

nCore platform starts identity verification internally.

Receive a successful identity verification notification

Identification verification processing completed successfully, the user is transitioned from PENDINGIDVERIFICATION to PENDINGKYC and you will receive a user status change notification (if configured) as given below.

User status change notification

{ "event":"USER_STATUS_CHANGE", "User_status_change":{ "id": "cf2de83b-ac68-441b-bc54-21de60014d57", "title": "MR", "first_name": "John", "middle_name": "Anthony", "last_name": "Smith", "native_name": "John Smith", "date_of_birth": "2021-10-25T12:47:04.361Z", "email": "[e-mail]", "mobile": "[phone]", "address": { "address_line1": "Flat 1904", "address_line2": "Glass Tower", "city": "New York City", "state": "New York", "postal_code": "12345", "country": "USA" }, "gender": "MALE", "preferred_language": "EN", "place_of_birth": "Las Vegas", "nationality": "USA", "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57", "created": "2021-10-25T12:47:04.361Z", "modified": "2021-10-25T12:47:04.361Z", "country_residence": "USA", "country_tax_residence": "USA", "employment_type": "SALARIED", "employment_title": "string", "monthly_salary": 0, "company_name": "string", "company_address": { "address_line1": "Flat 1904", "address_line2": "Glass Tower", "city": "New York City", "state": "New York", "postal_code": "12345", "country": "USA" }, "company_country": "USA", "industry_type": "I01", "expected_monthly_balance": 0, "relationship_with_parent": "SON", "user_type": "INDIVIDUAL", "business_legal_name": "string", "business_dba_name": "string", "date_established": "2021-10-25T12:47:04.362Z", "phone_number": "[phone]", "website": "string", "status": "PENDINGKYC", "status_reason_code": "I0", "kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY" } }

Also you can check the status by sending a GET request to /user/{id} endpoint:

GET /users/{id}

Response

{ "id": "cf2de83b-ac68-441b-bc54-21de60014d57", "title": "MR", "first_name": "John", "middle_name": "Anthony", "last_name": "Smith", "user_type": "INDIVIDUAL", "status": "PENDINGKYC", "status_reason_code": "I0", "kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY" }

The above sample is given just for reference, please refer to the API Catalog for a complete payload.

IDV Re-verification upon document expiration

Background: INDIVIDUAL users who are already verified but their documents have either expired or about to expire. To cater to that, we will introduce a mechanism for IDV re-verification.

New settings (configured on NymCard side):

"expired_idv_policy":        
{
  "days_prior_expiration": 30, (attached is a file to explain the expiration date calculation)
  "applicable_user_status": [ "ACTIVE"]  (applicable to ACTIVE users for now)
}

Cron Job

a. read tenant level settings related to expired_idv_policy

b. pick INDIVIDUAL users and check for the expiry date of their documents

c. update user status_reason_code to A6 if their documents have expired or about to expire

d. Fintechs will receive webhook with status A6, then they need to start below mentioned process:

• Change the (ACTIVE) user 'status_reason_code' to B2E (works exactly the same as B2) to generate a new IDV token and ask the end-user to upload his documents again

• Update the (ACTIVE) user 'status_reason_code' to B0E (works exactly the same as B0) once the documents are uploaded to initiate the IDV process

If the report is CLEAR, user status is updated to (ACTIVE), A7 (new status reason code). Otherwise; user takes on (ACTIVE), A8 'status_reason_code' for the CONSIDER > CAUTION scenario, T12E 'status_reason_code' for the CONSIDER > TERMINATED user status scenario & T13E 'status_reason_code' for the CONSIDER > SUSPECTED user status scenario (where A8, T12E (works same way as T12) & T13E (works same way as T13) are new status reason codes).

Respectively, we added new values for user status_reason_code:

• A6 : Document expired or about to expire

• A7 - ID renewed

• A8 : ID re-verification failed after document expiration

• B2E: Generate SDK token, document expired (same as B2)

• B0E: Documents re-uploaded after document expiration for identity verification (same as B0)

• T12E: System terminated due to ID verification rejected after document expiration for identity verification (same as T12)

• T13E: System terminated due to ID verification suspected after document expiration for identity verification (same as T13)

To re-initiate IDV flow by generating a new SDK token: change status_reason_code from A8 to B2E.

Below you can find a document with IDV expiration days calculation samples.

10KB

IDV Expiration Days Calculation Samples (1).xlsx

Besides, we have added ability for system to verify issuing country of identity document so that IDV is not passed for users other than allowed country. For this we introduced several new status reason codes:

B9	Document issuing country mismatch
B10	Identity verification consider with caution status and document issuing country mismatch
B9E	Document issuing country mismatch upon IDV re-verification after document expiration
B10E	Identity verification consider with caution status and document issuing country mismatch upon IDV re-verification after document expiration