vietqr-core-sdk

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.

This site is open source. Improve this page.