Skip to main content
POST
https://api.stablepay.global
/
v2
/
users
/
{userId}
/
kyc
/
face
/
init
Verify Face
curl --request POST \
  --url https://api.stablepay.global/v2/users/{userId}/kyc/face/init \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "redirectUrl": "<string>",
  "deviceId": "<string>",
  "sessionId": "<string>"
}
'

​
Face Verification

Face verification is required. Users can complete KYC and transact without face verification. Only Aadhaar, PAN, and Bank are required.
Face verification is a two-step process:
  1. Initialize - Get a session URL for the user to complete face liveness
  2. Verify - Check the verification status after user completes the flow

​
Initialize Face Verification

​
redirectUrl
string
Required URL to redirect user after completion
​
deviceId
string
required
Device fingerprint/ID for FIU compliance. Must be captured from the client device.

​
Request

curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/face/init \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://yourapp.com/kyc/callback",
    "deviceId": "device-fingerprint-12345"
  }'

​
Response

{
  "success": true,
  "data": {
    "sessionId": "face_1704067200_abc123",
    "sdkToken": "face_1704067200_abc123",
    "url": "https://kyc-sdk.surepass.io/face-liveness?token=...",
    "expiresIn": 600
  }
}
Direct the user to the url to complete face liveness verification. The session expires in 10 minutes.

​
Check Face Verification Status

After the user completes the face liveness flow, check the verification status.
​
sessionId
string
The sessionId from the init response (optional if stored in database)

​
Request

curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/face/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "face_1704067200_abc123"}'

​
Response (Verified)

{
  "success": true,
  "data": {
    "verified": true,
    "livenessScore": 0.95,
    "faceMatchScore": 0.88,
    "isLive": true,
    "faceMatched": true,
    "message": "Face liveness verified"
  }
}

​
Response (Pending)

{
  "success": true,
  "data": {
    "verified": false,
    "livenessScore": 0,
    "faceMatchScore": 0,
    "isLive": false,
    "faceMatched": false,
    "message": "Face verification pending or failed"
  }
}

​
Verification Thresholds

MetricThresholdDescription
Liveness Score>= 0.8Confidence that the face is live (not a photo/video)
Face Match Score>= 0.7Similarity between selfie and reference image

​
Errors

CodeDescription
SESSION_NOT_FOUNDFace verification session not initialized
ALREADY_VERIFIEDFace is already verified for this user
SESSION_EXPIREDThe session has expired, initialize again