> For the complete documentation index, see [llms.txt](https://developer.fraudcheck.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.fraudcheck.co.za/identity/biometric-identity-verification.md). # Identity Verification - Enhanced with Liveness Identity Verification Enhanced with Liveness confirms a consumer's identity against official records, retrieves an official ID photograph, and for a **matched identity** automatically starts a biometric liveness capture. The consumer completes a short selfie-based liveness check through a secure link, and the service compares the selfie against the official photograph to confirm a live, matching person submitted the request. Two variants are available: **Registry Onfile**, for fast lookups against recent snapshot records, and **Registry Online**, which queries live DHA records in real time. An optional automatic failover can retry the other variant if the first finds no record for the submitted ID number. ## When to use this Use this service to: * Verify a consumer's identity and retrieve an official ID photograph in one call * Binding Identity Verification by confirm the person completing an onboarding is the same live person as the official identity record ## How it works Submit an ID number, first name, and surname in a single POST request, along with consent confirmation. The service validates the identity against the selected registry variant (`liveDHA: false` uses Registry Onfile; `liveDHA: true` uses Registry Online) and returns a decision code (`ACCEPT`, `REJECT`, or `FAIL`) along with the matched record. If the identity is found, a biometric liveness capture session is automatically created: * The secure capture link is returned as `capture_url` in the response. * If `sendCaptureSms` is `true`, the link is also sent by SMS to `CellNo`. * The response `code` is `PENDING` until the consumer completes the liveness check and a face-match result is available. If the identity is **not found**, no capture session is created and no SMS is sent there is no official photograph to match a selfie against, so the response stays `FAIL`. Poll `GET /idv/kyc/photo/results/{transaction_id}` to retrieve the final result once the consumer has completed the capture link. ### Automatic failover Set `enableFailover: true` to automatically retry the **other** registry variant if the one you selected returns a clean "no record found" result. This applies only when a record genuinely isn't found under that variant. | Property | Value | | --------------------- | ---------------------------------------------------------------------------------------------------- | | Response type | `Synchronous` (initial call), then poll for the capture/liveness outcome. **Webhook also available** | | Typical response time | 2–5s for the initial call | | Result retrieval | Returned inline; final outcome via `GET /idv/kyc/photo/results/{transaction_id}` | | Consent required | `Yes` | | Region | South Africa | *** ## Embedding capture in your own app By default, hand the consumer `capture_url` (directly, or by SMS via `sendCaptureSms`) and let them complete the liveness check on Fraudcheck's hosted capture page. If you'd rather embed the capture flow inside your own app instead of redirecting to that hosted page, use the `@fraudcheck/capture-flow` React SDK. ### Install ```bash npm install @fraudcheck/capture-flow ``` ### Usage ```jsx import { CaptureFlow } from '@fraudcheck/capture-flow' import '@fraudcheck/capture-flow/style.css' function VerifyPage() { return ( { // Session finished on the client. Treat this as a signal to start polling, // not as the final result - see the hint below. }} onError={(err) => { // Session bootstrap failed, or the final status update failed after retries }} onStepChange={({ step, index, total }) => { // 'welcome' | 'fields' | 'document' | 'liveness' }} /> ) } ``` `transactionId` is the `transaction_id` (same value as `capture_transaction_id`) returned by `POST /idv/kyc/photo/verify` - the SDK never creates or reads a transaction ID itself, so you still create it exactly as described above. All callbacks are optional and fire alongside the SDK's own UI, never instead of it. `showCompletionScreen` (default `true`) is the one exception - set it `false` to suppress just the final "done" screen and show your own instead, driven by `onComplete`. Every other screen in the flow is unaffected. {% hint style="info" %} `onComplete` only means the capture session finished on the client. The backend is the source of truth: poll `GET /idv/kyc/photo/results/{transaction_id}` for the authoritative `code`, `liveness`, and `face_match` outcome rather than building UI around the `results` passed to `onComplete`. {% endhint %} *** ## Authentication ```http Authorization: Bearer {your_access_token} ``` *** ## Endpoints ```http POST /idv/kyc/photo/verify GET /idv/kyc/photo/results/{transaction_id} ``` ## Request ### Headers | Header | Required | Value | | --------------- | -------- | ------------------ | | `Authorization` | Yes | `Bearer {token}` | | `Content-Type` | Yes | `application/json` | ### Body parameters | Field | Type | Required | Default | Description | | ------------------------------ | ------- | ---------------------------------- | ------- | --------------------------------------------------------------------------------------------------- | | `IdentityNo` | string | Yes | | 13-digit South African ID number | | `FirstName` | string | Yes | | Consumer's first name | | `LastName` | string | Yes | | Consumer's surname | | `CellNo` | string | Only if `sendCaptureSms` is `true` | | Consumer's mobile number, for sending the capture link by SMS | | `ConsentObtainedByDataSubject` | boolean | Yes | | Must be `true`. Confirms POPIA consent. | | `lenientThreshold` | number | No | `0.95` | Given-name match threshold between `0.0` and `1.0`. See [Matching behaviour](#matching-behaviour). | | `liveDHA` | boolean | No | `false` | `false` uses Registry Onfile; `true` uses Registry Online | | `sendCaptureSms` | boolean | No | `false` | Send the liveness capture link to `CellNo` by SMS. The link is returned in the response either way. | | `enableFailover` | boolean | No | `false` | Automatically retry the other registry variant if the first returns no record | ### Example request ```json { "IdentityNo": "*************", "FirstName": "John", "LastName": "Smith", "CellNo": "0821234567", "ConsentObtainedByDataSubject": true, "liveDHA": false, "sendCaptureSms": true, "enableFailover": true } ``` *** ## Matching behaviour `lenientThreshold` controls how strictly the submitted **given name** is matched against the official record. It does **not** relax surname matching: * **Given name** matched against `lenientThreshold` (defaults to `0.95`). A lower value tolerates spelling variance and given-name ordering. * **Surname** always requires **at least 95% similarity**, regardless of how low `lenientThreshold` is set. * **Swap detection**: if the submitted given name matches the record's surname and the submitted surname matches the record's given name, the request is treated as the same identity with the fields reversed, and is accepted. *** ## Response ### Initial response (`POST /idv/kyc/photo/verify`) | Field | Type | Description | | ---------------------------- | ------- | ------------------------------------------------------------------------------------- | | `success` | boolean | `true` if the identity was found by either registry variant | | `transaction_id` | string | Unique request identifier. A `failover` suffix indicates the other variant responded. | | `code` | string | `ACCEPT`, `REJECT`, `FAIL`, or `PENDING` while liveness/face-match is outstanding | | `message` | string | Human-readable explanation of the result | | `request` | object | Details submitted in the request | | `record` | object | Identity record returned by the registry | | `outcome` | object | Field-level match results (see below) | | `liveness` | string | `pending` once a capture session is created; otherwise `null` | | `face_match` | string | `pending` once a capture session is created; otherwise `null` | | `capture_transaction_id` | string | Same as `transaction_id`, present only when a capture session was created | | `capture_url` | string | Secure link for the consumer to complete the liveness check | | `capture_session_expires_at` | string | Expiry timestamp for `capture_url` | | `sms_sent` | boolean | `true` if the capture link was sent by SMS | | `sms_error` | string | Reason the SMS could not be sent, if applicable | ### `outcome` object fields | Field | Type | Description | | ----------------------------- | ------- | ----------------------------------------------------------------------- | | `id_found` | boolean | `false` only when no registry variant has a record for the submitted ID | | `id_matched` | boolean | The submitted ID number matches the returned record | | `first_name_matched` | boolean | The submitted given name cleared `lenientThreshold` | | `first_name_similarity_score` | number | Jaro-Winkler similarity score for the given name comparison | | `first_name_threshold` | number | The threshold actually applied | | `last_name_matched` | boolean | The submitted surname matches the record (always ≥ 95% similarity) | | `last_name_similarity_score` | number | Jaro-Winkler similarity score for the surname comparison | | `last_name_threshold` | number | The threshold actually applied to surname matching (always ≥ 0.95) | | `names_swapped` | boolean | `true` when the given name and surname appear entered in reverse order | | `dob_matched` | boolean | Date of birth parsed from the ID number matches the record | | `id_valid` | string | Result of the SA ID checksum validation | ### Example: identity found, capture session started ```json { "success": true, "transaction_id": "5635ae839b4a084bce2fffc7976d009d", "code": "PENDING", "message": "Identity verification in progress - awaiting liveness capture and face match.", "request": { "id_number": "*************", "first_name": "John", "last_name": "Smith", "date_of_birth": "1995-09-03" }, "record": { "id_number": "*************", "first_names": "JOHN", "surname": "SMITH", "date_of_birth": "1995-09-03", "deceased_status": "Alive", "deceased_date": null, "id_book_issued_date": "", "id_card_issued": true, "id_card_date": null }, "outcome": { "id_found": true, "id_matched": true, "first_name_matched": true, "first_name_similarity_score": 1.0, "first_name_threshold": 0.95, "last_name_matched": true, "last_name_similarity_score": 1.0, "last_name_threshold": 0.95, "names_swapped": false, "dob_matched": true, "id_valid": "Identity passed checksum" }, "liveness": "pending", "face_match": "pending", "capture_transaction_id": "5635ae839b4a084bce2fffc7976d009d", "capture_url": "https://capture.example.fraudcheck.co.za/5635ae839b4a084bce2fffc7976d009d", "capture_session_expires_at": "2026-09-15T08:58:40.045716", "sms_sent": true, "sms_error": null } ``` ### Example: identity not found No capture session is created and no SMS is sent — `code` stays `FAIL`. ```json { "success": false, "transaction_id": "58a4cb34c7fcc37b5b38508dc94df298", "code": "FAIL", "message": "No identity record was found for this ID number.", "request": { "id_number": "*************", "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1999-11-15" }, "record": { "id_number": "*************", "first_names": "", "surname": "", "date_of_birth": "", "deceased_status": "Unknown", "deceased_date": null, "id_book_issued_date": "", "id_card_issued": false, "id_card_date": null }, "outcome": { "id_found": false, "id_matched": false, "first_name_matched": false, "first_name_similarity_score": 0.0, "first_name_threshold": 0.95, "last_name_matched": false, "last_name_similarity_score": 0.0, "last_name_threshold": 0.95, "names_swapped": false, "dob_matched": false, "id_valid": "Identity passed checksum" }, "liveness": null, "face_match": null, "capture_transaction_id": null, "capture_url": null, "capture_session_expires_at": null, "sms_sent": false, "sms_error": null } ``` ### Example: found via automatic failover Submitted with `liveDHA: false, enableFailover: true`. Registry Onfile had no record, so the service automatically retried Registry Online, which found the identity. Note the `failover` suffix on `transaction_id`. ```json { "success": true, "transaction_id": "793129b2e4c2147fcff0c8fd3d35df58failover", "code": "PENDING", "message": "Identity verification in progress - awaiting liveness capture and face match.", "request": { "id_number": "*************", "first_name": "Warren", "last_name": "Brocklebank", "date_of_birth": "1999-11-15" }, "record": { "id_number": "*************", "first_names": "WARREN COLIN", "surname": "BROCKLEBANK", "date_of_birth": "", "deceased_status": "Alive", "deceased_date": null, "id_book_issued_date": "20240524", "id_card_issued": true, "id_card_date": null }, "outcome": { "id_found": true, "id_matched": true, "first_name_matched": true, "first_name_similarity_score": 1.0, "first_name_threshold": 0.95, "last_name_matched": true, "last_name_similarity_score": 1.0, "last_name_threshold": 0.95, "names_swapped": false, "dob_matched": false, "id_valid": "Identity passed checksum" }, "liveness": "pending", "face_match": "pending", "capture_transaction_id": "793129b2e4c2147fcff0c8fd3d35df58failover", "capture_url": "https://capture.example.fraudcheck.co.za/793129b2e4c2147fcff0c8fd3d35df58failover", "capture_session_expires_at": "2026-09-16T06:05:09.385497", "sms_sent": true, "sms_error": null } ``` *** ## Retrieving the final result Poll this endpoint after receiving `code: PENDING` to check whether the consumer has completed the liveness capture and what the final decision is. ```http GET /idv/kyc/photo/results/{transaction_id} Authorization: Bearer {your_access_token} ``` ### Path parameter | Parameter | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------------------- | | `transaction_id` | string | Yes | The `transaction_id` returned by `POST /idv/kyc/photo/verify` | ### Response fields | Field | Type | Description | | ----------------- | -------------- | ----------------------------------------------------------------------------- | | `success` | boolean | `true` if the transaction was found | | `transaction_id` | string | The transaction ID requested | | `code` | string | `ACCEPT`, `REJECT`, `REVIEW`, `FAIL`, or `PENDING` | | `message` | string | Human-readable explanation of the result | | `request` | object | `id_number`, `first_name`, `last_name` as submitted | | `record` | object | Identity record returned by the registry | | `outcome` | object | Same fields as the initial response's `outcome`, plus `liveness`/`face_match` | | `session_id` | string \| null | Capture session identifier, if a capture session exists | | `session_details` | object \| null | Capture session status, type, link, and timestamps | | `dha_image` | string \| null | Base64-encoded official identity photograph, where available | | `selfie_image` | string \| null | Base64-encoded selfie captured during the liveness check, where available | ### Final decision codes | Code | Meaning | | --------- | ---------------------------------------------------------------------------------- | | `ACCEPT` | Identity verified, liveness passed, and the selfie matched the official photograph | | `REJECT` | Identity details, liveness, or the face match did not pass | | `REVIEW` | The result requires manual review, for example an inconclusive face match | | `FAIL` | No identity record was found, or verification could not be completed | | `PENDING` | The consumer has not yet completed the liveness capture | ### Example response (accepted) ```json { "success": true, "transaction_id": "5635ae839b4a084bce2fffc7976d009d", "code": "ACCEPT", "message": "Identity verified, liveness passed, and the submitted selfie matches the official photograph.", "request": { "id_number": "*************", "first_name": "John", "last_name": "Smith" }, "record": { "id_number": "*************", "first_names": "JOHN", "surname": "SMITH", "date_of_birth": "1995-09-03", "deceased_status": "Alive", "deceased_date": null, "id_book_issued_date": "", "id_card_issued": true, "id_card_date": null }, "outcome": { "id_found": true, "id_matched": true, "first_name_matched": true, "first_name_similarity_score": 1.0, "first_name_threshold": 0.95, "last_name_matched": true, "last_name_similarity_score": 1.0, "last_name_threshold": 0.95, "names_swapped": false, "dob_matched": true, "id_valid": "Identity passed checksum", "liveness": "accept", "face_match": "accept" }, "session_id": "5635ae839b4a084bce2fffc7976d009d", "session_details": { "status": "completed", "capture_type": "dha_and_liveness", "liveness_type": "passive", "capture_url": "https://capture.example.fraudcheck.co.za/5635ae839b4a084bce2fffc7976d009d", "expires_at": "2026-09-16T08:58:40.045716", "created_at": "2026-09-15T08:58:40.045716", "updated_at": "2026-09-15T09:02:11.113221" }, "dha_image": "base64_encoded_photo_data...", "selfie_image": "base64_encoded_photo_data..." } ``` ### Example response (still pending) ```json { "success": true, "transaction_id": "5635ae839b4a084bce2fffc7976d009d", "code": "PENDING", "message": "Identity verification in progress - awaiting liveness capture and face match.", "request": { "id_number": "*************", "first_name": "John", "last_name": "Smith" }, "record": { "...": "..." }, "outcome": { "...": "...", "liveness": "pending", "face_match": "pending" }, "session_id": "5635ae839b4a084bce2fffc7976d009d", "session_details": { "status": "created", "capture_type": "dha_and_liveness", "liveness_type": "passive", "capture_url": "https://capture.example.fraudcheck.co.za/5635ae839b4a084bce2fffc7976d009d", "expires_at": "2026-09-16T08:58:40.045716", "created_at": "2026-09-15T08:58:40.045716", "updated_at": "2026-09-15T08:58:40.045716" }, "dha_image": null, "selfie_image": null } ``` *** ## Errors | HTTP | Code | Meaning | Action | | ---- | --------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | 422 | `invalid_input` | Required field missing, consent not confirmed, or `CellNo` missing when `sendCaptureSms` is `true` | See `details.field` | | 401 | `unauthorized` | Token missing or expired | Refresh your access token | | 403 | `forbidden` | Account lacks access to this service | Contact your account manager | | 404 | `not_found` | `transaction_id` not found, or does not belong to your account | Confirm the transaction ID from the original request | | 500 | `server_error` | Unexpected error | Retry; contact support if persistent | {% hint style="info" %} A negative outcome is not an error. An ID that is not on file, a failed liveness check, or a mismatched selfie all return HTTP `200` with a decision code such as `FAIL`, `REJECT`, or `REVIEW`. This means the request was processed successfully, but the identity could not be accepted. {% endhint %} *** ## Code examples {% tabs %} {% tab title="cURL" %} ```bash BASE_URL="https://consumer-service-api.fraudcheckonline.co.za/consumer-service" curl -X POST "$BASE_URL/idv/kyc/photo/verify" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "IdentityNo": "*************", "FirstName": "John", "LastName": "Smith", "CellNo": "0821234567", "ConsentObtainedByDataSubject": true, "liveDHA": false, "sendCaptureSms": true, "enableFailover": true }' curl -X GET "$BASE_URL/idv/kyc/photo/results/$TRANSACTION_ID" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` {% endtab %} {% tab title="Python" %} ```python import requests BASE_URL = "https://consumer-service-api.fraudcheckonline.co.za/consumer-service" response = requests.post( f"{BASE_URL}/idv/kyc/photo/verify", headers={ "Authorization": f"Bearer {access_token}", "Content-Type": "application/json", }, json={ "IdentityNo": "*************", "FirstName": "John", "LastName": "Smith", "CellNo": "0821234567", "ConsentObtainedByDataSubject": True, "liveDHA": False, "sendCaptureSms": True, "enableFailover": True, }, ) result = response.json() print("Decision:", result.get("code")) if result.get("code") == "PENDING": print("Capture link:", result.get("capture_url")) transaction_id = result["transaction_id"] status_response = requests.get( f"{BASE_URL}/idv/kyc/photo/results/{transaction_id}", headers={"Authorization": f"Bearer {access_token}"}, ) final = status_response.json() print("Final decision:", final.get("code")) ``` {% endtab %} {% tab title="JavaScript (Node.js)" %} ```javascript const BASE_URL = "https://consumer-service-api.fraudcheckonline.co.za/consumer-service"; const response = await fetch(`${BASE_URL}/idv/kyc/photo/verify`, { method: "POST", headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json", }, body: JSON.stringify({ IdentityNo: "*************", FirstName: "John", LastName: "Smith", CellNo: "0821234567", ConsentObtainedByDataSubject: true, liveDHA: false, sendCaptureSms: true, enableFailover: true, }), }); const result = await response.json(); console.log("Decision:", result.code); if (result.code === "PENDING") { console.log("Capture link:", result.capture_url); const statusResponse = await fetch( `${BASE_URL}/idv/kyc/photo/results/${result.transaction_id}`, { headers: { Authorization: `Bearer ${accessToken}` } } ); const final = await statusResponse.json(); console.log("Final decision:", final.code); } ``` {% endtab %} {% endtabs %} *** ## Compliance & consent * Obtain explicit consent from the data subject before submitting a request. * Set `ConsentObtainedByDataSubject` to `true` to confirm consent has been captured. * Retain proof of consent, and any retrieved photographs, in line with POPIA requirements. *** ## FAQ
What's the difference between the two registry variants? Registry Onfile (`liveDHA: false`) uses recent snapshot data. Registry Online (`liveDHA: true`) queries live DHA records in real time.
What happens if I don't set sendCaptureSms? The liveness capture session is still created and `capture_url` is still returned in the response. you're just responsible for sharing the link with the consumer yourself instead of Fraudcheck texting it.
Why didn't I get a capture link? A capture link is only created when the identity is actually found. If `code` is `FAIL` and `outcome.id_found` is `false`, there is no official photograph to run a liveness/face-match check against, so no session is created and no SMS is sent, even if `sendCaptureSms` was `true`.
What does enableFailover actually retry? Only a clean "no record found" result from the registry variant you selected. If the request itself fails (a timeout or service error), the endpoint still returns an error response the same way it would with `enableFailover` off.
How do I know if the failover variant responded instead of my selected one? Check `transaction_id.` a `failover` suffix means the other registry variant found the record after your selected one returned no result.
Can lenientThreshold cause an incorrect surname to be accepted? No. `lenientThreshold` only relaxes given-name matching. Surname matching always requires at least 95% similarity, regardless of how low `lenientThreshold` is set.
What client timeout should I configure? Up to 30 seconds for the initial `POST` call. The liveness capture itself is asynchronous — poll `GET /idv/kyc/photo/results/{transaction_id}` rather than waiting on the initial request.
*** ## Changelog | Date | Version | Change | | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 2026-09-15 | v1.1 | Added `enableFailover` for automatic retry against the other registry variant on a clean not-found. Liveness capture / SMS are no longer triggered when the identity isn't found — a not-found result now stays `FAIL` instead of moving to `PENDING`. | | 2026-08-31 | v1.0 | Initial release: identity verification against two registry variants, automatic liveness capture session, optional SMS delivery of the capture link. |