VietQR.Core 1.0.8

.NET 6.0

dotnet add package VietQR.Core --version 1.0.8

NuGet\Install-Package VietQR.Core -Version 1.0.8

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="VietQR.Core" Version="1.0.8" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="VietQR.Core" Version="1.0.8" />
                    

                            Directory.Packages.props

<PackageReference Include="VietQR.Core" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add VietQR.Core --version 1.0.8

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: VietQR.Core, 1.0.8"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package VietQR.Core@1.0.8

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=VietQR.Core&version=1.0.8
                    

                            Install as a Cake Addin

#tool nuget:?package=VietQR.Core&version=1.0.8
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

VietQR.Core

Thư viện C# (.NET) hỗ trợ tạo chuỗi, đọc mã QR và render ảnh thẻ thanh toán VietQR theo chuẩn NAPAS247 / EMVCo. Thư viện tích hợp sẵn danh mục ngân hàng Việt Nam, nhúng sẵn logo và font chữ trong DLL để sử dụng trực tiếp mà không phụ thuộc API bên ngoài.

⚡ Cài đặt

dotnet add package VietQR.Core

💡 Nếu cần lấy link mở ứng dụng ngân hàng (Mobile Banking), bạn có thể dùng thêm gói VietQR.Deeplink.Client.

🚀 Bắt đầu nhanh (Quick Start - 30 giây)

1. Tạo chuỗi mã QR thanh toán (EMVCo)

Chỉ 1 dòng lệnh, không cần cấu hình phức tạp:

using VietQR.Core;

// Tạo mã thanh toán động (chuyển khoản tới số tài khoản MBBank)
string qrContent = VietQrPayload.Create(
    bin: "970422",                  // Mã BIN ngân hàng (MBBank: 970422)
    accountNo: "056789799999",       // Số tài khoản người nhận
    amount: 50000,                   // Số tiền VNĐ (> 0 cho QR động, null cho QR tĩnh)
    description: "Ung ho quy"        // Nội dung chuyển khoản (tự bỏ dấu tiếng Việt)
);

Console.WriteLine(qrContent);
// Output: 00020101021238570010A000000727012700069704220112056789799999...63048E1D

2. Xuất ảnh thẻ thanh toán hiển thị lên UI hoặc lưu file

using VietQR.Core;

var imageService = new QrImageService();

// Xuất Data URL Base64 (gắn trực tiếp vào thẻ <img src="..."> trên Web hoặc PictureBox WinForms)
string dataUrl = await imageService.GenerateVietQrBase64Async(
    emvQrContent: qrContent,
    bankBin: "970422",
    accountNo: "056789799999",
    amount: "50000",
    description: "Ung ho quy",
    template: "compact"             // compact (mặc định) | print | qr_only
);

// Hoặc lưu thẳng ra file ảnh PNG / WebP trên ổ cứng
var options = new QrRenderOptions
{
    Template = "compact",
    BankBin = "970422",
    AccountNo = "056789799999",
    Amount = 50000,
    Description = "Ung ho quy"
};
byte[] pngBytes = await imageService.RenderBytesAsync(qrContent, options);
await File.WriteAllBytesAsync("vietqr.png", pngBytes);

🖼️ Mẫu Thẻ Thanh Toán Hỗ Trợ (Visual Showcase)

Mẫu 1: `compact` (Mặc định)	Mẫu 2: `print` (Quầy thu ngân / A4 / A5)	Mẫu 3: `card` (Chuyển tiền qua Thẻ ATM)

Header VietQR, logo Napas247 & logo ngân hàng nhúng sẵn	In to rõ số tiền, tên chủ TK, nội dung chuyển khoản	Chuyển nhanh qua số thẻ Napas (`QRIBFTTC`)

Mẫu 4: `custom_logo` (Logo thương hiệu tâm)	Mẫu 5: `qr_only` (Mã QR vuông tối giản)

