Responses

sample-response

//Content-Type: application/json
//Signature: NmI4NmIyNzNmZjM0ZmNl
{
    "reference":"17374217",
    "event":"request.pending",
    "verification_url":"https://ra.shuftipro.com/risk-api/process/verification/RPQ8hwPE3cdHKho2wjK7CVQJCQxNx5Rwmb81k3ediXLSWhQM5QibGBWOSgCVjZJd"
}

The Shufti Pro Verification API will send you two types of responses if a request for verification is made. First is the HTTP response sent against your request, and the second is the callback response. Both HTTP and callback responses will be in JSON format with a header. application/json The response header also includes a Key Signature. This key is used for validating the source of the response. Be sure to validate the request by generating signature and matching it with the Signature value from the response header.

Verification Response

Responses will contain the following parameters:

Parameters	Description
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.
event	This is the request event which shows status of request. Event is changed in every response.
email	Which you provided us at the time of request.
country	Which you provided us at the time of request.
verification_result	It is only returned in case of a valid verification. This includes results of each verification. 1 means accepted 0 means declined null means not processed.
verification_data	It is only returned in case of a valid verification. This object will include the all the gathered data in a request process.
info	This object will be returned in case of verification.accepted or verification.declined. It contains the following keys: Agent provides information about the device and browser of the end-user. Geolocation provides information about the geographical location of the end-user.

info

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

Status Response

sample-response

//Content-Type: application/json
//Signature: NmI4NmIyNzNmZjM0ZmNl

{
    "reference" : "17374217",
    "event"     : "verification.accepted",
    "country"   : "GB",
     "services_proofs": [
        {
            "service": "face",
            "proof": "https://st-ns.shuftiapps.com/api/pea/4fb217ae0a129ca950ff03d7fc563d0596550173"
        },
        {
            "service": "document",
            "proof": "https://st-ns.shuftiapps.com/api/pea/99bd9abbd46258ff3652c21057ddf1413fbc196c",
            "additional_proof": "https://st-ns.shuftiapps.com/api/pea/99bd9abbd46258ff3652c21057ddf1413fbc196c"
        },
        {
            "service": "face",
            "proof": "https://st-ns.shuftiapps.com/api/pea/0c2a86b82eb929f23ed9bc054a5fea25e4495328"
        }
    ],
    "verification_data": {
        "risk_assessment": {
            "title": "testing one",
            "fraud_prevention": [
                {
                    "point_name": "No of successful verifications in last month",
                    "point_score": "50"
                },
                {
                    "point_name": "No of failed verifications in last month",
                    "point_score": "50"
                }
            ],
            "questionnaire": [
                {
                    "title": "testing one",
                    "questions": [
                        {
                            "question": "what is your name?",
                            "answer": "Hamza",
                            "type": "radio"
                        },
                        {
                            "question": "enter the percentage you acquired in your last exam",
                            "answer": "10.4",
                            "type": "float"
                        },
                        {
                            "question": "please upload your face img",
                            "answer": "https://ra.shuftipro.com/questionnaire-api/storage/ySeL5tlefCGEkc0vOxalD905MZXulo0XGcOvaN1yUmrnE7xk3V2G1CRRZIAPfSge/questionnaire/filedVXKGo1669969793.png?access_token=97dc9f2de58a2639c1915f7cdcd7d6f67ce466fb",
                            "type": "file"
                        }
                    ]
                }
            ],
           "risk_score": {
                "range_name": "low",
                "total_assessment_score": "12",
                "fraud_prevention_score": null,
                "questionnaire_score": "12"
            },
            "services": [
                {
                    "service_name": "phone",
                    "status": "verification.declined"
                },
                {
                    "service_name": "face",
                    "status": "verification.accepted"
                },
                {
                    "service_name": "background_checks",
                    "status": "verification.accepted"
                }
            ]
        }
    },
    "verification_result": {
        "risk_assessment": 1
    },
    "info": {
        "agent": {
            "is_desktop": true,
            "is_phone": false,
            "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36",
            "device_name": "Macintosh",
            "browser_name": "",
            "platform_name": "OS X - 10_14_0"
        },
        "geolocation": {
            "host": "212.103.50.243",
            "ip": "212.103.50.243",
            "rdns": "212.103.50.243",
            "asn": "9009",
            "isp": "M247 Ltd",
            "country_name": "Germany",
            "country_code": "DE",
            "region_name": "Hesse",
            "region_code": "HE",
            "city": "Frankfurt am Main",
            "postal_code": "60326",
            "continent_name": "Europe",
            "continent_code": "EU",
            "latitude": "50.1049",
            "longitude": "8.6295",
            "metro_code": "",
            "timezone": "Europe/Berlin"
        }
    }
}

