A detailed guide of integration process of Shufti Pro v1.2 with pre-existing modules & web applications for verification processing. Warning: This version is deprecated and support for this version will end on November 31st, 2018
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Sample codes Update get_request_status.py Jun 15, 2018
assets Updated document banner image Sep 27, 2018
README.md Updated document banner image Sep 27, 2018

README.md

Note: This version i.e. v1.2 is deprecated and support for this version will end on November 31st, 2018

Table of contents

Introduction

Note: This version i.e. v1.2 is deprecated and support for this version will end on November 31st, 2018

Shufti Pro provides two modes of verification:

  1. Real-Time Verification
  2. Offline Verification

In Real time verification, your customer has to show their face and the required document in front of the camera. On the other hand in Offline Verification, you have an opportunity to provide your customer’s identity document to us via this API and we’ll send you the verification results back.

Real-Time Verification

A typical real-time verification workflow looks like this:

  1. You send us your customer’s data to verify at one of our end points. We validate your request and send you a redirect URL so you can redirect your customer to our verification page or you can embed this in an iFrame.
  2. Your customer sees an instruction page. Upon clicking ‘Next’, the verification process starts.
  3. Your customer shows their face followed by the required document to the camera and the verification process begins in the background.
  4. Upon verification, your customer will be redirected to the given URL. Along with this URL, we’ll also send you the verification response via a callback. A callback is made before we redirect your customer to your redirect url.
  5. When you receive a verification response from us, you will also receive a field Signature. You need to verify this field before proceeding further. An example is given here.

Offline Verification

In this mode, you only make a single call to our API with your customer’s Identity document and we send you the verification result back in response to this API call. You can provide us with this identity document either as an image or you can ask your customer to provide you with a recorded video, which you can forward to us. Therefore, for the Offline verification you can choose following methods:

  1. Still Image Verification (Your customer’s face and document image as a Base64 String)*
  2. Video Verification (A recorded video of your customer showing their face and identity document (details showing clearly in the camera))**

*  Base64 string size shouldn’t be greater than 4MB for each image
** This video size shouldn’t be greater than 8MB

Identity Verification

The Identity verification supports the following kinds of verification:

  • General Purpose verification
  • Driving license verification
  • Passport verification
  • ID Card verification

General Purpose

Your customer is provided with a list of ID documents to choose from such as passport, driving license or ID card. After the user chooses one particular document, they are requested to display the required document in front of the camera. The document's validity is ensured after cross checking the information provided in the request with that present on the document.

Driving License

Your customer needs to display their Driving License. Shufti Pro verifies the validity of the driving license by cross checking the information (customer’s name and date of birth) provided in the request with that on the driving license.

Passport

Your customer needs to display their passport. The validity of the passport is verified by cross checking the provided information with that on the passport. For example, customer’s name and date of birth are cross checked to judged whether the passport shown is forged or authentic.

ID Card

Your customer needs to display their Identity Card. It could be government, school and/or university issued ID card. Shufti Pro verifies the validity of such ID card by cross checking the information (customer's name and date of birth) provided in the request with that on the ID card.

How to make a verification request

You can make a request at the following endpoint with all the parameters defined below.
Endpoint: POST https://api.shuftipro.com/
Format: x-www-form-urlencoded

Parameter Online Offline Description
client_id Required Required Client’s ID provided by Shufti Pro to you.
reference Required Required Your Unique reference ID, which we will send you back with each response, so you can verify the request. Only alphanumeric values are allowed.
email Optional Optional This parameter is used to notify your customer in case a verification result is delayed.
phone_number Required Required Customer’s phone number with country code. Example: +440000000000
lang Optional Optional Send ISO639-1 language code of your preferred language to display the verification screens accordingly. Please find a list of supported languages here.
country Required Required Send the 2 characters long ISO 3166-1 alpha-2 country code of where your customer is from.
callback_url Required Optional During a verification request, we make several server to server calls to keep you updated about the verification state. These states include: i) Customer lands on our verification page; ii) Verification process completes. This way you can update the request status at your end even if the customer is lost midway through the process.
redirect_url Required Required Once the verification process completes, we redirect your customer to your given URL. In this redirect request, you’ll also get all the verification response values using HTTP POST method, so you can make your decision. Please verify the response’s signature value with your own calculated signature value.
verification_services Required Required The JSON encoded array of all the data which you want us to verify using our different services. The key in this JSON encoded array will be the name of service which you want use in this verification request. e.g dob, first_name etc. All the available keys and the corresponding values are given below:
document_type Which type of document would you like your customer to verify with?
Possible values:
  • passport
  • driving_license
  • id_card
  • credit_card
In real time verification if an empty value is provided then the end user will have an option to choose any of the verification method from the given list.
document_id_no The valid ID number of your customer's identity document which you want us to verify. e.g. Passport number, ID card number and Driving License number.
document_expiry_date The expiry date of the customer's identity document. Example: 2025-01-31
address Your customer's home or billing address mentioned on the identity document, utility bill or on a bank statement.
first_name Customer’s first name on the identity document.
middle_name Customer’s middle name on the identity document.
last_name Customer’s last name on the identity document.
dob Customer’s date of birth (YYYY-MM-DD). Example: 1980-01-31
card_first_6_digits First 6 digits of the customer’s credit/debit card number if document type is debit/credit.
card_last_4_digits Last 4 digits of the customer’s credit/debit card number if document type is debit/credit.
background_checks Send 1 if you want us to perform background checks on your customer, 0 otherwise.
verification_data Optional Required If you want to perform an offline verification without redirecting your customer to us, you can send us the identity docs using this parameter. The JSON encoded array of all the data required in the offline verification. The following keys are allowed to send in the request. In the below table keys are listed in left side column and right side column has detail of each key.
face_image The base64 string of your customer's selfie. (Max size 4MB allowed)
document_front_image The base64 string of the document mentioned in “document_type” parameter (passport, driving_license, id_card). (Max size 4MB allowed)
document_back_image The base64 string of the customer’s document back side image (if any). (Max size 4MB allowed)
document_address_image The base64 string of the customer's utility bill or any document which must contain the residence address. If you want to verify the address then please send this image too. (Max size 4MB allowed)
video The base64 of the video is only required when the user wants to verify themselves through offline verification (by sending video). (Max size 8MB allowed)
signature Required Required SHA256 hash of all the request parameters in sorted order. The details are in the signature calculation section.

