Transaction Completion

Transaction - Authentication Completion

The Face Match ID Authentication API is used for completing the user authentication process for a transaction. After initiating a request for authentication, the server responds with a session ID, bearer token, and a challenge. To finalize the transaction, the user responds to this challenge by submitting an image (selfie). The API then validates this image against the one stored during the provisioning phase.

API Description

Method : POST

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

Headers

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

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.

200: OK

{
    "entity": {
        "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYbnNBNFVPdlkyU0JLSkdnX1ppTHN1Tk8tZ2dlLVB0RXZzX2twRTBhd3RnIn0.eyJleHAiOjE3MDM1ODE5NzUsIm5iZiI6MTcwMzU4MTY3NSwiaWF0IjoxNzAzNTgxNjc1LCJhdXRoX3RpbWUiOjE3MDM1ODE2NzUsImp0aSI6IjQwODczODM2LWRkNDAtNDI0NS1iNzYwLTQ4ZjgxYTRmMzg4ZiIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJlY2FiYzIzYS1iYThlLTQ3ZGUtYjdhNy1iZDlkZGYzZTAxNzEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcGkiLCJzZXNzaW9uX3N0YXRlIjoiZWZjNmM4OGItYTIyZC00ZWFmLTgyY2MtOTg0MGViYzNlMDA0Iiwic2NvcGUiOiIiLCJzaWQiOiJlZmM2Yzg4Yi1hMjJkLTRlYWYtODJjYy05ODQwZWJjM2UwMDQiLCJreWNfZXZlbnRfaWQiOiI4MjljODM3Zi01YmFjLTQ4YWYtYTViZC0zNDk5NTFjYzM2NDgiLCJsaXZlbGluZXNzVHJhbnNjYXRpb25JZCI6IjIwMjAwNjk0LTNiYzgtNDg4OS05MTIzLWM2OTI2ZDA5MGRhYSIsImZhY2VNYXRjaE1lc3NhZ2UiOiJTZWxmaWUgcGhvdG8gbWF0Y2hlcyB3aXRoIHJlZmVyZW5jZSBwaG90byIsImZhY2VNYXRjaFNjb3JlIjoiMS4wIiwibGl2ZWxpbmVzc1Njb3JlIjoiMC4wMDYzNzYiLCJtb2JpbGUiOiI4MjljODM3Zi01YmFjLTQ4YWYtYTViZC0zNDk5NTFjYzM2NDgiLCJzZXNzaW9uX2lkZW50aWZpZXIiOiJJYmdwYkdpLXdpYyIsInR5cGUiOiJGYWNlSUQiLCJsaXZlbGluZXNzQ29kZSI6IjEwNDMiLCJsaXZlbGluZXNzTWVzc2FnZSI6IlNlbGZpZSBwaG90byBpcyBhIGxpdmUgcGhvdG8iLCJmYWNlTWF0Y2hUcmFuc2NhdGlvbklkIjoiZDE0YjFlNzEtNDU3Yy00OTdjLTgwMTEtNzQwMGZiZjE1YjVjIiwiY3JlZGVudGlhbF9pZCI6ImJiZGNiMjg0LWE2NGMtNGMwYy04ODljLWMxMDBlMDk1NmZmZiJ9.UWzIn_E4u_OUcv9q4vLfeYCfkzdv6T11es-7zEX1oZxeFPbMZUR8Clj_5pEKLZTJmD01Dcdgm2FBU-4WvX9p3QmMI6pqkvQvDZilzFGkaKFYmZBI8VT9GmtD96OfRWQAtwUEiVbf_6pFHujHHMiydlndGoL9tm87nuMd9HwKD42Msejq4IdPNDUbnVhIMrqMaMkTyaE2jYGO1OzgZWm-InKXXV1_IuaXaZaIh2A2AfL2FDbyxTzRHFfd4BI5buSR03HUz_yw2hAwwHvXyojjU2MLYc76pQYfN38nUEhJLb6pGnbD01NRLIaiGQKQtYqKd8SmKjC2tOnXpsfj1WIpfA",
        "accessExpiresIn": 300,
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmMjFhZGYyZS03NWU2LTQ5Y2UtOWYwZi00ZDEwNjE0MDA4NGEifQ.eyJleHAiOjE3MDM1ODM0NzUsImlhdCI6MTcwMzU4MTY3NSwianRpIjoiMDI5OTExNmMtMGY2OS00NjEyLTgyZTYtNzdiMzIwM2I3NDNlIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay5hdXRoLXN0YWdlLnZpZGEuaWQvcmVhbG1zL3NwcmluZ2Jvb3QtcXVpY2tzdGFydCIsImF1ZCI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJlY2FiYzIzYS1iYThlLTQ3ZGUtYjdhNy1iZDlkZGYzZTAxNzEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYXBpIiwic2Vzc2lvbl9zdGF0ZSI6ImVmYzZjODhiLWEyMmQtNGVhZi04MmNjLTk4NDBlYmMzZTAwNCIsInNjb3BlIjoiIiwic2lkIjoiZWZjNmM4OGItYTIyZC00ZWFmLTgyY2MtOTg0MGViYzNlMDA0In0.XGkS03_dTcVCA2hwYfN-6BI1AmdoJEYIORE_i4-wD2w",
        "refreshExpiresIn": 1800,
        "authType": "FaceID"
    },
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlZmM2Yzg4Yi1hMjJkLTRlYWYtODJjYy05ODQwZWJjM2UwMDQiLCJleGVjdXRpb24iOm51bGwsInRhYl9pZCI6IkliZ3BiR2ktd2ljIiwibmJmIjoxNzAzNTgxNjc1LCJzZXNzaW9uX2NvZGUiOiJSRFpLVXFId1oxeHZseTFnYm8ySkhIblVMUkk4VEV5VjM3SVFPM0ZsTEdzIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiSWJncGJHaS13aWMiLCJleHAiOjE3MDM1ODE5NzUsImlhdCI6MTcwMzU4MTY3NSwiYXV0aF9zZXNzaW9uX2lkIjoiZWZjNmM4OGItYTIyZC00ZWFmLTgyY2MtOTg0MGViYzNlMDA0IiwianRpIjoiYmZkYmI4ZGUtZjY5MC00OWZlLWEwYjAtNzYxNjMyOGU2NDI2In0.t7hWqOupNrB_a7EMhLfthxCRfK-hDf35x09FPJFWnj0",
    "authType": "FaceID"
}