Chèn logo doanh nghiệp ở tâm, giữ mã QR chuẩn đen trắng	Vuông tối giản (`Size = 500`), có icon VietQR ở giữa

📋 Bảng Tra Cứu Tham Số Chi Tiết (Parameter Reference)

1. Tham số tạo mã thanh toán: `VietQrPayload.Create()`

Tên tham số	Kiểu dữ liệu	Bắt buộc	Mô tả & Ví dụ
`bin`	`BankBin` / `string`	Bắt buộc	Mã BIN ngân hàng đúng 6 chữ số (VD: `"970422"` - MBBank, `"970436"` - VCB, `"970415"` - VietinBank).
`accountNo`	`string`	Bắt buộc	Số tài khoản, số thẻ hoặc mã tài khoản định danh/ảo (Tối đa 25 ký tự).
`amount`	`long?`	Tùy chọn	Số tiền thanh toán VNĐ ($> 0$). Bỏ trống (`null`) để tạo QR tĩnh (người quét tự gõ số tiền).
`description`	`string?`	Tùy chọn	Nội dung thanh toán (Tối đa 95 ký tự EMVCo Tag 62.08, tự động loại bỏ dấu tiếng Việt).
`serviceType`	`VietQrServiceType`	Tùy chọn	Loại hình chuyển khoản: `Account` (mặc định - QRIBFTTA) hoặc `Card` (QRIBFTTC chuyển qua thẻ).

2. Tùy chọn render ảnh thẻ: `QrRenderOptions` class

Tên thuộc tính	Kiểu dữ liệu	Mặc định	Mô tả chi tiết
`Template`	`string`	`"compact"`	Mẫu thiết kế ảnh thẻ: `"compact"` (thẻ chuẩn), `"print"` (mẫu in quầy), `"qr_only"` (chỉ QR).
`Format`	`QrImageFormat`	`Png`	Định dạng file ảnh xuất ra: `QrImageFormat.Png`, `Webp` hoặc `Svg`.
`Size`	`int`	`500`	Kích thước cạnh vuông tính bằng pixel (chỉ áp dụng cho template `"qr_only"`).
`Quality`	`int`	`100`	Chất lượng nén ảnh (từ 1 đến 100, đặc biệt hữu ích khi xuất file WebP).
`AccountName`	`string?`	`null`	Tên chủ tài khoản người nhận (hiển thị nổi bật trên mẫu in ấn `"print"`).
`CustomCenterLogo`	`byte[]?`	`null`	Mảng byte ảnh logo riêng đặt ở tâm QR (thay thế cho logo VietQR mặc định).
`CenterLogoRatio`	`float`	`0.18f`	Tỷ lệ kích thước logo ở tâm so với mã QR (từ 0.05 đến 0.35, đảm bảo mắt đọc quét tốt).
`BillNumber`	`string?`	`null`	Số hóa đơn / mã đơn hàng (trích xuất đưa vào Tag 62.01).

3. Dữ liệu nhận được khi giải mã: `VietQrInfo` class

(Kết quả trả về từ VietQrDecoder.Decode quét ảnh hoặc VietQrParser.Parse bóc tách chuỗi)

Tên thuộc tính	Kiểu dữ liệu	Ý nghĩa nghiệp vụ
`BankBin`	`string`	Mã BIN 6 số của ngân hàng thụ hưởng (VD: `"970422"`).
`BankInfo`	`BankInfo?`	Thông tin ngân hàng: tên đầy đủ (`Name`), tên viết tắt (`ShortName`), logo nhúng (`Logo`).
`AccountNo`	`string`	Số tài khoản hoặc số thẻ của người nhận tiền.
`Amount`	`decimal?`	Số tiền giao dịch thanh toán (null nếu là mã QR tĩnh).
`Description`	`string?`	Nội dung chuyển khoản trích xuất từ Tag 62.08.
`BillNumber`	`string?`	Số hóa đơn / mã đơn hàng trích xuất từ Tag 62.01.
`ServiceType`	`VietQrServiceType`	`Account` (chuyển tới STK) hoặc `Card` (chuyển tới số thẻ Napas).
`QrType`	`VietQrType`	`Static` (QR tĩnh quét tự nhập tiền) hoặc `Dynamic` (QR động có sẵn tiền).
`IsValidCrc`	`bool`	`true` nếu mã băm kiểm tra CRC16 (Tag 63) hợp lệ 100% theo chuẩn EMVCo.