The Shufti Pro Verification API will send a JSON response if a status request is made. Make sure to validate the request by generating signature and matching it with the Signature value from the response header.

Parameters	Description
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.
event	This is the request event which shows status of request. Event is changed in every response.
country	This contains country code sent by the merchant at the time of request. Country code in the format of ISO 3166-1 alpha-2. Please consult (Supported Countries) for country codes. Type: string Example: DE null if not provided by merchant.
services_proofs	This contains all the proofs that were used to verify data. The Proof URLs returned are temporary and valid for 15 minutes only. Note: verification_video It contains the video URL and will be returned only for the video recorded on-site.
verification_data	This contains all the data used for verification. This will only be returned in case of verification.accepted or verification.declined.
verification_result	This is the complete result of the verification. 1 stands for verified, 0 for not verified and null for no verification performed. This will only be returned in case of verification.accepted or verification.declined.
info	This object will be returned in case of verification.accepted or verification.declined. It contains the following keys: Agent provides information about the device and browser of the end-user. Geolocation provides information about the geographical location of the end-user.

info

request.invalid response with HTTP status code 400 means the request is invalid.

Response Signature

Every HTTP and Callback response will be in application/JSON with a key Signature in the header. It can be used to validate the source of the request. Make a signature using the following procedure:

1. Concatenate Secret Key at the end of the raw response string. (i.e. response + secret_key).
2. Take SHA256 of concatenated string.
3. Match the SHA256 string with Signature value from the header of the response.

In short, make signature as mentioned format and match it with the signature provided in the header in Signature key.

hash('sha256', response . your_secret_key)

The clients who are registered with shuftipro after 15th March, 2023. They need to make the signature using the following procedure.

1. Take SHA256 of Secret Key string.
2. Concatenate hashed Secret Key at the end of the raw response string. (i.e. response + hash('sha256', secret_key)).
3. Take SHA256 of concatenated string.
4. Match the SHA256 string with Signature value from the header of the response.

hash('sha256', response . hash('sha256', secret_key))

caution

The clients registered with shuftipro before 15th March 2023 or have not updated the secret key from the back office. They don't need to take SHA256 of the Secret key.

Here is the sample code to validate the signature:

Javascript

const axios = require('axios');
const base64 = require('base-64');
const crypto = require('crypto');

// Shufti Pro API base URL
const url = 'https://api.shuftipro.com/status';

// Your Shufti Pro account Client ID
const client_id = 'YOUR_CLIENT_ID';

// Your Shufti Pro account Secret Key
const secret_key = 'YOUR_SECRET_KEY';

const request = {
    // your request reference
    reference: '1234-0987-1234',
};

// calling Shufti Pro request API using axios
const auth = `${client_id}:${secret_key}`;
const b64Val = Buffer.from(auth).toString('base64');
axios.post(url, request, {
    headers: {
        Authorization: `Basic ${b64Val}`,
        'Content-Type': 'application/json',
    },
    responseType: 'text'
})
    .then((response) => {
        // get Shufti Pro Signature
        const sp_signature = response.headers.signature;

        // convert secret key into sha256
        const hashed_secret_key = crypto.createHash('sha256').update(secret_key).digest('hex');

        // calculating signature for verification
        const calculated_signature = crypto.createHash('sha256').update(response.data + hashed_secret_key).digest('hex');

        if (sp_signature === calculated_signature) {
            console.log(response.data);
        } else {
            console.log(`Invalid signature: ${response.data}`);
        }
    })
    .catch((error) => {
        console.log(error);
    });

