Cashfree Payments Developer Documentation

Initiate Video KYC Request

curl --request POST \
  --url https://sandbox.cashfree.com/verification/vkyc \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data @- <<EOF
{
  "value": {
    "verification_id": "vkyc_verification_id",
    "user_template": "vkyc_user_template_v1",
    "agent_template": "vkyc_agent_template_v1",
    "user_reference_id": 8713,
    "notification_types": [
      "sms",
      "whatsapp"
    ],
    "aadhaar_details": {
      "last_verified_at": "2025-05-07T15:04:05Z",
      "care_of": "S/O: Fakkirappa Dollin",
      "dob": "02-02-1995",
      "gender": "M",
      "name": "Mallesh Fakkirappa Dollin",
      "split_address": {
        "country": "India",
        "dist": "Haveri",
        "house": "Shri Kanaka Nilaya",
        "pincode": 581115,
        "po": "Ranebennur",
        "state": "Karnataka",
        "street": "Umashankar Nagar 1st Main 5th Cross",
        "subdist": "Ranibennur",
        "vtc": "Ranibennur"
      },
      "year_of_birth": 1995,
      "photo_link": "<<link where aadhaar image is hosted on merchants end>"
    },
    "security_questions": [
      {
        "order": 1,
        "question": "What is your father's name?",
        "answer": "John Snow"
      },
      {
        "order": 2,
        "question": "What is your first pet's name?",
        "answer": "Oreo"
      }
    ]
  }
}
EOF

{
  "verification_id": "test053",
  "reference_id": 10042,
  "status": "PRE_VIDEO_CALL",
  "sub_status": "AADHAAR_VERIFICATION_SUCCESS",
  "vkyc_link": "https://forms.cashfree.com/verification/M8go0i1k9fvg",
  "link_expiry": "2025-05-30T00:00:00.000Z",
  "user_reference_id": 123456,
  "user_id": "User0123",
  "aadhaar_details": {
    "last_verified_at": "2025-05-06T15:04:05.000Z",
    "care_of": "Jerripothula Koteswrara Rao",
    "dob": "02-02-1995",
    "gender": "M",
    "name": "Mallesh Fakkirappa Dollin",
    "photo_link": "https://cf-prod-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/51826/10042/photo-link/photo.jpg",
    "split_address": {
      "country": "India",
      "dist": "Haveri",
      "house": "Shri Kanaka Nilaya",
      "pincode": 581115,
      "po": "Ranebennur",
      "state": "Karnataka",
      "street": "Umashankar Nagar 1st Main 5th Cross",
      "subdist": "Ranibennur",
      "vtc": "Ranibennur"
    }
  },
  "security_questions": [
    {
      "question": "What is your fathers's name ?",
      "answer": "John",
      "order": 1
    }
  ]
}

POST

vkyc

Initiate Video KYC Request

curl --request POST \
  --url https://sandbox.cashfree.com/verification/vkyc \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data @- <<EOF
{
  "value": {
    "verification_id": "vkyc_verification_id",
    "user_template": "vkyc_user_template_v1",
    "agent_template": "vkyc_agent_template_v1",
    "user_reference_id": 8713,
    "notification_types": [
      "sms",
      "whatsapp"
    ],
    "aadhaar_details": {
      "last_verified_at": "2025-05-07T15:04:05Z",
      "care_of": "S/O: Fakkirappa Dollin",
      "dob": "02-02-1995",
      "gender": "M",
      "name": "Mallesh Fakkirappa Dollin",
      "split_address": {
        "country": "India",
        "dist": "Haveri",
        "house": "Shri Kanaka Nilaya",
        "pincode": 581115,
        "po": "Ranebennur",
        "state": "Karnataka",
        "street": "Umashankar Nagar 1st Main 5th Cross",
        "subdist": "Ranibennur",
        "vtc": "Ranibennur"
      },
      "year_of_birth": 1995,
      "photo_link": "<<link where aadhaar image is hosted on merchants end>"
    },
    "security_questions": [
      {
        "order": 1,
        "question": "What is your father's name?",
        "answer": "John Snow"
      },
      {
        "order": 2,
        "question": "What is your first pet's name?",
        "answer": "Oreo"
      }
    ]
  }
}
EOF