Get Request status

Once a verification request is completed, you may request to this end point to get the verification status.

Endpoint: POST https://api.shuftipro.com/status
Format: x-www-form-urlencoded

Parameter Required Description
client_id Yes Client’s ID provided by Shufti Pro to you. (ID must be in alphanumeric format)
reference Yes Your unique request reference that you have sent at the time of request. (a valid request reference that is associated with any request at the time it is made)
signature Yes Provide SHA256 hash of CONCATENATE(client_id, reference, secret_key)

Find sample codes here.

Responses

The Shufti Pro API will send you two types of responses. First is the HTTP response sent against your request, and the second is the callback response, respectively. Both HTTP and callback responses will be in the JSON format and they will contain the following parameters:

Parameter Description
status_code One of the status codes given here.
message The description of status code. If the status code is SP2 then the message will be a redirect URL.
reference Your unique request reference, which you provided us at the time of request, so that you can identify the response in relation to the request made.
signature The SHA256 hash of CONCATENATE(status_code, message, reference, secret_key).

Note: Callback response will be sent on the callback_url provided in the request callback_url parameter.

Status Codes

Status codes represent the status of the verification process (Success / Failure). The Shufti Pro Verification API uses the following status codes sent throughout when making any kind of verification request.

Status Code Description HTTP Callback
SP0 Not Verified Yes Yes
SP1 Verified Yes Yes
SP2 Success! -- Contains the redirect url in message parameter. Yes Yes
SP11 Length Validation -- [parameter_name] maximum and minimum length limit is [min & max] characters. Yes Yes
SP14 Duplicate reference -- If a duplicate reference is provided. Yes Yes
SP15 Invalid client id -- Client id is invalid or not found. Yes Yes
SP16 Missing required parameter -- ["parameter_name"] is required but either missing or empty. Yes Yes
SP17 Invalid format -- ["parameter_name"] is not in the correct format. Yes Yes
SP18 Invalid signature -- Invalid request signature. Yes Yes
SP19 Invalid country code -- Invalid country code or country is not supported. Yes Yes
SP20 Invalid Phone No -- Invalid phone number is provided. Yes Yes
SP21 Invalid Method Name -- Given verification method is not supported. Yes Yes
SP22 Invalid checksum value. Yes Yes
SP23 Invalid DOB -- Date of birth is not valid. Yes Yes
SP24 Blocked Client -- Your account is not active. Yes Yes
SP25 Request Timeout -- Sends in callback when request timeouts. Yes Yes
SP26 User has been landed on verification page. Yes Yes
SP27 Request is already processed. Yes Yes
SP29 Invalid size. The size limit for ["parameter_name"] is ["size in MBs"]. Yes Yes
SP30 A particular verification service is not enabled. Please contact to the support. Yes Yes
SP31 User closed his/her web browser. Yes Yes
SP32 Invalid request reference. Request not found. Yes Yes
SP33 Verification review pending. Yes Yes
SP34 Language (provided in the request) is not supported. Yes Yes
SP35 [parameter_name] not allowed with [method_name] verification method. Yes Yes
SP150 User clicked on verification cancel button No Yes
SP151 User disagreed from terms & condition No Yes
SP153 Your account doesn't have enough credits to perform this verification Yes Yes

Signature Calculation

The request and response signature can be calculated as following:

Request Signature

  1. Sort all the request parameters (keys) in (ascending alphabetical order) and concatenate their values.
  2. Append the secret key at the end.
  3. Calculate the SHA256 hash of string (made in above 2 steps).

Response Signature

  1. Decode the JSON sent in the response body.
  2. Concatenate values of status_code, message, reference and secret key.
  3. Calculate the SHA256 hash of the string (made in above 2 steps).

Sample Codes

Below are the sample codes in php, python & c# for the following verification methods:

  1. Online Identity verification
  2. Online Card Present verification
  3. Offline Identity verification
  4. Offline Card Present verification

Supported Languages

Language Code
Arabic ar
English en
Estonian et
Russian ru
Arabic ar
English en
Estonian et
Russian ru
Italian it
Turkish tr
Swedish sv
Spanish es
Romanian ro
Portuguese pt
Korean ko
Polish pl
Norwegian no
Japanese ja
Icelandic is
French fr
German de
Dutch nl
Danish da
Indonesian in
Chinese zh

Test IDs

Shufti Pro provides the users with a number of test documents. Customers may use these to test the demo, instead of presenting their actual information.


Revision history

Date Version Description
March 14, 2018 1.0.1 Added new endpoint for get request status. https://api.shuftipro.com/status
March 26, 2018 1.0.2 Added lang parameter & supported languages list.
March 29, 2018 1.0.3 Added C# sample codes.
April 10, 2018 1.0.4 Added new supported languages.
July 10, 2018 1.0.5 Added new status codes.

2016-18 © Shufti Pro Ltd.