💡 Các Kịch Bản Sử Dụng Thường Gặp (Common Use Cases)

1. Tạo QR tĩnh vs QR động

// QR Tĩnh (Static): Dán tại quầy thu ngân / xe bán hàng, khách tự nhập số tiền
string staticQr = VietQrPayload.Create("970422", "056789799999", description: "Cua hang A");

// QR Động (Dynamic): Gắn sẵn số tiền cho từng đơn hàng cụ thể
string dynamicQr = VietQrPayload.Create("970422", "056789799999", amount: 150000, description: "DH1024");

2. Chuyển tiền tới Số Thẻ ATM Napas (thay vì STK)

string cardQr = VietQrPayload.Create(
    bin: "970422",
    accountNo: "9704222028493997",   // Số in dập nổi trên thẻ vật lý
    amount: 100000,
    serviceType: VietQrServiceType.Card // Chuyển sang chuẩn QRIBFTTC
);

3. Tra cứu danh mục 76+ ngân hàng (Chạy Offline 100%)

var catalog = EmbeddedBankCatalog.Instance;

// Tra cứu bằng mã BIN, mã Code hoặc tên viết tắt (không phân biệt hoa thường)
BankInfo? bank = await catalog.FindAsync("970422");
// bank.ShortName == "MBBank", bank.Code == "MB", bank.Name == "Ngân hàng TMCP Quân Đội"

// Lấy danh sách toàn bộ 76+ ngân hàng
IReadOnlyList<BankInfo> allBanks = await catalog.GetAllAsync();

4. Quét và giải mã ảnh VietQR (`VietQrDecoder`)

Hỗ trợ đọc từ ảnh chụp màn hình, ảnh upload từ khách hàng (hỗ trợ cả ảnh VietQR ngân hàng và ShopeePay):

byte[] imageBytes = await File.ReadAllBytesAsync("qr_screenshot.png");

Result<VietQrInfo> result = VietQrDecoder.Decode(imageBytes);
if (result.IsSuccess)
{
    VietQrInfo info = result.Value!;
    Console.WriteLine($"Ngân hàng: {info.BankInfo?.ShortName} - STK: {info.AccountNo}");
    Console.WriteLine($"Số tiền: {info.Amount:N0} VNĐ - Nội dung: {info.Description}");
}

5. Đăng ký Dependency Injection trong ASP.NET Core

// Trong Program.cs
builder.Services.AddVietQrCore();

// Inject vào Controller hoặc Minimal API
app.MapGet("/api/qr", async (IQrGenerator generator, IQrImageRenderer renderer) =>
{
    var request = new VietQrRequest(BankBin.Create("970422"), "056789799999", 50000, "Thanh toan");
    string payload = generator.Generate(request);
    byte[] image = await renderer.RenderPngAsync(payload, new QrRenderOptions { Template = "compact" });
    return Results.File(image, "image/png");
});

🌟 Ưu Điểm của VietQR.Core

🚀 Hiệu năng cao: Tính toán chuỗi EMVCo và bảng băm CRC16 chỉ mất ~0.4 micro-giây ($\mu$s), tối ưu hóa ReadOnlySpan<char> không cấp phát rác bộ nhớ.
📦 Hỗ trợ toàn diện .NET: Tương thích .NET 6.0, .NET 8.0 (LTS), .NET 9.0 và .NET 10.0.

