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.
-
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>
<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.
