SBV ISO 20022 API Gateway — Đặc tả Kiến trúc Kỹ thuật
Phiên bản: 1.0.0
Cơ quan chủ quản: Ngân hàng Nhà nước Việt Nam (SBV)
Mục tiêu: Nâng cấp cổng kết nối API từ chuẩn IBPS nội địa → ISO 20022 hoàn chỉnh
Tham chiếu: VNLH-VND Roadmap, ASEAN mBridge Spec, HP 2013
1. Bối cảnh và Mục tiêu
1.1 Trạng thái hiện tại (AS-IS)
- Cổng liên ngân hàng IBPS dùng định dạng proprietary XML riêng của SBV
- Không tương thích với SWIFT MX (ISO 20022) hoặc JSON API RESTful
- Thiếu trường dữ liệu bổ sung (LEI, Purpose Code, Remittance Info)
- Không có cơ chế xác thực schema tập trung
- Không kết nối được với ASEAN mBridge platform
1.2 Trạng thái mục tiêu (TO-BE)
- Full ISO 20022 message catalogue (pacs, pain, camt, head, auth)
- REST/JSON + SOAP/XML dual-mode gateway
- TLS 1.3 + mTLS xác thực hai chiều
- Schema validation tại gateway (không đẩy lỗi vào core banking)
- Kết nối trực tiếp ASEAN mBridge qua ISO 20022 pacs.009
- On-chain anchoring hash giao dịch lên SBV Gov-Chain (VNLH-VND layer)
2. Phạm vi Message Catalogue
2.1 Payment Initiation — pain.*
| Message ID | Tên | Sử dụng |
|---|---|---|
| pain.001.001 | CustomerCreditTransfer | KH khởi tạo lệnh chuyển khoản |
| pain.002.001 | PaymentStatusReport | Ngân hàng phản hồi trạng thái |
| pain.007.001 | PaymentReversal | Yêu cầu thu hồi lệnh |
| pain.008.001 | DirectDebitInitiation | Khởi tạo ghi nợ trực tiếp |
| pain.013.001 | CreditorPaymentActivation | Kích hoạt thanh toán bên thụ hưởng |
2.2 Payment Clearing & Settlement — pacs.*
| Message ID | Tên | Sử dụng |
|---|---|---|
| pacs.002.001 | FIToFIPaymentStatusReport | Báo cáo trạng thái liên ngân hàng |
| pacs.003.001 | FIToFICustomerDirectDebit | Ghi nợ liên NH cho khách hàng |
| pacs.004.001 | PaymentReturn | Hoàn trả lệnh thanh toán |
| pacs.008.001 | FIToFICustomerCreditTransfer | Chuyển khoản liên NH → KH |
| pacs.009.001 | FinancialInstitutionCreditTr | Chuyển vốn liên NH (mBridge) |
| pacs.010.001 | FinancialInstitutionDebit | Ghi nợ liên NH (NHNN ↔ NHTM) |
2.3 Cash Management — camt.*
| Message ID | Tên | Sử dụng |
|---|---|---|
| camt.052.001 | BankToCustomerAccountReport | Báo cáo tài khoản tức thời |
| camt.053.001 | BankToCustomerStatement | Sao kê tài khoản định kỳ |
| camt.054.001 | BankToCustomerDebitCredit | Thông báo ghi nợ/có |
| camt.055.001 | CustomerPaymentCancellation | Yêu cầu hủy từ phía KH |
| camt.056.001 | FIToFIPaymentCancellation | Yêu cầu hủy liên ngân hàng |
| camt.057.001 | NotificationToReceive | Thông báo nhận tiền |
| camt.060.001 | AccountReportingRequest | Yêu cầu báo cáo tài khoản |
2.4 Header — head.*
| Message ID | Tên | Sử dụng |
|---|---|---|
| head.001.001 | BusinessApplicationHdr | Header chuẩn bao ngoài mọi message |
2.5 Regulatory Reporting — auth.*
| Message ID | Tên | Sử dụng |
|---|---|---|
| auth.001.001 | InformationRequestOpening | Mở yêu cầu thông tin (AML/CFT) |
| auth.002.001 | InformationRequestResponse | Phản hồi yêu cầu thông tin |
| auth.018.001 | CurrencyControlReqOrLetter | Kiểm soát ngoại hối (SBV → NHTM) |
3. Kiến trúc Gateway
┌─────────────────────────────────────────────────────────────┐
│ SBV ISO 20022 API GATEWAY │
│ │
│ ┌──────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Ingress │──▶│ Validator │──▶│ Message Router │ │
│ │ TLS 1.3 │ │ (Schema │ │ (MQ / Kafka) │ │
│ │ mTLS │ │ XSD/JSON) │ │ │ │
│ └──────────┘ └─────────────┘ └──────────┬──────────┘ │
│ │ │
│ ┌───────────────────────────────────────────▼──────────┐ │
│ │ Transformation Engine │ │
│ │ Legacy IBPS XML ◀──────────▶ ISO 20022 MX/JSON │ │
│ └───────────────────────────────────────────┬──────────┘ │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────▼───────────┐ │
│ │ VNLH Anchor │ │ Audit Log │ │ Core Banking │ │
│ │ (Gov-Chain) │ │ (AML/CFT) │ │ Adapter (IBPS) │ │
│ └──────────────┘ └──────────────┘ └───────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │
ASEAN mBridge NHTM Domestic
(pacs.009) (pain/pacs/camt)
4. Các trường bắt buộc ISO 20022 bổ sung so với IBPS
| Trường ISO 20022 | Kiểu dữ liệu | Ghi chú |
|---|---|---|
BizMsgIdr (head.001) |
Max35Text | ID duy nhất mỗi business message |
MsgDefIdr (head.001) |
Max35Text | Tên message catalogue (pacs.008.001) |
CreDt (head.001) |
ISODateTime | Thời gian tạo message (UTC+7) |
CdtrAgt/FinInstnId/LEI |
LEIIdentifier | Mã định danh tổ chức quốc tế (20 ký tự) |
Purp/Cd (pain.001) |
ExternalPurposeCode | Mục đích chuyển tiền (SALA, TAXS…) |
RmtInf/Ustrd |
Max140Text | Thông tin nội dung chuyển tiền |
CdtTrfTxInf/IntrBkSttlmAmt |
ActiveCurrencyAndAmount | Số tiền thanh toán liên NH |
SttlmMtd |
SettlementMethod | INDA/INGA/COVE/CLRG |
ClrSys/Cd |
ExternalClearingSystem | VNIBPS / MBRIDGE / SWIFT |
UndrlygCstmrCdtTrf |
(complex) | Dữ liệu KH gốc (xuyên biên giới) |
5. Cơ chế Bảo mật
- Transport: TLS 1.3 bắt buộc; TLS 1.2 chỉ cho backward-compat trong 6 tháng đầu
- Authentication: mTLS (X.509 certificate) + OAuth 2.0 client_credentials
- Authorization: RBAC — vai trò NHTM / NHNN / mBridge / Audit
- Signing: JWS (JSON Web Signature) hoặc XML-DSig trên mọi message
- Non-repudiation: Hash SHA-256 toàn bộ message body → anchor lên Gov-Chain
- Key Management: HSM (Hardware Security Module) cấp CA SBV
6. SLA và Hiệu năng
| Chỉ tiêu | Yêu cầu |
|---|---|
| Thông lượng | ≥ 5,000 TPS (peak 10,000 TPS) |
| Độ trễ (p99) | ≤ 200ms nội địa; ≤ 500ms xuyên biên giới |
| Uptime | 99.99% (≤ 52 phút downtime/năm) |
| Recovery Time Objective | RTO ≤ 15 phút |
| Recovery Point Objective | RPO ≤ 1 phút |
| Schema validation | Từ chối message lỗi ≤ 50ms |
7. Lộ trình triển khai
| Mốc | Thời gian | Nội dung |
|---|---|---|
| M1 | Tháng 1-3 | Deploy gateway infra; implement head.001 + pacs.008 + pacs.002 |
| M2 | Tháng 4-6 | Thêm pain.001/002; migration IBPS → ISO 20022 nội địa |
| M3 | Tháng 7-9 | Tích hợp camt.*; on-chain anchoring Gov-Chain |
| M4 | Tháng 10-12 | Kết nối ASEAN mBridge (pacs.009); auth.* AML reporting |
| M5 | Năm 2 Q1 | Go-live production; SWIFT ISO 20022 migration complete |