Curl

curl --location --request POST '{{FOLLOW UP URI RECEIVED AS PART OF THE RESPONSE OF THE TRANSACTION FOLLOWUP REQUEST}}' \
--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 = "{{FOLLOW UP URI RECEIVED AS PART OF THE RESPONSE OF THE TRANSACTION FOLLOWUP REQUEST}}"

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: '{{FOLLOW UP URI RECEIVED AS PART OF THE RESPONSE OF THE TRANSACTION FOLLOWUP REQUEST}}',
  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("{{FOLLOW UP URI RECEIVED AS PART OF THE RESPONSE OF THE TRANSACTION FOLLOWUP REQUEST}}")
  .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("{{FOLLOW UP URI RECEIVED AS PART OF THE RESPONSE OF THE TRANSACTION FOLLOWUP REQUEST}}");
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 => '{{FOLLOW UP URI RECEIVED AS PART OF THE RESPONSE OF THE TRANSACTION FOLLOWUP REQUEST}}',
  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

In the case of a successful response from the follow-up request initiated with the image, the success response will include a follow-up URI and bearer token. These details are required for the subsequent call to obtain the access token.

{
    "entity": {
        "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYbnNBNFVPdlkyU0JLSkdnX1ppTHN1Tk8tZ2dlLVB0RXZzX2twRTBhd3RnIn0.eyJleHAiOjE3MDM1ODE5NzUsIm5iZiI6MTcwMzU4MTY3NSwiaWF0IjoxNzAzNTgxNjc1LCJhdXRoX3RpbWUiOjE3MDM1ODE2NzUsImp0aSI6IjQwODczODM2LWRkNDAtNDI0NS1iNzYwLTQ4ZjgxYTRmMzg4ZiIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJlY2FiYzIzYS1iYThlLTQ3ZGUtYjdhNy1iZDlkZGYzZTAxNzEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcGkiLCJzZXNzaW9uX3N0YXRlIjoiZWZjNmM4OGItYTIyZC00ZWFmLTgyY2MtOTg0MGViYzNlMDA0Iiwic2NvcGUiOiIiLCJzaWQiOiJlZmM2Yzg4Yi1hMjJkLTRlYWYtODJjYy05ODQwZWJjM2UwMDQiLCJreWNfZXZlbnRfaWQiOiI4MjljODM3Zi01YmFjLTQ4YWYtYTViZC0zNDk5NTFjYzM2NDgiLCJsaXZlbGluZXNzVHJhbnNjYXRpb25JZCI6IjIwMjAwNjk0LTNiYzgtNDg4OS05MTIzLWM2OTI2ZDA5MGRhYSIsImZhY2VNYXRjaE1lc3NhZ2UiOiJTZWxmaWUgcGhvdG8gbWF0Y2hlcyB3aXRoIHJlZmVyZW5jZSBwaG90byIsImZhY2VNYXRjaFNjb3JlIjoiMS4wIiwibGl2ZWxpbmVzc1Njb3JlIjoiMC4wMDYzNzYiLCJtb2JpbGUiOiI4MjljODM3Zi01YmFjLTQ4YWYtYTViZC0zNDk5NTFjYzM2NDgiLCJzZXNzaW9uX2lkZW50aWZpZXIiOiJJYmdwYkdpLXdpYyIsInR5cGUiOiJGYWNlSUQiLCJsaXZlbGluZXNzQ29kZSI6IjEwNDMiLCJsaXZlbGluZXNzTWVzc2FnZSI6IlNlbGZpZSBwaG90byBpcyBhIGxpdmUgcGhvdG8iLCJmYWNlTWF0Y2hUcmFuc2NhdGlvbklkIjoiZDE0YjFlNzEtNDU3Yy00OTdjLTgwMTEtNzQwMGZiZjE1YjVjIiwiY3JlZGVudGlhbF9pZCI6ImJiZGNiMjg0LWE2NGMtNGMwYy04ODljLWMxMDBlMDk1NmZmZiJ9.UWzIn_E4u_OUcv9q4vLfeYCfkzdv6T11es-7zEX1oZxeFPbMZUR8Clj_5pEKLZTJmD01Dcdgm2FBU-4WvX9p3QmMI6pqkvQvDZilzFGkaKFYmZBI8VT9GmtD96OfRWQAtwUEiVbf_6pFHujHHMiydlndGoL9tm87nuMd9HwKD42Msejq4IdPNDUbnVhIMrqMaMkTyaE2jYGO1OzgZWm-InKXXV1_IuaXaZaIh2A2AfL2FDbyxTzRHFfd4BI5buSR03HUz_yw2hAwwHvXyojjU2MLYc76pQYfN38nUEhJLb6pGnbD01NRLIaiGQKQtYqKd8SmKjC2tOnXpsfj1WIpfA",
        "accessExpiresIn": 300,
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmMjFhZGYyZS03NWU2LTQ5Y2UtOWYwZi00ZDEwNjE0MDA4NGEifQ.eyJleHAiOjE3MDM1ODM0NzUsImlhdCI6MTcwMzU4MTY3NSwianRpIjoiMDI5OTExNmMtMGY2OS00NjEyLTgyZTYtNzdiMzIwM2I3NDNlIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay5hdXRoLXN0YWdlLnZpZGEuaWQvcmVhbG1zL3NwcmluZ2Jvb3QtcXVpY2tzdGFydCIsImF1ZCI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJlY2FiYzIzYS1iYThlLTQ3ZGUtYjdhNy1iZDlkZGYzZTAxNzEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYXBpIiwic2Vzc2lvbl9zdGF0ZSI6ImVmYzZjODhiLWEyMmQtNGVhZi04MmNjLTk4NDBlYmMzZTAwNCIsInNjb3BlIjoiIiwic2lkIjoiZWZjNmM4OGItYTIyZC00ZWFmLTgyY2MtOTg0MGViYzNlMDA0In0.XGkS03_dTcVCA2hwYfN-6BI1AmdoJEYIORE_i4-wD2w",
        "refreshExpiresIn": 1800,
        "authType": "FaceID"
    },
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlZmM2Yzg4Yi1hMjJkLTRlYWYtODJjYy05ODQwZWJjM2UwMDQiLCJleGVjdXRpb24iOm51bGwsInRhYl9pZCI6IkliZ3BiR2ktd2ljIiwibmJmIjoxNzAzNTgxNjc1LCJzZXNzaW9uX2NvZGUiOiJSRFpLVXFId1oxeHZseTFnYm8ySkhIblVMUkk4VEV5VjM3SVFPM0ZsTEdzIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiSWJncGJHaS13aWMiLCJleHAiOjE3MDM1ODE5NzUsImlhdCI6MTcwMzU4MTY3NSwiYXV0aF9zZXNzaW9uX2lkIjoiZWZjNmM4OGItYTIyZC00ZWFmLTgyY2MtOTg0MGViYzNlMDA0IiwianRpIjoiYmZkYmI4ZGUtZjY5MC00OWZlLWEwYjAtNzYxNjMyOGU2NDI2In0.t7hWqOupNrB_a7EMhLfthxCRfK-hDf35x09FPJFWnj0",
    "authType": "FaceID"
}

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.