Responses
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.
HTTP Status Codes
Shufti Pro Verification API uses conventional HTTP response codes to indicate the success or failure of an API request. Every response is generated in JSON with a specific HTTP code.
Following is a list of HTTP codes that are generated in responses by Shufti Pro Verification API.
HTTP code | HTTP message | Message |
---|---|---|
200 | OK | success |
400 | Bad Request | Bad Request: one or more parameter is invalid or missing |
401 | Unauthorized | Unauthorized: invalid signature key provided in the request |
402 | Request Failed | Invalid request data: missing required parameters |
403 | Forbidden | Forbidden: service not allowed |
404 | Not Found | Resource not found |
409 | Conflict | Conflicting data: already exists |
429 | Too Many Requests | Too Many Attempts. |
500 | Server Error | Internal Server Error |
504 | Gateway Timeout | Server error |
524 | Timeout from Cloudflare | Unofficial Server Error |
Response Events
Events are sent in responses that show the status of the request. These events are sent in both HTTP and callback responses.
- verification.accepted
- verification.declined
- verification.cancelled
- request.pending
- request.invalid
- request.timeout
- request.unauthorized
- verification.status.changed
- request.deleted
- request.received
- review.pending
{
"reference": "sp-bc-prod-3ywNyrCj",
"event": "verification.accepted",
"email": null,
"country": "",
"verification_data": {
"ekyc": {
"personal_details": {
"first_name": "",
"last_name": " ",
"dob": "20XX-01-01",
"gender" : "",
},
"address_details": {
"postal_code": "",
"country_name": "Spain"
},
"contact_details": {
"phone": "",
"email": ""
}
}
},
"verification_result": {
"ekyc": 1
},
"info": {
"agent": {
"is_desktop": true,
"is_phone": false,
"device_name": "Macintosh",
"browser_name": "Chrome 111.0.0.0",
"platform_name": "Mac OS 10.15.7"
},
"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"
}
}
}
{
"reference": "sp-bc-prod-lfFfWUgU",
"event": "verification.declined",
"email": null,
"country": "",
"verification_data": {
"ekyc": []
},
"verification_result": {
"ekyc": 0
},
"info": {
"agent": {
"is_desktop": true,
"is_phone": false,
"device_name": "Macintosh",
"browser_name": "Chrome 111.0.0.0",
"platform_name": "Mac OS 10.15.7"
},
"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"
}
},
"declined_reason": "The BankID app could not be found on your computer or mobile device OR Failed to scan the QR code.",
"declined_codes": ["SPDR245"],
"services_declined_codes": {
"ekyc": ["SPDR245"]
}
}
{
"reference": "17374217",
"event": "verification.cancelled",
"country": "GB",
"proofs": {}
}
{
"reference": "17374217",
"event": "request.pending",
"verification_url": "https://eidv.shuftipro.com/process/eidv/bGnb5HuWkyD0ZPMGCGsp30HaYC7vhrBDoNB11NYWcV47yt5K8ugdA9yxQHU0vMxZ",
"email": "[email protected]",
"country": "GB"
}
{
"reference": "8233266298",
"event": "request.invalid",
"error": {
"service": "",
"key": "ekyc",
"message": "The ekyc field must be an array."
},
"email": null,
"country": null
}
{
"reference": "17374217",
"event": "request.timeout",
"country": "GB",
"proofs": {}
}
{
"reference": "",
"event": "request.unauthorized",
"error": {
"service": "",
"key": "",
"message": "Authorization keys are missing/invalid."
},
"email": null,
"country": null"
}
{
"reference": "17374217",
"event": "verification.status.changed"
}
{
"reference": "17374217",
"event": "request.deleted"
}
{
"reference": "17374217",
"event": "request.received",
"email": "[email protected]",
"country": "UK"
}
{
"reference": "sp-bc-prod-wVuvc6Kf",
"event": "review.pending",
"email": null,
"country": "",
"verification_data": {},
"verification_result": {
"ekyc": 1
},
"info": {
"agent": {
"is_desktop": true,
"is_phone": false,
"device_name": "Macintosh",
"browser_name": "Chrome 111.0.0.0",
"platform_name": "Mac OS 10.15.7"
},
"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"
}
}
}
Event | description | HTTP Response | Callback Response |
---|---|---|---|
request.pending | Request parameters are valid and verification url is generated in case of on-site verification. | Yes | Yes |
request.invalid | Request parameters provided in request are invalid. | Yes | No |
verification.cancelled | Request is cancelled by the user. This event occurs when end-user disagrees to terms and conditions before starting verifications. | Yes | Yes |
request.timeout | Request has timed out after a specific period of time. The onsite request will Time Out after 60 minutes. | No | Yes |
request.unauthorized | Request is unauthorized. The information provided in authorization header is invalid. | Yes | No |
verification.accepted | Request was valid and accepted after verification. | Yes | Yes |
verification.declined | Request was valid and declined after verification. | Yes | Yes |
verification.status.changed | Request status has been updated. | No | Yes |
request.deleted | Request has been deleted. | Yes | Yes |
request.received | Request has been received. | Yes | Yes |
review.pending | Documents are collected and request is pending for client to review and Accept/Decline. | Yes | Yes |
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. Please consult Events for more information. |
country | This is the country of request. |
error | Whenever there is an error in your request, this parameter will have the details of that error. |
token | This is the unique request token of the request. |
verification_result | This object will be returned in case of verification.accepted or verification.declined. This includes the results of each verification. 1 means accepted 0 means declined null means not processed Check verification.accepted and verification.declined responses in Events section for a sample response. |
verification_data | This object will be returned in case of verification.accepted or verification.declined. This object will include all the gathered data in a request process. Check verification.accepted and verification.declined responses in Events section for a sample response. |
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. |
declined_reason | This parameter will have the reason due to which a verification has been declined, and is only returned in this case in the callback URL. |
declined_codes | This array contains status codes of all declined verification reasons. It will return only for verification.declined. |
services_declined_codes | This object contains status codes of declined reasons for each service separately. Each service object will contain an array of status codes for declined reasons specific to that service. It will return only for verification. declined. |
Callback response will be sent on the callback_url provided in the request callback_url parameter.
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:
- Concatenate Secret Key at the end of the raw response string. (i.e. response + secret_key).
- Take SHA256 of concatenated string.
- 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.
- Take SHA256 of Secret Key string.
- Concatenate hashed Secret Key at the end of the raw response string. (i.e. response + hash('sha256', secret_key)).
- Take SHA256 of concatenated string.
- Match the SHA256 string with Signature value from the header of the response.
hash('sha256', response . hash('sha256', secret_key))
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
- PHP
- Python
- Ruby
- Java
- Go
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
// 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];
}
# 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))
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
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;
}
}
}
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[:])))
}