PHP

<?php

// Shufti Pro API base URL
$url = 'https://api.shuftipro.com/status';

// Your Shufti Pro account Client ID
$client_id = 'YOUR_CLIENT_ID';

// Your Shufti Pro account Secret Key
$secret_key = 'YOUR_SECRET_KEY';

$request = array(
    // your request reference
    "reference" => '1234-0987-1234',
);

// calling Shufti Pro request API using cURL
$auth = $client_id . ':' . $secret_key;
$headers = ['Content-Type: application/json'];

$response = send_curl($url, json_encode($request), $headers, $auth);

//Get Shufti Pro API Response
$response_data    = $response['body'];

//Get Shufti Pro Signature
$exploded = explode("\n", $response['headers']);

// Get Signature Key from Hearders
$sp_signature = null;
foreach ($exploded as $key => $value) {
  if (strpos($value, 'signature: ') !== false || strpos($value, 'Signature: ') !== false) {
    $sp_signature=trim(explode(':', $exploded[$key])[1]);
    break;
  }
}

// convert secret key into sha256
$hashed_secret_key = hash('sha256', $secret_key);

// calculating signature for verification
$calculated_signature = hash('sha256', $response_data . $hashed_secret_key);

if ($sp_signature === $calculated_signature) {
    print_r($response_data);
} else {
    echo 'Invalid signature: ' . $response_data;
}


function send_curl($url, $post_data, $headers, $auth){ // remove $auth in case of Access Token
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_USERPWD, $auth); // remove this in case of Access Token
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_HEADER, 1);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); // remove this in case of Access Token
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    $html_response = curl_exec($ch);
    $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    $headers = substr($html_response, 0, $header_size);
    $body = substr($html_response, $header_size);
    curl_close($ch);
    return ['headers' => $headers,'body' => $body];     
}

Python

# import required libraries
import base64
import requests
import json
import hashlib
import urllib.request
from random import randint

# Shufti Pro api base url
url = 'https://api.shuftipro.com/status'

# Your Shufti Pro account Client ID
client_id = 'YOUR_CLIENT_ID'

# Your Shufti Pro account Secret Key
secret_key = 'YOUR_SECRET_KEY'

request = {
    # your request reference
    "reference": '1234-0987-1234',
}

# calling Shufti Pro request API using python request
auth = '{}:{}'.format(client_id, secret_key)
b64Val = base64.b64encode(auth.encode()).decode()
response = requests.post(url,
                         headers={"Authorization": "Basic %s" %
                                  b64Val, "Content-Type": "application/json"},
                         data=json.dumps(request))


# get Shufti Pro Signature
sp_signature = response.headers.get('Signature')

# convert secret key into sha256
hashed_secret_key = hashlib.sha256(secret_key.encode()).hexdigest()

# calculating signature for verification
calculated_signature = hashlib.sha256('{}{}'.format(
    response.content.decode(), hashed_secret_key).encode()).hexdigest()

# Convert json string to json object
json_response = json.loads((response.content))

if sp_signature == calculated_signature:
    print(json_response)
else:
    print('Invalid signature: {}'.format(response.content))

Ruby

require 'uri'
require 'net/http'
require 'base64'
require 'json'
require 'digest'

url = URI("https://api.shuftipro.com/status")

# Your Shufti Pro account Client ID
CLIENT_ID  = "YOUR-CLIENT-ID"

# Your Shufti Pro account Secret Key
SECRET_KEY = "YOUR-SECRET-KEY"

post_data = { 
     # your request reference
     reference: "1234-0987-1234" 
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)

header_auth = Base64.strict_encode64("#{CLIENT_ID}:#{SECRET_KEY}")

request["Content-Type"]  = "application/json"
request["Authorization"] = "Basic #{header_auth}"  
request.body             = post_data.to_json

response = http.request(request)
response_headers =  response.instance_variable_get("@header")
response_data    = JSON.parse(response.read_body)

# get Shufti Pro Signature
sp_signature     = !(response_headers['signature'].nil?) ? response_headers['signature'].join(',') : ""

# convert secret key into sha256
hashed_secret_key = Digest::SHA256.hexdigest SECRET_KEY

