vietqr-core-sdk

VietQR Core SDK System Architecture (PaaS & SaaS)

1. Overview

VietQR Core SDK is an enterprise-grade payment infrastructure adhering strictly to Vietnamese National Standards (NAPAS 247) and the international EMVCo QR specification. Key architectural pillars include:

Zero Third-Party Dependency: Completely independent of external CDNs or APIs (e.g. no reliance on img.vietqr.io or cdn.vietqr.io). All bank logos, brand assets, typography, and QR image renderers are hosted 100% on your own server.
Custom Domain Ready: All image QuickLinks (/image/{bin}-{acc}-{template}.png) and interactive Deeplink Hubs (/qr/pay) dynamically resolve against your configured custom domain (e.g., https://qr.yourdomain.com).
High Performance: Gateway core built with Rust (Axum + Tokio), sustaining tens of thousands of generation requests per second with RAM footprints below 50MB.
Multi-Platform & Multi-Architecture: Native support for Windows, Linux, and macOS on x86, x64, ARMv7, and ARM64.

2. PaaS & SaaS Architecture Diagram

+-------------------------------------------------------------------------------+
|                                  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+ Vietnamese Banks)          |  |
|  |  - Deeplink Registry (35+ Banking Apps via Direct URL Schemes)         |  |
|  +-------------------------------------------------------------------------+  |
|                                     |                                         |
|                                     v                                         |
|  +-------------------------------------------------------------------------+  |
|  |                       LOCAL ASSETS & STORAGE                            |  |
|  |  assets/banks/*.png | assets/brand/*.png | assets/fonts/Roboto-Bold.ttf |  |
|  +-------------------------------------------------------------------------+  |
+-------------------------------------------------------------------------------+
                                     ^
                                     | Direct SDK embedding or Gateway REST
+------------------------------------+------------------------------------------+
|                         MULTILINGUAL SDK SUITE                                |
|  +--------+  +----------+  +------+  +------+  +---------+  +-----+  +------+ |
|  | C (C99)|  | C++(C++17|  | Rust |  |  Go  |  | Node/TS |  | PHP |  | Java | |
|  +--------+  +----------+  +------+  +------+  +---------+  +-----+  +------+ |
|  +--------+  +----------+                                                     |
|  | Python |  |  .NET C# |                                                     |
|  +--------+  +----------+                                                     |
+-------------------------------------------------------------------------------+

3. EMVCo & NAPAS 247 Specification

The generated QR code strictly adheres to the EMVCo Merchant-Presented QR standard:

Tag 00 (Payload Format Indicator): Constant "01".
Tag 01 (Point of Initiation Method):
- "11": Static QR (Fixed counter, user enters variable amount).
- "12": Dynamic QR (Order-specific, pre-defined amount and memo).
Tag 38 (Merchant Account Information - VietQR NAPAS 247):
- Sub-tag 00 (Globally Unique Identifier): "A000000727" (NAPAS routing ID).
- Sub-tag 01 (Payment Network Specific):
  - Sub-tag 00: 6-digit Bank BIN (e.g. 970436 for Vietcombank).
  - Sub-tag 01: Beneficiary Account Number.
- Sub-tag 02 (Service Code):
  - "QRIBFTTA": Transfer to Account.
  - "QRIBFTTC": Transfer to Card.
Tag 53 (Transaction Currency): "704" (ISO 4217 VND code).
Tag 54 (Transaction Amount): Positive integer (e.g. "100000").
Tag 58 (Country Code): "VN".
Tag 59 (Merchant Name): Beneficiary name in uppercase ASCII (max 25 characters).
Tag 62 (Additional Data Field Template):
- Sub-tag 08 (Purpose of Transaction): Order memo (max 50 chars, auto-normalized without Vietnamese diacritics for 100% banking app compatibility).
Tag 63 (CRC): 4 uppercase hex digits computed via CRC16-CCITT False (Polynomial: 0x1021, Initial Value: 0xFFFF, no reflection).

This site is open source. Improve this page.