Cashfree Payments Developer Documentation

Face Liveness Check

curl --request POST \
  --url https://sandbox.cashfree.com/verification/face-liveness \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --form verification_id=test_verification_id \
  --form image='@example-file'

{
  "reference_id": 1078756,
  "verification_id": "asbfhjjree1247",
  "status": "SUCCESS",
  "liveness": true,
  "liveness_score": 0.98,
  "gender": {
    "value": "FEMALE",
    "confidence": 98.4
  },
  "age_range": {
    "min": 29,
    "max": 37
  },
  "eye_wear": {
    "value": true,
    "confidence": 96.4
  },
  "face_occluded": {
    "value": false,
    "confidence": 98.7
  },
  "quality": {
    "blur": false,
    "bright": true,
    "exposure": "NEUTRAL"
  },
  "pose": {
    "face_alignment": "LEFT",
    "head_turned": false
  },
  "eyes_open": {
    "value": true,
    "confidence": 95.5
  }
}

POST

face-liveness

Face Liveness Check

curl --request POST \
  --url https://sandbox.cashfree.com/verification/face-liveness \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --form verification_id=test_verification_id \
  --form image='@example-file'

{
  "reference_id": 1078756,
  "verification_id": "asbfhjjree1247",
  "status": "SUCCESS",
  "liveness": true,
  "liveness_score": 0.98,
  "gender": {
    "value": "FEMALE",
    "confidence": 98.4
  },
  "age_range": {
    "min": 29,
    "max": 37
  },
  "eye_wear": {
    "value": true,
    "confidence": 96.4
  },
  "face_occluded": {
    "value": false,
    "confidence": 98.7
  },
  "quality": {
    "blur": false,
    "bright": true,
    "exposure": "NEUTRAL"
  },
  "pose": {
    "face_alignment": "LEFT",
    "head_turned": false
  },
  "eyes_open": {
    "value": true,
    "confidence": 95.5
  }
}

Authorizations

x-client-id

string

header

required

Your unique client identifier issued by Cashfree. You can find this in your Merchant Dashboard.

x-client-secret

string

header

required

The secret key associated with your client ID. Use this to authenticate your API requests. You can find this in your Merchant Dashboard.

Headers

x-cf-signature

string

Send the signature if two-factor authentication is selected as Public Key. More details

x-api-version

string

default:2024-12-01

required

API version to be used. Format is in YYYY-MM-DD.

Example:

"2024-12-01"

Body

multipart/form-data

Find the request parameters of Face Liveness Check.

verification_id

string

default:test_verification_id

required

It is the unique ID you create to identify the verification request. The maximum character limit is 50. Only alphanumeric, period (.), hyphen (-) and underscore ( _ ) are allowed.

Example:

"test_verification_id"

image

file

required

Upload the image of the individual to verify the liveness of the image. Supported types are jpeg, jpg and png.

Example:

"<image_file>"

Response

Success response for checking the face liveness.

reference_id

integer

Unique reference ID generated by Cashfree.

Example:

1078756

verification_id

string

It displays the unique ID you created to identify this API request.

Example:

"asbfhjjree1247"

status

string

The status of the face liveness verification request. Possible values:

SUCCESS: Face verification completed successfully
REAL_FACE_NOT_DETECTED: The submitted image does not contain a real face
MULTIPLE_FACES_DETECTED: More than one face detected in the image
FACE_NOT_DETECTED: No face detected in the submitted image

Example:

"SUCCESS"

liveness

boolean

Indicates whether the detected face exhibits signs of being from a live person.

Example:

true

liveness_score

number<float>

A confidence score between 0 and 1 indicating the probability that the face is from a live person.

Example:

0.98

gender

object

Show child attributes

gender.value

string

Detected gender of the person in the image.

Example:

"FEMALE"

gender.confidence

number<float>

Confidence score for gender detection (0-100).

Example:

98.4

age_range

object

Show child attributes

age_range.min

integer

Lower bound of the estimated age range.

Example:

29

age_range.max

integer

Upper bound of the estimated age range.

Example:

37

eye_wear

object

Show child attributes

eye_wear.value

boolean

Indicates whether the person is wearing glasses or other eyewear.

Example:

true

eye_wear.confidence

number<float>

Confidence score for eyewear detection (0-100).

Example:

96.4

face_occluded

object

Show child attributes

face_occluded.value

boolean

Indicates whether the face is partially covered or obscured.

Example:

false

face_occluded.confidence

number<float>

Confidence score for face occlusion detection (0-100).

Example:

98.7

quality

object

Show child attributes

quality.blur

boolean

Indicates whether the image is blurry.

Example:

false

quality.bright

boolean

Indicates whether the image has adequate lighting.

Example:

true

quality.exposure

enum<string>

Assessment of image exposure level.

Available options:

UNDER_EXPOSED,

NEUTRAL,

OVER_EXPOSED

Example:

"NEUTRAL"

pose

object

Show child attributes

pose.face_alignment

enum<string>

Direction of face alignment in the image.

Available options:

LEFT,

RIGHT,

CENTRE

pose.head_turned

boolean

Indicates whether the head is turned from the frontal position.

Example:

false

eyes_open

object

Show child attributes

eyes_open.value

boolean

Indicates whether both eyes are open in the image.

Example:

true

eyes_open.confidence

number<float>

Confidence score for eyes open detection (0-100).

Example:

95.5

Verify Name Match Smart OCR

⌘I

Secure ID APIs

V2

V1 (Depricated API's)

Face Liveness Check

Authorizations

Headers

Body

Response