Transaction Completion

The FaceMatch Completion API is used to complete the FaceMatch provisioning or authentication process. The user sends a base64 encoded image of their face for verification. Since FaceMatch does not involve a credential ID, the server responds with a JWT containing the sessionIdentifier received during initiation. This allows the transaction state to be tracked.

API Description

Method : POST

URL : Follow up url received as part of the response of the Transaction Initiation API

Parameters

Name	Type	Description
client_id*	String	A unique client id that is shared for each partner
image*	base64 string	Selfie Image of the user as Base 64
or
liveliness_transaction_id	String	The liveliness verification transaction id received as part of the Vida Liveliness verification process (e.g. Vida Liveliness SDK)

The partner can either submit the user's selfie image as a Base64 encoded string for KYC verification or provide the liveness_transaction_id from the liveness verification SDK, allowing us to retrieve the verified image directly from the liveness process.

Headers

Name	Type	Description
Authentication*	String	Bearer {Bearer Token Received in Transaction Initaition API}
Content-Type	String	application/x-www-form-urlencoded

200: OK

{
    "entity": {
        "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYbnNBNFVPdlkyU0JLSkdnX1ppTHN1Tk8tZ2dlLVB0RXZzX2twRTBhd3RnIn0.eyJleHAiOjE3MDE1ODI1MTYsIm5iZiI6MTcwMTU4MjIxNiwiaWF0IjoxNzAxNTgyMjE2LCJhdXRoX3RpbWUiOjE3MDE1ODIyMTYsImp0aSI6IjBjZDljNGUyLTEwZGYtNDNmZS04NGMwLWE0MmI0ZDVhOTRjMyIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJhMjI4YTM1NS05NTczLTQzNjgtYWYzMC01NWUwYTA1MjgwMTAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcGkiLCJzZXNzaW9uX3N0YXRlIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIiwic2NvcGUiOiIiLCJzaWQiOiJlOGM4ZjRkNC1lY2QyLTQ3NzQtYTllMy0zYmFjMzA5Zjg2OTIiLCJ0ZW1wbGF0ZV91cmwiOiJodHRwczovL21vY2staW1hZ2VzLmZvb2Jhci52aWRhLmlkL21vY2stbHYtZm0_bHZzPTAuOTQmZm1zPTAuOTAiLCJmYWNlTWF0Y2hNZXNzYWdlIjoiU2VsZmllIHBob3RvIGRvZXMgbm90IG1hdGNoIHdpdGggcmVmZXJlbmNlIHBob3RvIiwiZmFjZU1hdGNoU2NvcmUiOiIwLjkiLCJsaXZlbGluZXNzU2NvcmUiOiIwLjk0Iiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiUzhZVzltVjN4MjQiLCJ0eXBlIjoiRmFjZU1hdGNoIiwibGl2ZWxpbmVzc0NvZGUiOiIxMDQzIiwibGl2ZWxpbmVzc01lc3NhZ2UiOiJTZWxmaWUgcGhvdG8gaXMgYSBsaXZlIHBob3RvIn0.EMJKXNYRYW6X9z5fV479fIGLxlXRiLouzasF6_WqEVTOEvgCeFZ6KakV9C1tWSUq2MLU427FkIw5b4qiNERNABEXmI2yPkZpoAatP6LAErxS0WsKVbQddde6CWQCz9LFHY9I8ySpQhQyrx-gZ_V-nVdFz7rW8oiUIcMIF4zlfpnG98ZsscMIzvjVYDMS05YhX53TywewqpGOqXjqjx53NNGcXXot8HynW2nmhsixpuEZVBQU6BoPDVeW8FglFgSMkxfPxa4wkrak-oDJ4SPEAwteGp0mGyPMilT0HiktQVxyT1EhtjwnQlNKvrOXY1-K8hAOZsAwaHrqwutvfmraEg",
        "accessExpiresIn": 300,
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmMjFhZGYyZS03NWU2LTQ5Y2UtOWYwZi00ZDEwNjE0MDA4NGEifQ.eyJleHAiOjE3MDE1ODQwMTYsImlhdCI6MTcwMTU4MjIxNiwianRpIjoiYjVjZjA2ZGUtZGI5NC00NjMwLTg2YWYtMDM0ODdmYTgyMzUyIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay5hdXRoLXN0YWdlLnZpZGEuaWQvcmVhbG1zL3NwcmluZ2Jvb3QtcXVpY2tzdGFydCIsImF1ZCI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJhMjI4YTM1NS05NTczLTQzNjgtYWYzMC01NWUwYTA1MjgwMTAiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYXBpIiwic2Vzc2lvbl9zdGF0ZSI6ImU4YzhmNGQ0LWVjZDItNDc3NC1hOWUzLTNiYWMzMDlmODY5MiIsInNjb3BlIjoiIiwic2lkIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIn0.ybSUM9mPGdoUX-NgU4dJvFbQ7hZ0w81VYsi5qGFVcS0",
        "refreshExpiresIn": 1800,
        "authType": "FaceMatch"
    },
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlOGM4ZjRkNC1lY2QyLTQ3NzQtYTllMy0zYmFjMzA5Zjg2OTIiLCJleGVjdXRpb24iOm51bGwsInRhYl9pZCI6IlM4WVc5bVYzeDI0IiwibmJmIjoxNzAxNTgyMjE2LCJzZXNzaW9uX2NvZGUiOiJyUlh3cFhXU0hORW1wU0pSUTEzNXVaV3Zmb0tYZmFleFRjU1haZjBCdXhVIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiUzhZVzltVjN4MjQiLCJleHAiOjE3MDE1ODI1MTYsImlhdCI6MTcwMTU4MjIxNiwiYXV0aF9zZXNzaW9uX2lkIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIiwianRpIjoiNTlmYzk2ZjQtYzRkZS00MDM0LTljMGItZTQ0MWQ4OTU5ZDNhIn0.tNXAf3xyIvRCBvnrtJnSO2dUe8LRiP3K_k5RX9nhb_o",
    "authType": "FaceMatch"
}