🙏 Lời Cảm Ơn (Acknowledgments)

NAPAS & Sáng kiến VietQR vì quy chuẩn kỹ thuật thanh toán số thông minh.
VietQR.io vì dữ liệu danh mục ngân hàng tham khảo và hệ thống CDN logo ngân hàng tiện ích cho cộng đồng.

📄 Bản Quyền & Giấy Phép

Phát hành theo giấy phép mã nguồn mở MIT License — Hoàn toàn miễn phí cho cả dự án cá nhân và thương mại.
VietQR® và NAPAS247® là nhãn hiệu thuộc sở hữu của NAPAS. Dự án này là thư viện mã nguồn mở độc lập.

Product	Compatible and additional computed target framework versions.
.NET	net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Options (>= 8.0.0)
- QRCoder (>= 1.8.1)
- SkiaSharp (>= 4.153.1)
- SkiaSharp.NativeAssets.Linux.NoDependencies (>= 4.153.1)
- SkiaSharp.NativeAssets.macOS (>= 4.153.1)
- SkiaSharp.NativeAssets.Win32 (>= 4.153.1)
- ZXing.Net (>= 0.16.9)
net6.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Options (>= 8.0.0)
- QRCoder (>= 1.8.1)
- SkiaSharp (>= 4.153.1)
- SkiaSharp.NativeAssets.Linux.NoDependencies (>= 4.153.1)
- SkiaSharp.NativeAssets.macOS (>= 4.153.1)
- SkiaSharp.NativeAssets.Win32 (>= 4.153.1)
- ZXing.Net (>= 0.16.9)
net8.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Options (>= 8.0.0)
- QRCoder (>= 1.8.1)
- SkiaSharp (>= 4.153.1)
- SkiaSharp.NativeAssets.Linux.NoDependencies (>= 4.153.1)
- SkiaSharp.NativeAssets.macOS (>= 4.153.1)
- SkiaSharp.NativeAssets.Win32 (>= 4.153.1)
- ZXing.Net (>= 0.16.9)
net9.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Options (>= 8.0.0)
- QRCoder (>= 1.8.1)
- SkiaSharp (>= 4.153.1)
- SkiaSharp.NativeAssets.Linux.NoDependencies (>= 4.153.1)
- SkiaSharp.NativeAssets.macOS (>= 4.153.1)
- SkiaSharp.NativeAssets.Win32 (>= 4.153.1)
- ZXing.Net (>= 0.16.9)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on VietQR.Core:

Package	Downloads
VietQR.Deeplink.Client Thư viện client C# (.NET) kết nối dịch vụ VietQR Deeplink để lấy link mở ứng dụng ngân hàng khi thanh toán, hỗ trợ Dependency Injection trong ASP.NET Core.	707

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.8	224	10/31/2026
1.0.7	136	10/29/2026
1.0.6	125	10/29/2026
1.0.5	122	10/28/2026
1.0.4	96	10/28/2026

Merge pull request #1 from Ngochiendev/dev (1caba35)
test(postman): Chuẩn hóa Postman collection hỗ trợ test API và Deeplink (c1b2b2b)
feat(api): Tích hợp Deeplink bridge (070b1b5)
ci(release): Thêm workflow publish NuGet cho VietQR.Deeplink.Client (d7cd7fe)
feat(client): Thêm thư viện VietQR.Deeplink.Client và tích hợp solution (5b6f73c)
docs(core): Cập nhật thông tin mô tả và metadata package VietQR.Core (610f1ec)
chore: Cập nhật .gitignore bảo vệ thư mục deeplink engine nội bộ (3183083)
chore: cập nhật .gitignore bỏ qua thư mục cache và tài liệu phân tích (24ede90)
docs: cập nhật tài liệu bảng tham số, hướng dẫn và bổ sung acknowledgments (25ea037)
fix(core): sửa lỗi format số thập phân SVG trên môi trường locale vi-VN (763ddfe)