Onboard a New Customer

The complete eKYC flow for a customer who has never held an account (NTB — new to bank): verify the document, verify the face, check for duplicates, then record the outcome. This is the production-ready flow, unlike Getting Started which only runs the spine.

The Flow

1.  Open a transaction
2.  Upload images              (3: front, back, selfie)
3.  Check card quality         → stop if verdict ≠ good
4.  Read the card              → check confidence
5.  Check card tampering       → stop if detected
6.  Check selfie quality       → stop if verdict ≠ good
7.  Check selfie liveness      → stop if is_live = false
8.  Match the face             → stop if unmatched
9.  Search for duplicates      → stop if already enrolled
10. Index the face             → only after approval
11. Close the transaction

Step 1 — Open a transaction

A transaction ties the individual steps into one auditable, verifiable session.

POST /v1/create_ekyc_transaction
{ "user_id": "user_00000001", "ref_id": "ref_00000001", "level": 0 }

Keep the ref_id. If you are using an SDK, pass the returned token to the app.

→ Create Transaction

Step 2 — Upload images

Three images, three calls, three image_id values. The labels must be exact: id_card.vn.national_id.front, id_card.vn.national_id.back, portrait.

→ Upload Image · Usage Recommendations

Step 3 — Card image quality

POST /v1/verify_id_card_sanity_sync

Pass both sides. The quality check is more accurate with the full card.

Verdict	What to do
good	Continue.
image1_glare / image2_glare	Ask for a retake of that side, away from direct light.
photocopied	Reject — this is a photocopy, not the real card.
multicard_image	Ask for a retake with one card per photo.
Anything else	Look it up in Verdict Definitions.

→ Verify ID Card Sanity

Step 4 — Read the card

POST /v1/read_id_card_info_sync

Do not take the values at face value. Check confidence_score against these thresholds:

Field group	Minimum
id, name, dob	>= 0.90
address, signature	>= 0.80

Anything below threshold goes to manual review — never auto-accept it.

If your app already scanned the QR string, Parse QR Info gives more reliable data than OCR.

→ Read ID Card Info

Step 5 — Card tampering

POST /v1/detect_id_card_tampering_sync

When verdict is alert, read details to see which signals fired. They need different handling:

Signal	Meaning
non_liveness	The card was photographed off a screen — likely fraud.
photo_tampered	The portrait on the card has been modified.
qr_info_not_match	The QR contradicts the printed surface.
card_expired	The card has expired — not fraud, but not usable either.

→ Detect ID Card Tampering

Steps 6–7 — Selfie quality and liveness

POST /v1/verify_portrait_sanity_sync
POST /v1/verify_face_liveness_sync

Run sanity first. A blurred or occluded selfie makes the liveness result untrustworthy.

is_live = false means the image was captured from a photo or a screen. Reject it, and do not allow unlimited retries.

→ Verify Face Sanity · Verify Face Liveness

Step 8 — Match the face

POST /v1/compare_faces_sync

Compare the selfie against the card front.

result	What to do
matched	Continue.
unmatched	Reject.
unsure	Send to manual review. Do not fold it into matched.

→ Compare Faces

Step 9 — Duplicate check

POST /v1/search_faces_sync

Search the enrolled collection for this face. A high-scoring hit means this person already has an account — or is using someone else's documents.

WARNING

Skipping this step leaves you open to one person opening many accounts. It is the only step that detects a repeat person, because every earlier step examines a single application in isolation.

→ Search Faces

Step 10 — Index the face

POST /v1/index_faces_sync

Call this only after approval. Indexing early pollutes the collection with rejected applications, which makes step 9 raise false duplicates for later customers.

→ Index Faces

Step 11 — Close the transaction

POST /v1/verify_transaction_key

→ Verify Transaction Key · Get Transaction

What Changes With an SDK

With the Mobile SDK, takeNID already bundles steps 2–5 and takeFaces bundles steps 2 and 6–7. Steps 8–10 still come from your backend, because no SDK performs duplicate detection.

Next Steps

• Read an ID Card Only — the short flow when face verification is not needed
• Testing — exercise this flow without a camera
• Error Codes — look up a failure at any step