Onboard một khách hàng mới

Luồng eKYC đầy đủ cho một khách hàng chưa từng có tài khoản (NTB — new to bank): xác minh giấy tờ, xác minh khuôn mặt, kiểm tra trùng lặp, rồi ghi nhận kết quả. Đây là luồng sẵn sàng cho production, khác với Bắt đầu nhanh vốn chỉ chạy phần xương sống.

Luồng xử lý

1.  Mở một giao dịch
2.  Tải ảnh lên              (3 ảnh: mặt trước, mặt sau, selfie)
3.  Kiểm tra chất lượng thẻ  → dừng nếu verdict ≠ good
4.  Đọc thông tin thẻ        → kiểm tra độ tin cậy
5.  Kiểm tra giả mạo thẻ     → dừng nếu phát hiện
6.  Kiểm tra chất lượng selfie → dừng nếu verdict ≠ good
7.  Kiểm tra liveness selfie → dừng nếu is_live = false
8.  So khớp khuôn mặt        → dừng nếu unmatched
9.  Tìm kiếm trùng lặp       → dừng nếu đã đăng ký
10. Lập chỉ mục khuôn mặt    → chỉ sau khi được duyệt
11. Đóng giao dịch

Bước 1 — Mở một giao dịch

Một giao dịch gắn kết các bước riêng lẻ thành một phiên có thể kiểm toán, có thể xác minh.

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

Giữ lại ref_id. Nếu bạn dùng một SDK, hãy truyền token trả về cho ứng dụng.

→ Tạo giao dịch

Bước 2 — Tải ảnh lên

Ba ảnh, ba lệnh gọi, ba giá trị image_id. Nhãn phải chính xác: id_card.vn.national_id.front, id_card.vn.national_id.back, portrait.

→ Tải ảnh lên · Khuyến nghị sử dụng

Bước 3 — Chất lượng ảnh thẻ

POST /v1/verify_id_card_sanity_sync

Truyền cả hai mặt. Kiểm tra chất lượng chính xác hơn khi có đủ cả thẻ.

Verdict	Cần làm gì
good	Tiếp tục.
image1_glare / image2_glare	Yêu cầu chụp lại mặt đó, tránh ánh sáng chiếu trực tiếp.
photocopied	Từ chối — đây là bản photocopy, không phải thẻ thật.
multicard_image	Yêu cầu chụp lại, mỗi ảnh chỉ một thẻ.
Giá trị khác	Tra cứu tại Định nghĩa kết luận.

→ Xác minh ID Card Sanity

Bước 4 — Đọc thông tin thẻ

POST /v1/read_id_card_info_sync

Đừng chấp nhận các giá trị mà không kiểm tra. Đối chiếu confidence_score với các ngưỡng sau:

Nhóm trường	Tối thiểu
id, name, dob	>= 0.90
address, signature	>= 0.80

Bất kỳ giá trị nào dưới ngưỡng đều chuyển sang xét duyệt thủ công — không bao giờ tự động chấp nhận.

Nếu ứng dụng của bạn đã quét chuỗi QR, Phân tích thông tin QR cho dữ liệu đáng tin cậy hơn OCR.

→ Đọc thông tin thẻ ID

Bước 5 — Giả mạo thẻ

POST /v1/detect_id_card_tampering_sync

Khi verdict là alert, đọc details để xem tín hiệu nào đã kích hoạt. Mỗi tín hiệu cần cách xử lý khác nhau:

Tín hiệu	Ý nghĩa
non_liveness	Thẻ được chụp lại từ một màn hình — khả năng cao là gian lận.
photo_tampered	Ảnh chân dung trên thẻ đã bị chỉnh sửa.
qr_info_not_match	QR mâu thuẫn với bề mặt in.
card_expired	Thẻ đã hết hạn — không phải gian lận, nhưng cũng không dùng được.

→ Phát hiện giả mạo thẻ ID

Bước 6–7 — Chất lượng và liveness của selfie

POST /v1/verify_portrait_sanity_sync
POST /v1/verify_face_liveness_sync

Chạy kiểm tra sanity trước. Một ảnh selfie bị mờ hoặc bị che khiến kết quả liveness không đáng tin cậy.

is_live = false nghĩa là ảnh được chụp từ một tấm ảnh hoặc một màn hình. Hãy từ chối, và không cho phép thử lại vô hạn.

→ Xác minh sanity khuôn mặt · Xác minh liveness khuôn mặt

Bước 8 — So khớp khuôn mặt

POST /v1/compare_faces_sync

So sánh ảnh selfie với mặt trước thẻ.

result	Cần làm gì
matched	Tiếp tục.
unmatched	Từ chối.
unsure	Chuyển sang xét duyệt thủ công. Không gộp vào matched.

→ So sánh khuôn mặt

Bước 9 — Kiểm tra trùng lặp

POST /v1/search_faces_sync

Tìm kiếm khuôn mặt này trong collection đã đăng ký. Một kết quả khớp với điểm số cao nghĩa là người này đã có tài khoản — hoặc đang dùng giấy tờ của người khác.

WARNING

Bỏ qua bước này khiến bạn dễ bị một người mở nhiều tài khoản. Đây là bước duy nhất phát hiện người dùng lặp lại, vì mọi bước trước đó đều chỉ xem xét một hồ sơ đơn lẻ, tách biệt.

→ Tìm kiếm khuôn mặt

Bước 10 — Lập chỉ mục khuôn mặt

POST /v1/index_faces_sync

Chỉ gọi bước này sau khi được duyệt. Lập chỉ mục quá sớm sẽ làm ô nhiễm collection bằng các hồ sơ bị từ chối, khiến bước 9 báo trùng lặp giả cho các khách hàng sau này.

→ Lập chỉ mục khuôn mặt

Bước 11 — Đóng giao dịch

POST /v1/verify_transaction_key

→ Xác minh khóa xác thực giao dịch · Lấy giao dịch

Điều gì thay đổi khi dùng SDK

Với Mobile SDK, takeNID đã bao gồm sẵn các bước 2–5 và takeFaces bao gồm sẵn các bước 2 và 6–7. Các bước 8–10 vẫn do backend của bạn thực hiện, vì không SDK nào tự phát hiện trùng lặp.

Bước tiếp theo

• Chỉ đọc thẻ ID — luồng ngắn khi không cần xác minh khuôn mặt
• Kiểm thử — chạy thử luồng này mà không cần camera
• Mã lỗi — tra cứu lỗi ở bất kỳ bước nào