Biometric Verification

Biometric Verification only

This configuration performs biometric-only verification, focusing specifically on evaluating the user’s selfie through liveness detection, image quality assessment, manipulation checks, and face validation. Although the request includes a full set of identity data such as name, government ID, and date of birth, only the biometric components are processed and validated. This setup is suitable for scenarios where demographic validation is handled externally through a registration authority agreement.

If only the Biometric Verification is conducted, then a Level 1 Certificate will be issued upon acceptance.

Parameters

Field

Type

Description

Sample Value

partnerTrxId

string

Generate a unique transaction ID in UUID format and include it in the request to link your transaction with the VIDA transaction.

Generated random uuid by the partner.

Example:

1000073-c00f-4008-8005-d2ec4d9be956

groupId

string

For each NIK, partners should send a unique group ID that can be used to track related transactions across multiple fraud assessment categories.

This is mandatory for customers using Multistage verification

Generated random UUID by the partner.

Example:

8000073-d00e-9008-9005-d2ce4b9ce956

transactionType*

string

Type of the transaction

In the biometric verification below transaction type is applicable BIOMETRIC_FRAUD_ASSESSMENT

govId*

string

The user's government ID number

NIK - Nomor Induk Kependudukan), consisting of a 16-digit number: 3451222123456716

Here are following validation that must to follow for NIK input:

NIK must 16 digit number
NIK shouldn't be started with "0"

govIdType

string

The type of IDCard Document.

Supported values: "KTP"

fullName*

string

Users Full Name which should same with registered ID

User full name as per KTP.

Example: Johnny Rudiantara Sembiring

dob*

string

User's Date of Birth

Date of Birth in yyyy-mm-dd format

Example: 1989-01-01

mobile*

string

The user's verified mobile number with the country code, provided in E.164 format without spaces or special characters.

If the mobile number isn’t available, a verified email address can be passed, however, one of the two is mandatory.

Example: +6281293671234

string

The user's valid email address

Example: user@example.com

consent*

object

A user’s consented timestamp value where they agreed to consent sharing data with VIDA

"consent": {

"consentedAt": "1614089870",

"consentGiven": true

}

selfiePhoto*

base64-encoded string

A base64-encoded string of the user's selfie for facial recognition and face-match checks, adhering to specified image standards.

Example: "/9j/4AAQSkZJRgABAQAAJAAkAAD/4QhcR..."

idCardPhoto

base64-encoded string

A plain base64-encoded string of the user ID card Photo (i.e. KTP)

Example: "/9j/4AAQSkZJRgABAQAAJAAkAAD/4QhcR..."

*required

Note: When using biometric verification, only the biometric data will be validated, regardless of any additional parameters provided (e.g., fullName, dob, email). These additional fields may be included in the request but will not be assessed in this type.

Sample Request

Sample JSON Request (Main Parameters Only)

{
    "partnerTrxId": "{{random-UUID}}", //must be unique for every transaction.
    "groupId": "{{UUID4}}", //Required for Multistage verification
    "transactionType": "BIOMETRIC_FRAUD_ASSESSMENT",
    "mobile": "Phone Number from ID Card",
    "email": "useremail@emailprovider.com",
    "govId": "Gov Id from ID Card",
    "govIdType": "KTP",
    "fullName":"Userbcde", //recorded but not verified
    "dob": "YYYY-MM-DD", //recorded but not verified
    "selfiePhoto": "{{selfieID1}}",
    "consent": {
        "consentedAt": "1614089870",
        "consentGiven": true
    }
}

Sample Response

HTTP Status Code: 200

JSON Response (Main Parameters only)

{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is bound to the certificate requesting client"
        },
        //authenticationLevel & certificate field should NOT be used programmatically
        //authenticationLevel & certificate result depends on verification data availability & its RA level
        //Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status,

        "transactionType": "BIOMETRIC_FRAUD_ASSESSMENT",
        "transactionId": "unique transaction id generated to identify this transaction",
        "groupId": "{{as provided in request}}", //Returned only for Multistage Verification
        "registrationId": "unique VIDA user ID" //Returned only for Multistage Verification on success, used for digital signature
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "selfiePhoto",
                "result": 0.9
            },
            {
                "name": "liveness",
                "result": 0.164398
            },
            {
                "name": "imgManipulationScore",
                "result": 0.117981
            }
        ]
    }
}

Sample Response Value Explanation

Values

Description

selfiePhoto

The degree of match between the selfie provided and the stored biometric data. (Score threshold: 0 to 1)

liveness

Score indicating the likelihood that the selfie represents a live person. (Score threshold: 0 to 1)

imgManipulationScore

Probability of image manipulation in the selfie. (Score threshold: 0 to 1)

fraudAssessment

Indicates whether the fraud assessment process is completed or in progress.

authenticationLevel

Assurance level of the authentication process. authenticationLevel field should not be used programatically to determine a successful transaction. Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status

certificate

Details regarding the certificate's trustworthiness for digital signatures. certificate field should not be used programatically to determine a successful transaction. Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status

groupId

Returned only for Multistage Verification. The groupId passed on the request body

registrationId

Returned only for Multistage Verification on success, used for digital signature