{
  "verification_id": "test053",
  "reference_id": 10042,
  "status": "PRE_VIDEO_CALL",
  "sub_status": "AADHAAR_VERIFICATION_SUCCESS",
  "vkyc_link": "https://forms.cashfree.com/verification/M8go0i1k9fvg",
  "link_expiry": "2025-05-30T00:00:00.000Z",
  "user_reference_id": 123456,
  "user_id": "User0123",
  "aadhaar_details": {
    "last_verified_at": "2025-05-06T15:04:05.000Z",
    "care_of": "Jerripothula Koteswrara Rao",
    "dob": "02-02-1995",
    "gender": "M",
    "name": "Mallesh Fakkirappa Dollin",
    "photo_link": "https://cf-prod-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/51826/10042/photo-link/photo.jpg",
    "split_address": {
      "country": "India",
      "dist": "Haveri",
      "house": "Shri Kanaka Nilaya",
      "pincode": 581115,
      "po": "Ranebennur",
      "state": "Karnataka",
      "street": "Umashankar Nagar 1st Main 5th Cross",
      "subdist": "Ranibennur",
      "vtc": "Ranibennur"
    }
  },
  "security_questions": [
    {
      "question": "What is your fathers's name ?",
      "answer": "John",
      "order": 1
    }
  ]
}

Template Behavior: Including Aadhaar details in this request skips the DigiLocker verification step, reducing the user journey from 3 steps to 2. See User Templates for details.

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

application/json

Request parameters to generate Video KYC link.

verification_id

string

default:vkyc_verification_id

required

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

Example:

"vkyc_verification_id"

user_template

string

default:vkyc_user_template_v1

It is the name of users vkyc template more details.

Example:

"vkyc_user_template_v1"

agent_template

string

default:vkyc_agent_template_v1

It is the name of agents vkyc template more details.

Example:

"vkyc_agent_template_v1"

user_reference_id

integer

default:1358

It is the unique ID created by Cashfree Payments that you receive in the response of Create User for Secure ID API.

Example:

1358

user_id

string

default:User0123

It is the unique ID you create to identify the user in Create User for Secure ID API.

Example:

"User0123"

notification_types

string[]

List of notification types that should be triggered for this request.

Example:

["sms", "whatsapp"]

aadhaar_details

object

Show child attributes

aadhaar_details.last_verified_at

string<date-time>

required

Example:

"2025-05-07T15:04:05Z"

aadhaar_details.care_of

string

required

Example:

"S/O: Fakkirappa Dollin"

aadhaar_details.dob

string<date>

required

Example:

"02-02-1995"

aadhaar_details.gender

enum<string>

required

Available options:

M,

F,

O

Example:

"M"

aadhaar_details.name

string

required

Example:

"Mallesh Fakkirappa Dollin"

aadhaar_details.photo_link

string<uri>

required

Example:

"<link where aadhaar image is hosted on merchants end>"

aadhaar_details.split_address

object

Show child attributes

aadhaar_details.split_address.country

string

required

Example:

"India"

aadhaar_details.split_address.dist

string

required

Example:

"Haveri"

aadhaar_details.split_address.house

string

required

Example:

"Shri Kanaka Nilaya"

aadhaar_details.split_address.pincode

integer

required

Example:

581115

aadhaar_details.split_address.state

string

required

Example:

"Karnataka"

aadhaar_details.split_address.street

string

required

Example:

"Umashankar Nagar 1st Main 5th Cross"

aadhaar_details.split_address.po

string

Example:

"Ranebennur"

aadhaar_details.split_address.subdist

string

Example:

"Ranibennur"

