# VietQR Core SDK (PaaS & SaaS) - Chuẩn Quốc Gia NAPAS 247 & EMVCo
Hạ Tầng Mã Phản Hồi Nhanh (QR Code) Thanh Toán Liên Ngân Hàng Việt Nam
English Documentation |
Kiến Trúc Hệ Thống |
Đặc Tả OpenAPI
Bộ giải pháp hạ tầng thanh toán số **VietQR Core SDK** toàn diện, hỗ trợ đa ngôn ngữ, chuẩn hóa theo thông số kỹ thuật **NAPAS 247** và **EMVCo QR Code**. Thiết kế theo kiến trúc **PaaS & SaaS**, hỗ trợ self-host 100% không phụ thuộc dịch vụ bên thứ ba, tự động gắn tên miền riêng và chứng chỉ SSL Let's Encrypt. Hỗ trợ sẵn các gói tích hợp chính thức cho **Laravel, Node.js (Express/Next.js), Python (FastAPI/Flask/CLI), PHP, Go, .NET C#**.
---
## 🌟 Tính năng nổi bật
1. **Zero Third-Party Dependency (Không phụ thuộc bên thứ 3):**
- Toàn bộ logo ngân hàng (hơn 60 ngân hàng Việt Nam), font chữ, tài nguyên đồ họa được tích hợp sẵn tại local máy chủ.
- Không gọi bất kỳ liên kết ngoài nào như `img.vietqr.io` hay `cdn.vietqr.io`.
2. **Cấu hình Domain Riêng (Custom Domain PaaS/SaaS):**
- Sinh ảnh VietQR trực tiếp qua đường dẫn: `https://qr.yourdomain.com/image/{bin}-{acc}-{template}.png`.
- Cung cấp cổng thanh toán trực quan Deeplink Hub: `https://qr.yourdomain.com/qr/pay?...`.
3. **Engine Gateway Siêu Tốc (Rust Axum & Tokio) & Vector SVG Engine:**
- Động cơ sinh vector SVG trực tiếp (`.svg`) siêu nét, sắc nét vô hạn trên màn hình Retina / 4K và tài liệu in ấn PDF/In nhiệt POS.
- Song hành hoàn hảo với định dạng ảnh raster PNG (`.png`).
- Xử lý hàng chục ngàn lượt sinh ảnh và chuỗi TLV mỗi giây với mức RAM < 50MB.
4. **Bộ Thư Viện SDK Đa Ngôn Ngữ (55+ Ngôn Ngữ Phổ Biến):**
- Hỗ trợ đầy đủ **55+ ngôn ngữ lập trình**: Rust, Go, Node.js/TypeScript, PHP/Laravel, Python, C# .NET, Java, Kotlin, Swift, Ruby, Dart/Flutter, C, C++, Scala, Groovy, Clojure, Elixir, Erlang, Haskell, OCaml, F#, R, Julia, Lua, Perl, Zig, Nim, Crystal, D, Pascal, Fortran, V, Racket, Common Lisp, Scheme, Tcl, Ada, Prolog, Bash, PowerShell, Objective-C, Solidity, WASM, AWK, Haxe, VB.NET, Elm, PureScript, CoffeeScript, ReScript, Apex, ActionScript, Vyper, Ballerina, Smalltalk.
5. **Cổng Thanh Toán VNPay v2.1.0 Chuẩn HMAC-SHA512:**
- Tạo URL thanh toán VNPay chuẩn v2.1.0 với thuật toán mã hóa HMAC-SHA512.
- Kiểm thử và xác thực dữ liệu phản hồi (Return URL) / IPN webhook.
6. **7 Mẫu Giao Diện VietQR Chuẩn & Cơ Chế Fallback:**
- `compact2` (Mặc định: thẻ chuẩn đầy đủ logo ngân hàng, số tài khoản, người thụ hưởng, dải nhận diện NAPAS / VietQR).
- `compact` (Tối giản, nhỏ gọn).
- `qr_only` (Chỉ mã QR thuần túy kèm logo trung tâm).
- `print` (Độ tương phản cao, tối ưu cho máy in hóa đơn nhiệt POS và khổ giấy A4/A5).
- `loax` (Thẻ hiện đại với gradient nổi bật thương hiệu).
- `vietqr_pro` (Phong cách VietQR Pro sang trọng tông vàng kim/dark mode).
- `payos` (Phong cách thanh toán fintech trẻ trung).
- *Quy tắc fallback:* Custom theme người dùng truyền vào tự động hiển thị theo template `compact2`; tên template lạ/sai định dạng tự động fallback về `compact`.
7. **Đường Dẫn Linh Hoạt & Tương Thích Tuyệt Đối:**
- Định dạng hiện đại: `/image/--.(svg|png)`, `/image/-.(svg|png)`.
- Đường dẫn Legacy: `/////.`, `//`.
- Cơ chế `REDIRECT_RASTER_TO_SVG=true`: Tự động chuyển hướng (HTTP 307) trình duyệt máy tính đến ảnh `.svg` siêu sắc nét, trong khi giữ nguyên ảnh `.png` cho các thiết bị di động (iOS/Android).
8. **Web Studio & Trình Quét QR Thông Minh:**
- Kéo-thả (drag-drop), dán (Ctrl+V) hoặc tải tệp ảnh QR bất kỳ để trích xuất ngay lập tức số tài khoản, tên ngân hàng, số tiền và nội dung thanh toán (giải mã offline qua `jsQR` và fallback API `/api/v1/decode`).
- Tìm kiếm ngân hàng theo prefix/tên/mã BIN real-time.
- Nút tải ảnh định dạng PNG/SVG và sao chép mã payload chuỗi EMVCo chỉ với 1 cú click.
9. **Deeplink Tự Động Kích Hoạt 44+ App Ngân Hàng & Ví Điện Tử:**
- Tự động mở ứng dụng ngân hàng tương ứng trên iOS & Android với số tài khoản và số tiền điền sẵn.
---
## 📁 Cấu trúc Thư mục Dự án
```
vietqr-core-sdk/
├── assets/ # Tài nguyên local (Zero 3rd-party)
│ ├── banks/ # 62+ Logo ngân hàng định dạng PNG chất lượng cao
│ ├── brand/ # Logo VietQR, NAPAS, PTN
│ └── fonts/ # Font Roboto-Bold hỗ trợ tiếng Việt
├── data/
│ ├── banks.json # Danh mục ngân hàng chuẩn NAPAS
│ └── deeplinks.json # Cấu hình 44+ URL Scheme ứng dụng ngân hàng & ví
├── sdks/ # Bộ thư viện 13 ngôn ngữ lập trình
│ ├── c/ # C99 SDK (CMake, Shared/Static Library)
│ ├── cpp/ # C++17 Header-only & Fluent API SDK
│ ├── rust/ # Rust SDK (Cargo crate)
│ ├── golang/ # Go SDK (go.mod)
│ ├── nodejs/ # Node.js & TypeScript SDK (npm package)
│ ├── php/ # PHP 7.4/8+ SDK (Composer package)
│ ├── java/ # Java 11+ SDK (Maven package)
│ ├── python/ # Python 3.8+ SDK (pip/PyPI)
│ ├── dotnet/ # .NET Standard 2.0 / .NET 8 / .NET 9
│ ├── dart/ # Dart & Flutter SDK
│ ├── kotlin/ # Kotlin & Android SDK
│ ├── swift/ # Swift & iOS SDK
│ └── ruby/ # Ruby gem
│ └── dotnet/ # .NET Standard 2.0 / .NET 8 SDK
├── server/ # Rust Axum Gateway Engine (PaaS / SaaS)
│ ├── Cargo.toml
│ └── src/
│ ├── main.rs # Điểm khởi chạy Gateway
│ ├── config.rs # Cấu hình Domain, Port, Scheme, API Key
│ ├── emvco.rs # Engine sinh và giải mã EMVCo TLV + CRC16
│ ├── canvas.rs # Render ảnh VietQR các mẫu compact, standee...
│ ├── banks.rs # Registry ngân hàng nội bộ
│ ├── deeplink.rs # Registry Deeplink App Scheme
│ ├── pay_hub.rs # Web Pay Hub giao diện mobile
│ ├── routes.rs # Router API & Link handler
│ └── ui/ # Web Studio & Pay Hub HTML templates
├── deploy/ # Môi trường triển khai Production
│ ├── docker/ # Dockerfile multi-arch & Docker Compose
│ ├── linux/ # Script cài đặt tự động & Systemd Service
│ └── reverse-proxy/ # File cấu hình mẫu Caddy & Nginx
├── docs/ # Tài liệu chi tiết song ngữ Anh - Việt
│ ├── vi/ # Tài liệu Tiếng Việt (Kiến trúc, Cài đặt, API, SDK)
│ ├── en/ # Tài liệu Tiếng Anh
│ └── openapi.yaml # Đặc tả chuẩn OpenAPI 3.0.3
└── .github/workflows/ # GitHub Actions CI/CD matrix tự động hóa
├── ci.yml # Test tự động 9 ngôn ngữ SDK
├── release-artifacts.yml # Cross-build binary cho 10 nền tảng OS/CPU
└── docker-publish.yml # Build & Push Docker image multi-arch lên GHCR
```
---
## 🚀 Hướng dẫn Triển khai Nhanh (SaaS Production)
### 1. Chạy với Docker Compose & Tự động cấp SSL (Let's Encrypt)
```bash
cd deploy/docker
cp .env.example .env
# Sửa domain của bạn
sed -i 's/qr.yourdomain.com/tenmien-cua-ban.com/g' .env
# Khởi chạy cụm dịch vụ
docker-compose -f docker-compose.prod.yml up -d
```
### 2. Cài đặt trực tiếp lên máy chủ Linux (Systemd)
```bash
sudo bash deploy/linux/install.sh --domain tenmien-cua-ban.com --scheme https
```
---
## 🛠️ Ví dụ Sử dụng QuickLink & Deeplink
### Sinh ảnh mã QR trực tiếp qua URL:
```html
```
### Trang Web Pay Hub (Tự động mở App ngân hàng trên điện thoại):
```
https://qr.yourdomain.com/qr/pay?bin=970436&acc=1234567890&amount=100000&desc=DH12345
```
---
---
## 📦 Hỗ trợ Framework & Package Ecosystem
### 🔴 Laravel Framework (`vietqr/core-sdk`)
Tương thích hoàn toàn Laravel 8, 9, 10, 11+ với cơ chế tự nhận diện ServiceProvider, Facade và Blade Directive:
```bash
composer require vietqr/core-sdk
php artisan vendor:publish --tag=vietqr-config
```
```php
use VietQR\Laravel\Facades\VietQR;
// Sinh chuỗi mã QR EMVCo chuẩn NAPAS 247
$qr = VietQR::generate(bank: 'MB', account: '0352350917', amount: 50000, memo: 'DON HANG #123');
// Sinh URL ảnh QuickLink trực quan trên Gateway riêng
$imageUrl = VietQR::quicklink(bank: 'MB', account: '0352350917', amount: 50000, template: 'compact2');
// Lấy danh sách 44+ deeplink mở app ngân hàng
$deeplinks = VietQR::deeplink('MB', '0352350917', 50000, 'DON HANG #123')->getAll();
```
Trong Blade view:
```blade
)
```
---
### 🟢 Node.js / TypeScript (`@vietqr/core-sdk`)
Hỗ trợ cả Express.js và Next.js (App Router & Pages Router):
```bash
npm install @vietqr/core-sdk
```
**Express.js:**
```typescript
import express from 'express';
import { createVietQRExpressHandler } from '@vietqr/core-sdk';
const app = express();
app.use('/api/vietqr', createVietQRExpressHandler({
defaultBank: '970422',
defaultAccount: '0352350917',
gatewayUrl: 'https://qr.tenmien-cua-ban.com'
}));
```
**Next.js (App Router):**
```typescript
// app/api/vietqr/route.ts
import { createVietQRNextHandler } from '@vietqr/core-sdk';
export const { GET, POST } = createVietQRNextHandler({
defaultBank: process.env.VIETQR_DEFAULT_BANK || '970422',
defaultAccount: process.env.VIETQR_DEFAULT_ACCOUNT,
gatewayUrl: process.env.VIETQR_GATEWAY_URL,
});
```
---
### 🐍 Python Package & CLI (`vietqr-core`)
```bash
pip install vietqr-core
```
**Sử dụng CLI tiện lợi:**
```bash
vietqr generate --bank MB --account 0352350917 --amount 50000 --memo "Don hang"
vietqr verify "00020101021238540010A00000072701240006970422..."
vietqr quicklink --bank VCB --account 0011002233 --amount 100000
vietqr banks --query MB
```
**Tích hợp FastAPI:**
```python
from fastapi import FastAPI
from vietqr.integrations.fastapi import get_vietqr_router
app = FastAPI()
app.include_router(get_vietqr_router(
default_bank="970422",
default_account="0352350917",
gateway_url="https://qr.tenmien-cua-ban.com"
))
```
---
### 🔵 Go (`net/http`, Gin, Fiber)
```go
import "github.com/vietqr/vietqr-go"
http.Handle("/vietqr/", vietqr.NewHTTPHandler(vietqr.HandlerOptions{
DefaultBank: "970422",
DefaultAccount: "0352350917",
GatewayURL: "https://qr.tenmien-cua-ban.com",
}))
```
---
### 🔷 .NET C# (Dependency Injection)
```csharp
using VietQR.Core;
builder.Services.AddSingleton(new VietQRService(new VietQROptions {
DefaultBank = "970422",
DefaultAccount = "0352350917",
GatewayUrl = "https://qr.tenmien-cua-ban.com"
}));
```
---
## 📖 Tài Liệu Tham Khảo
- [Kiến trúc hệ thống PaaS/SaaS](docs/vi/architecture.md)
- [Hướng dẫn cài đặt Linux & Cấu hình Tên Miền](docs/vi/deployment.md)
- [Đặc tả API & QuickLink Reference](docs/vi/api-reference.md)
- [Hướng dẫn tích hợp SDK 9 Ngôn Ngữ](docs/vi/sdk-guides.md)
- [Đặc tả OpenAPI 3.0](docs/openapi.yaml)
---
## 📄 Bản quyền & Giấy phép
Phát hành theo giấy phép [MIT License](LICENSE).
Bản quyền thuộc về cộng đồng phát triển VietQR Core SDK.