Curl

curl --location --request POST 'https://{environment-url}/realms/{partner-id}/protocol/api/authenticate' \
--header 'Authorization: Bearer <Bearer Token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'image=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC+4+ipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J/wvc/wBDUDohi1/pvwAAAABJRU5ErkJggg==' \
--data-urlencode 'client_id=api'

Python

import requests

url = "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate"

payload='image=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC%2B4%2BipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J%2Fwvc%2FwBDUDohi1%2FpvwAAAABJRU5ErkJggg%3D%3D&client_id=api'
headers = {
  'Authorization': 'Bearer <Bearer Token>',
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

NodeJS

var axios = require('axios');
var qs = require('qs');
var data = qs.stringify({
  'image': 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC+4+ipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J/wvc/wBDUDohi1/pvwAAAABJRU5ErkJggg==',
  'client_id': 'api' 
});
var config = {
  method: 'post',
  url: 'https://{environment-url}/realms/{partner-id}/protocol/api/authenticate',
  headers: { 
    'Authorization': 'Bearer <Bearer Token>', 
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "image=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC+4+ipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J/wvc/wBDUDohi1/pvwAAAABJRU5ErkJggg==&client_id=api");
Request request = new Request.Builder()
  .url("https://{environment-url}/realms/{partner-id}/protocol/api/authenticate")
  .method("POST", body)
  .addHeader("Authorization", "Bearer <Bearer Token>")
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();
Response response = client.newCall(request).execute();

C#

var client = new RestClient("https://{environment-url}/realms/{partner-id}/protocol/api/authenticate");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <Bearer Token>");
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("image", "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC+4+ipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J/wvc/wBDUDohi1/pvwAAAABJRU5ErkJggg==");
request.AddParameter("client_id", "api");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{environment-url}/realms/{partner-id}/protocol/api/authenticate',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => 'image=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC%2B4%2BipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J%2Fwvc%2FwBDUDohi1%2FpvwAAAABJRU5ErkJggg%3D%3D&client_id=api',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <Bearer Token>',
    'Content-Type: application/x-www-form-urlencoded'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Success Response

The access token issued after a successful face match validation functions is a JWT token, which includes details such as liveliness and face match scores. The signed JWT tokens contain parameters along with corresponding explanations.

The uri and bearerToken in the response will be used in case of the multi authenticator flow and it can be ignored in the case when single authenticator is used.

{
    "entity": {
        "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYbnNBNFVPdlkyU0JLSkdnX1ppTHN1Tk8tZ2dlLVB0RXZzX2twRTBhd3RnIn0.eyJleHAiOjE3MDE1ODI1MTYsIm5iZiI6MTcwMTU4MjIxNiwiaWF0IjoxNzAxNTgyMjE2LCJhdXRoX3RpbWUiOjE3MDE1ODIyMTYsImp0aSI6IjBjZDljNGUyLTEwZGYtNDNmZS04NGMwLWE0MmI0ZDVhOTRjMyIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJhMjI4YTM1NS05NTczLTQzNjgtYWYzMC01NWUwYTA1MjgwMTAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcGkiLCJzZXNzaW9uX3N0YXRlIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIiwic2NvcGUiOiIiLCJzaWQiOiJlOGM4ZjRkNC1lY2QyLTQ3NzQtYTllMy0zYmFjMzA5Zjg2OTIiLCJ0ZW1wbGF0ZV91cmwiOiJodHRwczovL21vY2staW1hZ2VzLmZvb2Jhci52aWRhLmlkL21vY2stbHYtZm0_bHZzPTAuOTQmZm1zPTAuOTAiLCJmYWNlTWF0Y2hNZXNzYWdlIjoiU2VsZmllIHBob3RvIGRvZXMgbm90IG1hdGNoIHdpdGggcmVmZXJlbmNlIHBob3RvIiwiZmFjZU1hdGNoU2NvcmUiOiIwLjkiLCJsaXZlbGluZXNzU2NvcmUiOiIwLjk0Iiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiUzhZVzltVjN4MjQiLCJ0eXBlIjoiRmFjZU1hdGNoIiwibGl2ZWxpbmVzc0NvZGUiOiIxMDQzIiwibGl2ZWxpbmVzc01lc3NhZ2UiOiJTZWxmaWUgcGhvdG8gaXMgYSBsaXZlIHBob3RvIn0.EMJKXNYRYW6X9z5fV479fIGLxlXRiLouzasF6_WqEVTOEvgCeFZ6KakV9C1tWSUq2MLU427FkIw5b4qiNERNABEXmI2yPkZpoAatP6LAErxS0WsKVbQddde6CWQCz9LFHY9I8ySpQhQyrx-gZ_V-nVdFz7rW8oiUIcMIF4zlfpnG98ZsscMIzvjVYDMS05YhX53TywewqpGOqXjqjx53NNGcXXot8HynW2nmhsixpuEZVBQU6BoPDVeW8FglFgSMkxfPxa4wkrak-oDJ4SPEAwteGp0mGyPMilT0HiktQVxyT1EhtjwnQlNKvrOXY1-K8hAOZsAwaHrqwutvfmraEg",
        "accessExpiresIn": 300,
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmMjFhZGYyZS03NWU2LTQ5Y2UtOWYwZi00ZDEwNjE0MDA4NGEifQ.eyJleHAiOjE3MDE1ODQwMTYsImlhdCI6MTcwMTU4MjIxNiwianRpIjoiYjVjZjA2ZGUtZGI5NC00NjMwLTg2YWYtMDM0ODdmYTgyMzUyIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay5hdXRoLXN0YWdlLnZpZGEuaWQvcmVhbG1zL3NwcmluZ2Jvb3QtcXVpY2tzdGFydCIsImF1ZCI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJhMjI4YTM1NS05NTczLTQzNjgtYWYzMC01NWUwYTA1MjgwMTAiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYXBpIiwic2Vzc2lvbl9zdGF0ZSI6ImU4YzhmNGQ0LWVjZDItNDc3NC1hOWUzLTNiYWMzMDlmODY5MiIsInNjb3BlIjoiIiwic2lkIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIn0.ybSUM9mPGdoUX-NgU4dJvFbQ7hZ0w81VYsi5qGFVcS0",
        "refreshExpiresIn": 1800,
        "authType": "FaceMatch"
    },
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlOGM4ZjRkNC1lY2QyLTQ3NzQtYTllMy0zYmFjMzA5Zjg2OTIiLCJleGVjdXRpb24iOm51bGwsInRhYl9pZCI6IlM4WVc5bVYzeDI0IiwibmJmIjoxNzAxNTgyMjE2LCJzZXNzaW9uX2NvZGUiOiJyUlh3cFhXU0hORW1wU0pSUTEzNXVaV3Zmb0tYZmFleFRjU1haZjBCdXhVIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiUzhZVzltVjN4MjQiLCJleHAiOjE3MDE1ODI1MTYsImlhdCI6MTcwMTU4MjIxNiwiYXV0aF9zZXNzaW9uX2lkIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIiwianRpIjoiNTlmYzk2ZjQtYzRkZS00MDM0LTljMGItZTQ0MWQ4OTU5ZDNhIn0.tNXAf3xyIvRCBvnrtJnSO2dUe8LRiP3K_k5RX9nhb_o",
    "authType": "FaceMatch"
}

Response Schema

{
    "entity": {
        "accessToken": "{JWT TOKEN WITH TRANSACTION DETAILS AND INCLUDING SESSION IDENTIFIER AND THE FACEMATCH SCORE}",
        "accessExpiresIn": 300,
        "refreshToken": "{REFRESH TOKEN}",
        "refreshExpiresIn": 1800,
        "authType": "{AUTHENTICATION TYPE}"
    },
    "uri": "{URI OF THE FOLLOW UP REQUEST FOR TRANSACTION COMPLETION}",
    "bearerToken": "{BEARER TOKEN TO BE ADDED IN AUTHORIZATION HEADER OF FOLLOW UP REQUEST}",
    "authType": "{AUTHENTICATION TYPE}",
}

Error Response

{
    "error": "Unprocessable Entity",
    "errorDescription": "message=Unprocessable Entity;livelinessScore=0.0;faceMatchScore=0.0"
}

Response Schema

{
    "error": "{TYPE OF ERROR}",
    "errorDescription": "{REASONING FOR THE ERROR}"
}

Error Codes

For a complete list of error codes and their meanings, refer to the Error Scenarios section.