aadhaar_details.split_address.vtc

string

Example:

"Ranibennur"

security_questions

object[]

Show child attributes

security_questions.order

integer

required

Example:

1

security_questions.question

string

required

Example:

"What is your father's name?"

security_questions.answer

string

required

Example:

"John Snow"

Response

Success response for generating a Video KYC link.

verification_id

string

It displays the unique ID you created to identify the verification request.

Example:

"test053"

reference_id

integer

It displays the unique ID created by Cashfree Payments for reference purposes. format: int64

Example:

10042

status

string

It displays the status of the API request. Refer to this link for all possible values and their meanings.

Example:

"PRE_VIDEO_CALL"

sub_status

string

It displays the sub status of the API request. Refer to this link for all possible values and their meanings.

Example:

"AADHAAR_VERIFICATION_SUCCESS"

vkyc_link

string

It displays the URL of the vKYC form to be filled by the user.

Example:

"https://forms.cashfree.com/verification/M8go0i1k9fvg"

link_expiry

string<date>

The date on which the vKYC link will expire.

Example:

"2025-05-30T00:00:00.000Z"

user_reference_id

string

The reference ID of the user for whom the VKYC link is generated.

Example:

123456

user_id

string

The user ID of the user for whom the VKYC link is generated.

Example:

"User0123"

aadhaar_details

object

Aadhaar information associated with the user.

Show child attributes

aadhaar_details.last_verified_at

string<date-time>

Timestamp when Aadhaar was last verified.

Example:

"2025-05-06T15:04:05.000Z"

aadhaar_details.care_of

string

It displays the parent/guardian of the user.

Example:

"Jerripothula Koteswrara Rao"

aadhaar_details.dob

string

It displays the date of birth of the user.

Example:

"02-02-1995"

aadhaar_details.gender

string

It displays the gender of the user.

Example:

"M"

aadhaar_details.name

string

It displays the name of the user.

Example:

"Mallesh Fakkirappa Dollin"

aadhaar_details.photo_link

string

It displays the URL to the image present in the aadhaar card.

Example:

"https://cf-prod-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/51826/10042/photo-link/photo.jpg"

aadhaar_details.split_address

object

Split address as extracted from Aadhaar.

Show child attributes

aadhaar_details.split_address.country

string

It displays the name of the country as present in the aadhaar card of user.

Example:

"India"

aadhaar_details.split_address.dist

string

It displays the name of the dist as present in the aadhaar card of user.

Example:

"Haveri"

aadhaar_details.split_address.house

string

It displays the house name/number as present in the aadhaar card of user.

Example:

"Shri Kanaka Nilaya"

aadhaar_details.split_address.pincode

integer

It displays the PIN code information as present in the aadhaar card of user.

Example:

581115

aadhaar_details.split_address.po

string

It displays the post office nearest to the address present in the aadhaar card of user.

Example:

"Ranebennur"

aadhaar_details.split_address.state

string

It displays the name of the state as present in the aadhaar card of user.

Example:

"Karnataka"

aadhaar_details.split_address.street

string

It displays the name of the street as present in the aadhaar card of user.

Example:

"Umashankar Nagar 1st Main 5th Cross"

aadhaar_details.split_address.subdist

string

It displays the name of the sub district as present in the aadhaar card of user.

Example:

"Ranibennur"

aadhaar_details.split_address.vtc

string

It displays the village, town, city information as present in the aadhaar card of user.

Example:

"Ranibennur"

security_questions

object[]

List of security questions and answers.

Show child attributes

security_questions.question

string

Security question asked to the user.

Example:

"What is your fathers's name ?"

security_questions.answer

string

Answer provided by the user.

Example:

"John"

security_questions.order

integer

Order of the security question.

Example:

1

Create User for Secure ID Get status of Video KYC

⌘I

Secure ID APIs

V2

V1 (Depricated API's)

Initiate Video KYC Request

Authorizations

Headers

Body

Response