Last updated
Last updated
# Identity Verification — Callback Methods & Response Structure
## Overview
The identity verification workflow provides multiple callback methods to handle different stages of the verification process. We recommend using **`onComplete`** and **`onError`** as the primary callbacks — they provide the complete verification response at the end of the flow.
For use cases where immediate responses are needed at specific stages (e.g., updating UI after document capture or handling partial failures), optional intermediate callbacks are available.
## Primary Callbacks (Recommended)
### `onComplete`
Called when the entire identity verification flow completes successfully. This is the final success callback that contains all verification results.
**Default (combined document verification + face match):**
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"docVerificationResult": {
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"transactionId": "c8ad9541-c376-43f4-a84a-647526b7840e",
"card": { "country": "MALAYSIA", "type": "MyTentera", "isoAlpha3CountryCode": "MYS" },
"imageQualityResult": { "front": { ... }, "back": { ... } },
"idVerificationResult": { "front": { ... }, "back": { ... } },
"ocrResult": { "front": { "data": { "idNumber": { ... }, "name": { ... }, ... } }, "back": { ... } }
},
"faceMatchVerificationResult": {
"code": 1042,
"message": "Selfie photo matches with reference photo",
"score": 0.951598,
"transactionId": "da6b2f0b-e971-4232-bb84-6f840e821c6c"
},
"livenessVerificationResult": {
"score": 0.266861,
"liveImage": true,
"message": "Selfie photo is a live photo",
"code": 1043,
"transactionId": "fa581b84-6d90-9cdd-f073-18fd020be300",
"base64Image": "data:image/jpeg;base64,..."
}
}
```
**Color flash (smart liveness) response:**
When color flash is enabled, `livenessVerificationResult` includes a `livenessScores` array:
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"docVerificationResult": { ... },
"faceMatchVerificationResult": { ... },
"livenessVerificationResult": {
"score": 0.277815,
"liveImage": true,
"message": "Smart liveness success",
"code": 1043,
"transactionId": "2a58d634-d137-44c1-9527-cec61891e8df",
"base64Image": "data:image/jpeg;base64,...",
"attemptedTransactionIds": ["2a58d634-d137-44c1-9527-cec61891e8df"],
"livenessScores": [
{ "type": "passiveLiveness", "score": 0.171321 },
{ "type": "imageManipulation", "score": 0.093166 },
{ "type": "colorCaptcha", "score": 0.277815 }
]
}
}
**When `verifyDocumentOnEachSideCapture: true` (per-side verification):**
`docVerificationResult` is replaced with `docFrontSideVerificationResult` and `docBackSideVerificationResult` at the top level:
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"docFrontSideVerificationResult": {
"transactionId": "c8ad9541-c376-43f4-a84a-647526b7840e",
"card": { ... },
"ocrResult": { "front": { ... } },
"idVerificationResult": { "front": { ... } },
"imageQualityResult": { "front": { ... } }
},
"docBackSideVerificationResult": {
"transactionId": "ea263ea7-8bab-4d68-a960-3faa986900cf",
"ocrResult": { "back": { ... } },
"idVerificationResult": { "back": { ... } },
"imageQualityResult": { "back": { ... } }
},
"faceMatchVerificationResult": { ... },
"livenessVerificationResult": { ... }
}
```
**When `skipFaceMatch: true` (document verification only):**
Same structure as above (combined or per-side depending on config) but without `faceMatchVerificationResult` and `livenessVerificationResult`.
**`attemptedTransactionIds`:**
If there were multiple retry attempts for any operation, an `attemptedTransactionIds` array is included containing all transaction IDs from each attempt. This field is only present when there are more than 1 attempt.
```js
{
"docVerificationResult": {
"transactionId": "latest-txn-id",
"attemptedTransactionIds": ["first-attempt-txn-id", "second-attempt-txn-id", "latest-txn-id"],
...
},
"faceMatchVerificationResult": {
"transactionId": "latest-fm-txn-id",
"attemptedTransactionIds": ["first-fm-txn-id", "latest-fm-txn-id"],
...
}
}
```
---
### `onError`
Called when the verification flow fails and the user either exhausts all retry attempts or manually closes the modal or any other error occurs during the flow. Contains error details along with any successful verification results completed before the failure.
**Document verification error (e.g., invalid card, bad quality):**
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"transactionId": "4bffc031-d672-4481-9196-c3c29bff819e",
"errors": [
{ "code": "5023", "message": "Bad quality image", "status": 400 }
],
"warnings": [ ... ]
}
```
**Liveness error during face match — default (combined doc verification):**
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"docVerificationResult": {
"transactionId": "c8ad9541-c376-43f4-a84a-647526b7840e",
"card": { ... },
"ocrResult": { ... },
...
},
"errors": [
{
"score": -1,
"liveImage": false,
"message": "Detect Un-standardized Image Quality",
"code": 1051,
"transactionId": "d61f047d-3435-bf8c-2138-4b8a2fc05e87"
}
]
}
```
**Liveness error during face match — per-side verification (`verifyDocumentOnEachSideCapture: true`):**
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"docFrontSideVerificationResult": { ... },
"docBackSideVerificationResult": { ... },
"errors": [
{
"score": -1,
"liveImage": false,
"message": "Detect Un-standardized Image Quality",
"code": 1051,
"transactionId": "d61f047d-3435-bf8c-2138-4b8a2fc05e87"
}
]
}
```
**Per-side verification — front side success, back side failed:**
When `verifyDocumentOnEachSideCapture: true` and the front side succeeded but back side failed, only `docFrontSideVerificationResult` is included:
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"docFrontSideVerificationResult": {
"transactionId": "c8ad9541-c376-43f4-a84a-647526b7840e",
"card": { ... },
"ocrResult": { "front": { ... } },
...
},
"errors": [
{ "code": "5027", "message": "Front & Back side of the card not matching" }
]
}
```
**Face match error (after successful liveness):**
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"docVerificationResult": { ... },
"livenessVerificationResult": { ... },
"faceMatchVerificationResult": { ... },
"errors": [
{ "code": "1040", "message": "Selfie does not match the photo on your ID document" }
],
}
```
**Max retry exhausted:**
```js
{
"code": 71010,
"message": "Maximum retry attempts exhausted",
"verificationId": "...",
"docVerificationResult": { ... }
}
```
**User cancelled (closed modal without completing):**
```js
{
"code": 71008,
"message": "Identity verification cancelled by user",
"verificationId": "...",
"docVerificationResult": { ... }
}
```
**Frontend errors (camera, network, timeout, etc.):**
These errors occur during the frontend flow before or outside of API calls.
```js
// Network offline
{ "code": 40001, "message": "Unable to proceed, please check your connection" }
// Network timeout
{ "code": 40002, "message": "Unable to proceed due to network timeout, please check your connection" }
// Token expired / unauthorized
{ "code": 40003, "message": "Unable to proceed, ensure authorization method is correct and token is not expired" }
// Unknown error
{ "code": 50005, "message": "Unknown error occurred, please try again later" }
// Camera permission denied
{ "code": 70001, "message": "Unable to proceed, the functionality will not work without Camera permissions" }
// Face detection model download failed
{ "code": 70002, "message": "Unable to proceed, failed to download face landmark models" }
// Unsupported device/browser
{ "code": 70003, "message": "Unable to proceed, browser or device doesn't support this functionality" }
// Camera not found
{ "code": 70005, "message": "Unable to proceed, No camera device found" }
// Detection timeout
{ "code": 70007, "message": "Detection timed out" }
```
#### Frontend Error Codes Reference
| Code | Description |
| ----- | ------------------------------------ |
| 40001 | Network offline |
| 40002 | Network timeout |
| 40003 | Token expired or unauthorized |
| 50005 | Unknown error |
| 50006 | Color flash image upload error |
| 70001 | Camera permission denied |
| 70002 | Face detection model download failed |
| 70003 | Unsupported device/browser |
| 70004 | Video frame processing failed |
| 70005 | No camera device found |
| 70006 | Image capture failed |
| 70007 | Face detection timeout |
| 71008 | User cancelled (closed modal) |
| 70009 | Camera failed to start |
| 71010 | Max retry attempts exhausted |
| 70011 | Identity verification cancelled |
> **Note:** `docVerificationResult` (or `docFrontSideVerificationResult`/`docBackSideVerificationResult`) and `verificationId` are included in the error response only if document verification was completed (fully or partially) before the error occurred.
---
## Intermediate Callbacks (Optional)
These callbacks fire at specific stages during the flow. Use them when you need to react immediately to a specific event (e.g., show a custom UI, log analytics, or trigger external processes) without waiting for the full flow to complete.
### `onDocVerificationSuccess`
Called when document verification completes successfully (both sides when applicable). This is the default callback for combined verification mode.
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"transactionId": "c8ad9541-c376-43f4-a84a-647526b7840e",
"card": { ... },
"ocrResult": { ... },
"idVerificationResult": { ... },
"imageQualityResult": { ... }
}
```
### `onDocVerificationError`
Called when document verification fails in combined mode, or when back side verification fails in per-side mode.
```js
{
"transactionId": "...",
"errors": [{ "code": "5027", "message": "Front & Back side of the card not matching" }]
}
```
### `onDocFrontSideVerificationSuccess`
Called when the front side of the document is verified successfully. **Only fires when `verifyDocumentOnEachSideCapture: true`.**
```js
{
"verificationId": "9cf9db4c-a174-1ec6-b952-9099b83e4cc0",
"transactionId": "c8ad9541-c376-43f4-a84a-647526b7840e",
"card": { "country": "MALAYSIA", "type": "MyTentera", ... },
"ocrResult": { "front": { "data": { ... } } },
"idVerificationResult": { "front": { ... } },
"imageQualityResult": { "front": { ... } }
}
```
### `onDocFrontSideVerificationError`
Called when front side verification fails. **Only fires when `verifyDocumentOnEachSideCapture: true`.**
```js
{
"transactionId": "4bffc031-d672-4481-9196-c3c29bff819e",
"errors": [{ "code": "5023", "message": "Bad quality image" }]
}
```
### `onLivenessError`
Called each time liveness verification fails during the face match step. Fires on every failed liveness attempt (not just the final one). Useful for tracking individual liveness failures.
```js
{
"errors": [
{
"score": -1,
"liveImage": false,
"message": "Detect Un-standardized Image Quality",
"code": 1051,
"transactionId": "d61f047d-3435-bf8c-2138-4b8a2fc05e87"
}
]
}
```
### `onDocFaceMatchError`
Called when the face match API call fails (after successful liveness).
```js
{
"transactionId": "...",
"errors": [{ "code": "1040", "message": "Selfie does not match the photo on your ID document" }]
}
```
### `onSelfieCapture`
Called when a selfie is captured during the face match step. Receives the base64 image string.
```js
onSelfieCapture: (image) => {
// image is a base64 encoded JPEG string
console.log('Selfie captured', image);
};
```
### `onDocCapture`
Called when a document photo is captured. Receives the base64 image string.
```js
onDocCapture: (image) => {
// image is a base64 encoded JPEG string
console.log('Document captured', image);
};
```
---
## Key Fields Reference
| Field | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `verificationId` | Unique identifier for the verification session (derived from backend `groupId`) |
| `transactionId` | Transaction ID of the latest/successful attempt |
| `attemptedTransactionIds` | Array of transaction IDs from all attempts. Only present when there were multiple attempts (retries). |
| `card` | Detected document card details (country, type, etc.) |
| `ocrResult` | OCR extraction results (name, ID number, address, etc.) |
| `idVerificationResult` | Spoofing and landmark detection results |
| `imageQualityResult` | Image quality scores (blurriness, low light) |
| `docVerificationResult` | Complete document verification result (combined mode) |
| `docFrontSideVerificationResult` | Front side document verification result (per-side mode) |
| `docBackSideVerificationResult` | Back side document verification result (per-side mode) |
| `faceMatchVerificationResult` | Face match score and result |
| `faceMatchVerificationResult.warnings` | Array of warning objects with `code` and `message`. Present when the backend returns warnings (e.g., image extraction issues). |
| `livenessVerificationResult` | Liveness detection score and result |
| `livenessVerificationResult.livenessScores` | Array of individual scores per verification method (color flash only). Each entry has `type` and `score`. Types: `passiveLiveness`, `imageManipulation`, `colorCaptcha`. |
| `errors` | Array of error objects with `code`, `message`, and additional details |