1. Accept Response

HTTP Status Code: 200

Status : SUCCESS

Main Required Parameters

JSON Response

{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is bound to the certificate requesting client"
        },
        "transactionType": "BIOMETRIC_FRAUD_ASSESSMENT",
        "transactionId": "unique transaction id generated to identify this transaction",
        "groupId": "{{as received in request}}",
        "registrationId": "unique VIDA user ID" //Returned only for Multistage Verification on success, used for digital signature        
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "selfiePhoto",
                "result": 0.9
            },
            {
                "name": "liveness",
                "result": 0.164398
            },
            {
                "name": "imgManipulationScore",
                "result": 0.117981
            }
        ]
    }
}

With All Extended Demographic Parameters

JSON Response

{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is bound to the certificate requesting client"
        },
        "transactionType": "BIOMETRIC_FRAUD_ASSESSMENT",
        "transactionId": "unique transaction id generated to identify this transaction",
        "groupId": "{{as received in request}}",
        "registrationId": "unique VIDA user ID" //Returned only for Multistage Verification on success, used for digital signature
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "selfiePhoto",
                "result": 0.9
            },
            {
                "name": "liveness",
                "result": 0.164398
            },
            {
                "name": "imgManipulationScore",
                "result": 0.117981
            }
        ]
    }
}

2. Reject Responses

2.1 Selfie photo match does not pass threshold

HTTP Status Code: 200

Status : SUCCESS

Sample Response if the Case of 0.3

JSON Response

{
    "data": {
        "transactionType": "BIOMETRIC_FRAUD_ASSESSMENT",
        "transactionId": "73b0f092-a4be-468e-bedf-8a914c9cfd16",
        "groupId": "{{as received in request}}",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "selfiePhoto",
                "result": 0.30000000000000004
            },
            {
                "name": "liveness",
                "result": 0.070489
            },
            {
                "name": "imgManipulationScore",
                "result": 0.081049
            }

        ]
    }
}

Sample Response if the Case of 0.7

JSON Response

{
    "data": {
        "transactionType": "BIOMETRIC_FRAUD_ASSESSMENT",
        "transactionId": "73b0f092-a4be-468e-bedf-8a914c9cfd16",
        "groupId": "{{as received in request}}",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "selfiePhoto",
                "result": 0.7000000000000001
            },
            {
                "name": "liveness",
                "result": 0.070489
            },
            {
                "name": "imgManipulationScore",
                "result": 0.081049
            }

        ]
    }
}

2.2 Liveness and image manipulation does not pass threshold

HTTP Status Code: 200

Status : SUCCESS

Both Fails

JSON Response

{
    "data": {
        "transactionType": "BIOMETRIC_FRAUD_ASSESSMENT",
        "transactionId": "73b0f092-a4be-468e-bedf-8a914c9cfd16",
        "groupId": "{{as received in request}}",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "liveness",
                "result": 0.999932
            },
            {
                "name": "imgManipulationScore",
                "result": 0.997597
            }
        ]
    }
}

Only 1 Passed

JSON Response

{
    "data": {
        "transactionType": "BIOMETRIC_FRAUD_ASSESSMENT",
        "transactionId": "73b0f092-a4be-468e-bedf-8a914c9cfd16",
        "groupId": "{{as received in request}}",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "liveness",
                "result": 0.669388
            },
            {
                "name": "imgManipulationScore",
                "result": 0.998272
            }
        ]
    }
}

2.3 Image quality not passed (single detail)

HTTP Status Code: 200

Status : SUCCESS

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1051,
            "title": "Detect Un-standardized Image Quality",
            "detail": "Face Occluded"
        }
    ]
}

{
    "transactionId": "2ad38778-00d9-4fdf-b509-a3b6bf35eb34",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1052,
            "title": "Detect Un-standardized Image Quality",
            "detail": "Face too small"
        }
    ]

{
    "transactionId": "b0f4a52f-d917-41d1-8e0b-23fa93c34d15",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1054,
            "title": "Detect Un-standardized Image Quality",
            "detail": "More than one face"
        }
    ]
}

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1055,
            "title": "Detect Un-standardized Image Quality",
            "detail": "No face detected"
        }
    ]
}

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        }
    ]
}

2.4 Image quality not passed (multiple details)

HTTP Status Code: 200

Status : SUCCESS

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1075,
            "title": "Image Quality Is Below Threshold",
            "detail": "Over Exposure"
        },
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        }
    ]
}

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1074,
            "title": "Image Quality Is Below Threshold",
            "detail": "Under Exposure"
        },
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        }
    ]
}

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "UnNatural Color"
        },
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        }
    ]
}

3. Required parameters are missing

These errors occur when one or more mandatory fields are not provided in the request. The response includes details of the missing parameter in the detail field.

HTTP Status Code: 400

Status : ERROR

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "must not be blank",
            "detail": "fullName"
        }
    ]
}

{
    "errors": [
        {
            "code": 1006,
            "title": "must not be blank",
            "detail": "selfiePhoto"
        }
    ]
}

{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid image base64 String",
            "detail": "selfiePhoto"
        }
    ]
}

Last updated 10 months ago