KYC / eKYC / ODC — Kiến trúc triển khai
SWIFTNET_LINK + VNLH-VND SDK | ISO 20022 auth.012/013 | Ngân hàng Nhà nước Việt Nam
✅ Build status: 0 TypeScript errors |
Tests: 23/23 pass |
Nodes mới: 9 files (4 Node.js + 1 TypeScript + 1 EJS view + 3 cập nhật)
Luồng xử lý KYC end-to-end
1
NHTM/PSP nộp hồ sơ POST /kyc/submit → Bearer JWT xác thực → KYC Service
2
ODC Scan tài liệu đính kèm odcScannerService: OCR field extraction → integrity check → expiry validation → contract analysis
3
AML Risk Scoring FATF R.10/R.12 — PEP check, sanctions screening, country risk, document risk
4
Auto-status decision LOW risk + valid docs → APPROVED | HIGH/CRITICAL → IN_REVIEW | Sanctioned → REJECTED
5
Sinh ISO 20022 messages auth.012 (request) + auth.013 (response) XML được trả về tức thì
6
Gov-Chain anchoring recordHash neo lên VNLH ledger sau khi APPROVED (M1→M3)
Files đã tạo / cập nhật
SWIFTNET_LINK (Node.js)
| File | Loại | Chức năng |
|---|
| models/KycRecord.js |
Model |
Mongoose schema — hồ sơ KYC, ODC documents[], risk assessment, Gov-Chain anchor |
| services/odcScannerService.js |
Service |
ODC Scanner: OCR field extraction, integrity check, expiry validation, contract analysis, anti-tampering |
| services/kycService.js |
Service |
KYC Engine: submitKyc, getKycStatus, searchKyc, reviewKyc, computeRiskScore, buildAuth012/013 |
| routes/kycRoutes.js |
Router |
9 endpoints KYC/ODC (xem bảng endpoints bên dưới) |
| views/kycPortal.ejs |
View |
KYC/ODC Portal — UI nộp KYC, quét tài liệu, phân tích hợp đồng, tra cứu |
| server.js updated |
Server |
Mount kycRoutes tại BASE/kyc + comment endpoints đầy đủ |
| routes/sdkGatewayRoutes.js updated |
Proxy |
Thêm 5 KYC entries vào ROUTE_MAP để proxy sang ISO20022 GW |
| .env.example updated |
Config |
Thêm 8 biến KYC_*: OCR engine, sanctions URL, validity years, webhook |
VNLH-VND SDK (TypeScript)
| File | Loại | Chức năng |
|---|
| src/vnlh/kyc-engine.ts |
Engine |
KycSubmitInput, OdcScanResult, processKycSubmit(), scanOdcDocument(), computeKycRisk(), buildAuth012/013Xml() |
| src/vnlh/index.ts updated |
Export |
Export * from kyc-engine |
| src/gateway/vnlh-router.ts updated |
Router |
4 KYC endpoints: /kyc/submit, /kyc/scan, /kyc/contract, /kyc/schemas |
| src/index.ts updated |
Server |
Thêm log startup cho KYC endpoints |
Endpoint Map đầy đủ
SWIFTNET_LINK — /SWIFT/kyc/*
| Method | Path | Auth | Mô tả |
|---|
| POST | /SWIFT/kyc/submit | Bearer JWT | Nộp hồ sơ KYC đầy đủ → trả auth.012 + auth.013 XML |
| GET | /SWIFT/kyc/status/:kycId | Bearer JWT | Tra cứu trạng thái KYC + auth.013 XML |
| POST | /SWIFT/kyc/scan | Bearer JWT | ODC quét tài liệu đơn lẻ |
| POST | /SWIFT/kyc/scan/batch | Bearer JWT | ODC quét nhiều tài liệu (max 20) |
| POST | /SWIFT/kyc/verify-contract | Bearer JWT | Phân tích hợp đồng / văn bản pháp lý |
| GET | /SWIFT/kyc/search | Session Admin | Tìm kiếm hồ sơ KYC |
| PUT | /SWIFT/kyc/review/:kycId | Session Admin | Duyệt/từ chối KYC |
| GET | /SWIFT/kyc/stats | Session Admin | Thống kê tổng hợp |
| GET | /SWIFT/kyc/schemas | Public | Danh sách loại tài liệu ODC hỗ trợ |
| GET | /SWIFT/kyc-portal | Public | KYC/ODC Web Portal (EJS) |
VNLH-VND SDK (TypeScript) — /api/v1/iso20022/vnlh/kyc/*
| Method | Path | ISO 20022 | Mô tả |
|---|
| POST | /vnlh/kyc/submit | auth.012.001.02 | KYC submission + ODC scan + risk scoring |
| POST | /vnlh/kyc/scan | — | ODC document scan đơn lẻ |
| POST | /vnlh/kyc/contract | — | Contract/legal document analysis |
| GET | /vnlh/kyc/schemas | — | ODC docType registry + legal refs |
ODC — Loại tài liệu hỗ trợ
| docType | Tài liệu | OCR Fields | Hiệu lực |
|---|
NATIONAL_ID | CMND/CCCD Việt Nam | idNumber, fullName, dateOfBirth, gender, address, issueDate, expiryDate, MRZ | 15 năm |
PASSPORT | Hộ chiếu | passportNo, fullName, dateOfBirth, nationality, issueDate, expiryDate, MRZ | 10 năm |
DRIVING_LIC | Bằng lái xe | licenseNo, fullName, dateOfBirth, licenseClass, expiryDate | 10 năm |
BUSINESS_REG | Đăng ký kinh doanh | taxCode, companyName, legalRepresentative, registrationDate, businessAddress | Không hết hạn |
CONTRACT | Hợp đồng tín dụng/dịch vụ | contractNo, parties, effectiveDate, expiryDate, value, currency, detectedClauses | Per contract |
LEGAL_DOC | Văn bản pháp lý | docNumber, docType, issuer, issuedDate, effectiveDate, subject | Per document |
FINANCIAL_STMT | Báo cáo tài chính | reportingPeriod, entityName, totalAssets, netRevenue, auditorName | Per period |
AML Risk Scoring
| Rule | Điểm cộng | Flag | Chuẩn pháp lý |
|---|
| Quốc tịch FATF Black List (KP, IR, SY) | +50 | FATF_BLACK_LIST | FATF Updated Statement |
| Quốc tịch FATF Grey List | +25 | FATF_GREY_LIST | FATF Increased Monitoring |
| PEP suspected (keyword match) | +25 | PEP_SUSPECTED | FATF Recommendation 12 |
| Thiếu tài liệu định danh bắt buộc | +20 | MISSING_ID_DOCUMENT | Luật PCRT 2022 — Điều 11 |
| Tài liệu INVALID/EXPIRED | +10 mỗi doc | INVALID_DOCUMENTS | TT09/2023/TT-NHNN |
| Tài liệu TAMPERED | +60 | TAMPERED_DOCUMENT | Điều 20 Luật GDĐT 2023 |
| Sanctions hit (OFAC/UN/EU) | +50 | SANCTIONS_HIT | FATF Recommendation 6 |
| Risk Score | Risk Level | Hành động tự động |
|---|
| 0–29 | LOW | APPROVED tự động (nếu docs VALID) |
| 30–59 | MEDIUM | PENDING — cần duyệt |
| 60–79 | HIGH | IN_REVIEW — EDD required |
| 80–100 | CRITICAL | REJECTED tự động |
Contract Analyzer — Risk Clauses
| Code | Mô tả | Mức độ |
|---|
PENALTY_RATE | Lãi suất phạt bất thường cao | MEDIUM |
VOID_CLAUSE | Điều khoản vô hiệu hoá hợp đồng | HIGH |
CONFIDENTIALITY | Bảo mật tuyệt đối (cản trở khiếu nại) | MEDIUM |
IRREVOCABLE_POA | Ủy quyền không hủy ngang | HIGH |
EXTRAJUDICIAL | Xử lý tài sản không qua tòa án | HIGH |
HIGH_INTEREST | Lãi suất > ngưỡng hợp lý | MEDIUM |
Khung pháp lý áp dụng
| Chuẩn / Văn bản | Nội dung áp dụng |
|---|
| ISO 20022 auth.012.001.02 | MoneyLaunderingRiskReport — KYC Request message |
| ISO 20022 auth.013.001.02 | InvestigationRequestResponse — KYC Response message |
| Luật PCRT 2022 (Luật số 14/2022/QH15) | Nhận biết khách hàng, đánh giá rủi ro, lưu trữ hồ sơ |
| Nghị định 19/2023/NĐ-CP | Hướng dẫn Luật PCRT 2022 — CDD thực hành |
| Thông tư 09/2023/TT-NHNN | eKYC điện tử — yêu cầu kỹ thuật |
| Thông tư 16/2021/TT-NHNN | Nhận biết khách hàng điện tử tại ngân hàng |
| FATF Recommendation 10 | Customer Due Diligence (CDD) |
| FATF Recommendation 12 | Politically Exposed Persons (PEP) |
| Nghị định 13/2023/NĐ-CP | Bảo vệ dữ liệu cá nhân — mask PII trong log |
| Điều 20 Luật GDĐT 2023 | Gov-Chain blockHash làm bằng chứng điện tử |
| Bộ luật Dân sự 2015 — Điều 385-408 | Phân tích hiệu lực điều khoản hợp đồng |