# Kiến Trúc Hệ Thống VietQR Core SDK (PaaS & SaaS) ## 1. Giới thiệu tổng quan **VietQR Core SDK** là giải pháp nền tảng thanh toán chuẩn quốc gia (NAPAS 247 & EMVCo QR) và SaaS/PaaS độc lập toàn diện. Toàn bộ kiến trúc được thiết kế với nguyên tắc: - **Zero Third-Party Dependency:** Không phụ thuộc bất kỳ API hay CDN hình ảnh bên thứ ba nào (như `img.vietqr.io` hay `cdn.vietqr.io`). Toàn bộ tài nguyên logo ngân hàng, thương hiệu, font chữ và engine sinh mã đều được self-host 100% tại local máy chủ của bạn. - **Custom Domain Ready:** Mọi link ảnh QuickLink (`/image/{bin}-{acc}-{template}.png`) và trang chuyển khoản Deeplink Hub (`/qr/pay`) đều tự động sinh ra theo tên miền riêng do bạn cấu hình (ví dụ: `https://qr.yourdomain.com`). - **Hiệu năng cực cao:** Gateway core được viết bằng **Rust (Axum + Tokio)**, có khả năng xử lý hàng chục ngàn yêu cầu sinh mã/giây với mức tiêu thụ RAM dưới 50MB. - **Đa nền tảng và đa kiến trúc:** Hỗ trợ Windows, Linux, macOS trên các kiến trúc `x86`, `x64`, `ARMv7`, `ARM64`. --- ## 2. Mô hình Kiến trúc PaaS & SaaS ``` +-------------------------------------------------------------------------------+ | KHÁCH HÀNG / CLIENTS | | +--------------------+ +--------------------+ +-------------------------+ | | | Web Browser / Ecom | | iOS / Android Apps | | ERP / POS / Backend API | | | +---------+----------+ +---------+----------+ +------------+------------+ | +------------|-----------------------|--------------------------|---------------+ | | | v v v +-------------------------------------------------------------------------------+ | REVERSE PROXY & SSL (NGINX / CADDY / CLOUDFLARE) | | https://qr.yourdomain.com (Let's Encrypt TLS) | +------------------------------------+------------------------------------------+ | v +-------------------------------------------------------------------------------+ | VIETQR GATEWAY ENGINE (RUST SERVICE) | | | | +------------------------+ +----------------------+ +-------------------+ | | | QuickLink Image API | | Web Deeplink Hub | | REST API | | | | /image/{slug}.png | | /qr/pay (Mobile) | | /api/v1/generate | | | +-----------+------------+ +----------+-----------+ +---------+---------+ | | | | | | | v v v | | +-------------------------------------------------------------------------+ | | | CORE MODULES | | | | - EMVCo TLV Generator & Parser (CRC16-CCITT False: 0x1021) | | | | - High Performance Canvas Renderer (compact, compact2, standee, sepay) | | | | - Bank Catalog & Local Assets Registry (62+ Ngân hàng Việt Nam) | | | | - Deeplink Registry (35+ Ứng dụng ngân hàng qua App Scheme) | | | +-------------------------------------------------------------------------+ | | | | | v | | +-------------------------------------------------------------------------+ | | | LOCAL ASSETS & STORAGE | | | | assets/banks/*.png | assets/brand/*.png | assets/fonts/Roboto-Bold.ttf | | | +-------------------------------------------------------------------------+ | +-------------------------------------------------------------------------------+ ^ | Tích hợp SDK độc lập hoặc gọi Gateway +------------------------------------+------------------------------------------+ | BỘ THƯ VIỆN SDK ĐA NGÔN NGỮ | | +--------+ +----------+ +------+ +------+ +---------+ +-----+ +------+ | | | C (C99)| | C++(C++17| | Rust | | Go | | Node/TS | | PHP | | Java | | | +--------+ +----------+ +------+ +------+ +---------+ +-----+ +------+ | | +--------+ +----------+ | | | Python | | .NET C# | | | +--------+ +----------+ | +-------------------------------------------------------------------------------+ ``` --- ## 3. Quy chuẩn EMVCo & NAPAS 247 Mã VietQR tuân thủ chuẩn EMVCo QR Code Specification for Payment Systems (Merchant-Presented QR): - **Tag 00 (Payload Format Indicator):** Giá trị mặc định `"01"` (Version 1.0). - **Tag 01 (Point of Initiation Method):** - `"11"`: Static QR (Dùng cho quầy cố định, không fix số tiền hoặc khách tự nhập). - `"12"`: Dynamic QR (Dùng cho từng đơn hàng với số tiền và nội dung cụ thể). - **Tag 38 (Merchant Account Information - VietQR NAPAS 247):** - Sub-tag `00` (Globally Unique Identifier): `"A000000727"` (Định danh hệ thống NAPAS). - Sub-tag `01` (Payment Network Specific): - Sub-tag `00`: Mã BIN 6 số của ngân hàng (Ví dụ: `970436` cho Vietcombank). - Sub-tag `01`: Số tài khoản thụ hưởng. - Sub-tag `02` (Service Code): - `"QRIBFTTA"`: Chuyển tiền nhanh đến Tài khoản (Account). - `"QRIBFTTC"`: Chuyển tiền nhanh đến Thẻ (Card). - **Tag 53 (Transaction Currency):** `"704"` (Mã tiền tệ VND theo ISO 4217). - **Tag 54 (Transaction Amount):** Số tiền thanh toán (Số nguyên dương, ví dụ `"100000"`). - **Tag 58 (Country Code):** `"VN"`. - **Tag 59 (Merchant Name):** Tên chủ tài khoản hoặc cửa hàng (Chuỗi ASCII không dấu, in hoa, tối đa 25 ký tự). - **Tag 62 (Additional Data Field Template):** - Sub-tag `08` (Purpose of Transaction): Nội dung chuyển tiền (Tối đa 50 ký tự, tự động bỏ dấu tiếng Việt để tương thích 100% app ngân hàng). - **Tag 63 (CRC):** 4 ký tự Hex in hoa, tính toán bằng thuật toán CRC16-CCITT False (`Polynomial: 0x1021`, `Init: 0xFFFF`, không đảo bit). --- ## 4. Quản lý Tài nguyên Cục bộ (Local Assets) Toàn bộ hệ thống không gọi bất kỳ liên kết ngoại vi nào: - Thư mục `assets/banks/` lưu trữ icon PNG trong suốt chất lượng cao của hơn 60 ngân hàng. - Hệ thống hỗ trợ tra cứu kép qua cả **Mã BIN** (`assets/banks/970436.png`) và **Mã viết tắt** (`assets/banks/VCB.png`). - Khi client yêu cầu `/assets/banks/VCB.png` hoặc `/image/VCB-1234567890-compact2.png`, server tự động mapping và render trực tiếp từ bộ nhớ đệm (Cache) trên local server.