VKYC Integration | Cashfree Payments

Cashfree Video KYC (VKYC) is a secure, RBI-compliant digital customer verification solution that enables businesses to complete customer onboarding remotely through a live video interaction. Merchants can choose to integrate VKYC in two ways, depending on their user experience requirements and technical capabilities. Cashfree offers the following ways to integrate VKYC: Integrating using the SDK

Integrate the VKYC process directly into your web or mobile application.
Provide a seamless in-app experience for customers without redirecting them.
Support an OTP-less flow if the customer is already authenticated in your application.
Use SDK callbacks to handle events such as success, failure, or closure, and to track activity and customise your user interface.

Integrating using the APIs

Generate a unique VKYC link for each customer.
Share the link via SMS, email, or any external channel.
Allow customers to complete the VKYC process outside your application.

Integrating using the SDK
Integrating using the APIs

The VKYC SDK supports Web, Android, and iOS platforms and communicates securely with Cashfree servers through callbacks.This topic includes the following sections:

SDK VKYC flow
Initialising SDK
Callback structure

SDK VKYC flow

Refer to the steps below for the VKYC flow for SDK:

Create the user using the Create User for Secure ID Suite API. You must complete this step before initiating the VKYC session.
Start the VKYC session using the Initiate Video KYC Request API. Pass the user ID and authentication token to the SDK.
Generate an authentication token using the Create Auth Token API. This token is required to initialise the SDK. Use it to bypass OTP verification if the user is already authenticated in your application.
Retrieve the current session status using the Get Video KYC Status API.
Configure webhooks to receive real-time updates on VKYC events. For more information, refer to Webhook.

Refer to the image below for a sample workflow:

Initialising SDK

Refer to the instructions below to initialise the SDK for your target platform. The SDK communicates with Cashfree and provides real-time updates through callbacks.You can initialise the SDK for:

Web integration

Initialise the Web SDKRefer to the example code snippet below to initialise the Web SDK:

const vkyc = CFVKYC({
  srcUrl: "https://forms.cashfree.com/verification/<shortCode>",
  oAuthToken: "<OAuth Token>", // Optional: enables OTP-less flow
  callback: (response) => {
    console.log("VKYC Response:", response);
  },
});

Parameter	Type	Required	Description
`srcUrl`	string	Yes	Base or full VKYC verification URL.
`oAuthToken`	string	No	Pass this token for OTP-less flow.
`callback`	function	Yes	Handles all SDK messages and responses.

Do not pass the OAuth token if you want Cashfree to perform the OTP check.

Close the SDK programmaticallyRefer to the code snippet below to close the SDK instance in your application:

vkyc.closeSDK();

Import the hosted JavaScript SDKRefer to the instructions below to import the SDK script into your HTML page.

Add the SDK script for your environment. Production environment:

<script src="https://vssdk-prod.cashfree.com/vkyc-sdk/prod/1.0.0/index.js"></script>

Sandbox environment:

<script src="https://vssdk-prod.cashfree.com/vkyc-sdk/gamma/1.0.0/index.js"></script>

Include a <div> for the SDK container.

<html>
  <head>
    <title>Video KYC</title>
    <script src="https://vssdk-prod.cashfree.com/vkyc-sdk/prod/1.0.0/index.js"></script>
  </head>
  <body>
    <div id="cf-vkyc-sdk"></div>
  </body>
</html>

Android native integration

Add the SDK dependencyRefer to the steps below to add the SDK to your Android project.

Add the Maven repository in settings.gradle.kts.

repositories {
    google()
    mavenCentral()
    maven { url = URI("https://maven.cashfree.com/release") }
}

Add the SDK dependency in build.gradle.kts.

dependencies {
    implementation("com.cashfree.vrs:kyc-verification:1.0.4")
}

Click Sync Now in Android Studio to sync your project.

Initialise and use the SDK

Create an instance of the verification service.

val verificationService = CFVerificationService.Builder()
    .setContext(this)
    .build()

Configure the callback to handle verification responses.

verificationService.setKycVerificationCallback(object : CFVerificationCallback {
    override fun onVerificationResponse(response: CFVerificationResponse) {
        showAlert(response)
    }

    override fun onErrorResponse(error: CFErrorResponse) {
        showAlert("Verification Error", error.message)
    }

    override fun onVKycCloseResponse(response: CFVKycCloseResponse) {
        showAlert("VKYC Closed", response.verificationId)
    }
})

Initiate the verification process.

verificationService.doVerification(kycUrl, token)

Parameter	Description
`kycUrl`	VKYC video call URL
`token`	Authentication token for VKYC

iOS native integration

The following are the requirements before integrating the iOS SDK:

iOS version: 13.0 or later
Swift version: 5.0 or later
Xcode version: 14.0 or later

Install the SDKTo install the SDK:

Open your Xcode project.
Go to File > Add Packages.

Enter the repository URL:

https://github.com/cashfree/KycVerificationSdk.git

Select the version and add the package to your project.

Initialise and use the SDK

Create an instance.

let kycService = CFVerificationService.getInstance()

Set up callback handlers.

func onVerificationCompletion(verificationResponse: KycVerificationSdk.CFVerificationResponse) {
    if verificationResponse.status == "SUCCESS" {
        print("Success: Verification successful")
    } else {
        print("Error: Verification failed, please try again")
    }
}

func onErrorResponse(errorReponse: KycVerificationSdk.CFErrorResponse) {
    print("Error: \(errorReponse.message ?? "")")
}

func onVerification(_ verificationResponse: KycVerificationSdk.CFSecureShareResponse) {
    print("Verification ID: \(verificationResponse.verificationId ?? "N/A")")
}

func onVerificationError(_ errorResponse: KycVerificationSdk.CFSecureShareErrorResponse) {
    print("Error Status: \(errorResponse.status ?? "N/A")")
}

func onUserDrop(_ userDropResponse: KycVerificationSdk.CFUserDropResponse) {
    print("User Dropped: \(userDropResponse.verificationId ?? "N/A")")
}

func onVkycCloseResponse(verificationResponse: KycVerificationSdk.CFVKycCloseResponse) {
    print("VKYC Closed")
}

Start the VKYC session.

do {
    let kycService = CFVerificationService.getInstance()
    try kycService.doVerification(kycUrl, self, self, accessToken)
} catch let error {
    print("Error: \(error)")
}

Callback structure

Refer to the sample response below for the VKYC callback structure:

{
  "verificationId": "verificationId_value",
  "status": "<STATUS>"
}

Status	Description
`TOKEN_EXPIRED`	The OAuth token has expired.
`SRC_URL_MISSING`	The `srcUrl` parameter isn’t provided.
`DIV_MISSING`	The `<div>` with ID `cf-vkyc-sdk` is missing.
`CLOSE`	The SDK session was closed by Cashfree.

Additional Notes:

Ensure the <div> with ID cf-vkyc-sdk exists in your HTML.
The SDK applies default styling for consistent behaviour. Custom styling is not supported.
The embedded iframe uses sandboxing for secure interactions.

Secure ID APIs

V2

V1 (Depricated API's)

Video KYC Integration

SDK VKYC flow

Initialising SDK

Web integration

Android native integration

iOS native integration

Callback structure

​SDK VKYC flow

​Initialising SDK

​Web integration

​Android native integration

​iOS native integration

​Callback structure

SDK VKYC flow

Initialising SDK

Web integration

Android native integration

iOS native integration

Callback structure