# calculated signature
calculated_signature = Digest::SHA256.hexdigest response.read_body + hashed_secret_key

if sp_signature == calculated_signature
   puts response_data
else
   puts "Invalid signature"
end

Java

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

import javax.net.ssl.HttpsURLConnection;


public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.shuftipro.com/status";
        String CLIENT_ID = "CLIENT_ID";
        String SECRET_KEY = "SECRET_KEY";
        URL obj = new URL(url);
        HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();

        // Add request header
        con.setRequestMethod("POST");
        con.setRequestProperty("Content-Type", "application/json");
        String basicAuth = "Basic " + Base64.getEncoder().encodeToString((CLIENT_ID + ":" + SECRET_KEY).getBytes(StandardCharsets.UTF_8));    
        con.setRequestProperty("Authorization", basicAuth);

        String payload = "{ \n    \"reference\" : \"1234-0987-1234\"\n}";

        // Send post request
        con.setDoOutput(true);
        DataOutputStream wr = new DataOutputStream(con.getOutputStream());
        wr.writeBytes(payload);
        wr.flush();
        wr.close();

        int responseCode = con.getResponseCode();
        System.out.println("\nSending 'POST' request to URL : " + url);
        System.out.println("Payload : " + payload);

        if (responseCode == HttpsURLConnection.HTTP_OK) {
            // Get Shufti Pro Signature
            String spSignature = con.getHeaderField("signature");

            // Convert secret key into sha256
            String hashedSecretKey = calculateSHA256Hash(SECRET_KEY);

            BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
            System.out.println(in.toString());
            String inputLine;
            StringBuffer response = new StringBuffer();

            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();

            // Calculating signature
            String calculatedSignature = calculateSHA256Hash(response + hashedSecretKey);

            if (spSignature != null && spSignature.equals(calculatedSignature)) {
                // Print the response
                System.out.println(response);
            } else {
                System.out.println("Invalid signature");
            }
        }else{
            System.out.println("Response Code : " + responseCode);
        }
                
    }
    public static String calculateSHA256Hash(String input) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] encodedHash = digest.digest(input.getBytes(StandardCharsets.UTF_8));

            StringBuilder hexString = new StringBuilder();
            for (byte b : encodedHash) {
                String hex = String.format("%02x", b);
                hexString.append(hex);
            }

            return hexString.toString();
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
            return null;
        }
    }
}

Go

package main

import (
    "crypto/sha256"
    "encoding/base64"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "strings"
)

type Payload struct {
    Reference string `json:"reference"`
}

func main() {
    // Create the payload
    payload := Payload{
        Reference: "",
    }

    // Marshal the payload to JSON
    jsonPayload, err := json.Marshal(payload)
    if err != nil {
        fmt.Println("Error marshaling payload:", err)
        return
    }

    // Set up Basic Auth header
    username := ""
    password := ""
    authHeader := "Basic " + base64.StdEncoding.EncodeToString([]byte(username+":"+password))

    // Create the HTTP client and request
    client := &http.Client{}
    req, err := http.NewRequest("POST", "https://api.shuftipro.com/status", strings.NewReader(string(jsonPayload)))
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }

    // Set headers
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", authHeader)

    // Send the request and get the response
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error making request:", err)
        return
    }
    defer resp.Body.Close()

    // Read the response body
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response body:", err)
        return
    }

    // Convert the response body to string
    responseData := string(body)

    // Calculate the response hash
    responseHash := calculateResponseHash(responseData, password)

    // Get the response signature from the header
    responseSignature := resp.Header.Get("Signature")

    // Check if the response signature matches the calculated hash
    signatureMatch := responseSignature == hex.EncodeToString(responseHash[:])

    fmt.Println("Response:", responseData)
    fmt.Println("Signature Match:", signatureMatch)
}

// calculateResponseHash calculates the SHA256 hash of the response data concatenated with the password hash
func calculateResponseHash(responseData string, password string) [32]byte {
    passwordHash := sha256.Sum256([]byte(password))
    return sha256.Sum256([]byte(responseData + hex.EncodeToString(passwordHash[:])))
}