Thông tin thanh toán

Ngân hàng thụ hưởng

Số tài khoản / số thẻ *

Tên chủ tài khoản (không dấu, in hoa)

Số tiền (VNĐ) * 50.000 đ

Nội dung chuyển khoản *

Mẫu thẻ hiển thị

compact Khung thẻ 540px qr_only Mã vuông tối giản print In hóa đơn đầy đủ

Định dạng hình ảnh

Phương thức chuyển khoản

Logo riêng ở tâm QR (tùy chọn)

Chọn file PNG, JPG làm logo trung tâm

Xem trước mã QR

Chuỗi EMVCo Payload

…

Developer Guide & Playground

Điều hướng ứng dụng ngân hàng (Bank Deeplink)

Tạo liên kết mở trực tiếp ứng dụng ngân hàng di động, tự động điền sẵn số tài khoản, số tiền và nội dung chuyển khoản theo chuẩn VietQR.

1. Cài đặt gói NuGet chính thức

Official .NET

Cài đặt 2 gói thư viện chuẩn vào dự án của bạn để xử lý sinh mã VietQR và khởi tạo liên kết Deeplink

VietQR.Core v1.0.1

Khởi tạo dữ liệu EMVCo, tính CRC16 và render hình ảnh thẻ thanh toán.

SDK

VietQR.Deeplink.Client v1.0.0

Client SDK tạo phiên điều hướng trực tiếp vào ứng dụng ngân hàng di động.

Terminal (.NET CLI)

dotnet add package VietQR.Core
dotnet add package VietQR.Deeplink.Client

2. Sử dụng thư viện C# (.NET SDK)

Tích hợp chỉ với 3 bước đơn giản thông qua cơ chế Dependency Injection và Fluent API của VietQR.Core

Bước 1: Đăng ký dịch vụ

Gọi builder.Services.AddVietQrDeeplink() trong file Program.cs.

Bước 2: Tạo mã VietQR

Khởi tạo đối tượng new VietQr() và cấu hình số tài khoản, số tiền, nội dung.

Bước 3: Lấy link Deeplink

Gọi extension method qr.ToDeeplinkUrlAsync(...) và trả về URL cho ứng dụng.

3. Đặc tả API Endpoint (REST API)

Endpoint khởi tạo phiên điều hướng ngắn hạn tới ứng dụng ngân hàng di động (áp dụng khi gọi từ dịch vụ ngoài .NET):

POST /api/v1/vietqr-core/deeplink/intents

Content-Type: application/json

Trường dữ liệu	Kiểu	Bắt buộc	Mô tả
appCode	string	Có	Mã định danh ứng dụng thanh toán (ví dụ: `MB`, `TPB`, `VCB`, `TCB`, `MOMO`).
qrCode	string	Có	Chuỗi dữ liệu VietQR EMVCo đầy đủ với mã kiểm tra CRC16 hợp lệ (bắt đầu bằng `000201...`).

Định dạng dữ liệu trả về (Response Payload)

{
  "code": "00",
  "desc": "Thành công",
  "data": {
    "url": "http://localhost:5187/p/8f1e2d3c",
    "expiresInSeconds": 60
  }
}

4. Mã nguồn mẫu tích hợp

Tích hợp bằng C# .NET SDK chính thức hoặc gọi trực tiếp qua HTTP Client các ngôn ngữ

CheckoutController.cs

// 1. Đăng ký dịch vụ trong Program.cs:
builder.Services.AddVietQrDeeplink();

// 2. Tiêm IVietQrDeeplinkClient vào Controller hoặc Service:
using VietQR.Core;
using VietQR.Deeplink.Client;

public class CheckoutController : ControllerBase
{
    private readonly IVietQrDeeplinkClient _deeplinkClient;

    public CheckoutController(IVietQrDeeplinkClient deeplinkClient)
    {
        _deeplinkClient = deeplinkClient;
    }

    [HttpPost("create-payment")]
    public async Task<IActionResult> CreatePayment()
    {
        // Tạo mã VietQR chuẩn NAPAS247 bằng VietQR.Core (NuGet)
        var qr = new VietQr()
            .SetBeneficiaryOrganization("970422", "056789799999", VietQrServiceType.Account)
            .SetTransactionAmount("50000")
            .SetAdditionalData(purpose: "thanh toan don hang");

        // Tạo link Deeplink mở ứng dụng MBBank tự động điền STK, tiền, nội dung
        var intent = await qr.ToDeeplinkUrlAsync(_deeplinkClient, "MB");
        if (intent is null) return BadRequest("Không tạo được liên kết điều hướng.");

        return Ok(new { url = intent.Url, expiresIn = intent.ExpiresInSeconds });
    }
}

using System.Net.Http.Json;

using var httpClient = new HttpClient();
var payload = new
{
    appCode = "MB",
    qrCode = "00020101021238560010A0000007270126000697042201120567897999990208QRIBFTTA53037045405500005802VN62230819thanh toan don hang6304B18D"
};

var response = await httpClient.PostAsJsonAsync(
    "https://api.yourdomain.com/api/v1/vietqr-core/deeplink/intents", payload);
var result = await response.Content.ReadFromJsonAsync<ApiResponse<DeeplinkResult>>();

if (result?.Code == "00")
{
    string targetUrl = result.Data.Url;
    // Điều hướng người dùng tới liên kết chuyển tiếp
}

curl -X POST "https://api.yourdomain.com/api/v1/vietqr-core/deeplink/intents" \
  -H "Content-Type: application/json" \
  -d '{
    "appCode": "MB",
    "qrCode": "00020101021238560010A0000007270126000697042201120567897999990208QRIBFTTA53037045405500005802VN62230819thanh toan don hang6304B18D"
  }'

async function createDeeplink(appCode, emvQrCode) {
  const res = await fetch('/api/v1/vietqr-core/deeplink/intents', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ appCode, qrCode: emvQrCode })
  });

  const json = await res.json();
  if (json.code === '00') {
    // Điều hướng người dùng tới liên kết mở app
    window.location.href = json.data.url;
  }
}

import requests

payload = {
    "appCode": "MB",
    "qrCode": "00020101021238560010A0000007270126000697042201120567897999990208QRIBFTTA53037045405500005802VN62230819thanh toan don hang6304B18D"
}

res = requests.post("https://api.yourdomain.com/api/v1/vietqr-core/deeplink/intents", json=payload)
data = res.json()
if data.get("code") == "00":
    target_url = data["data"]["url"]
    print(f"Mở liên kết: {target_url}")

<?php
$payload = [
    'appCode' => 'MB',
    'qrCode'  => '00020101021238560010A0000007270126000697042201120567897999990208QRIBFTTA53037045405500005802VN62230819thanh toan don hang6304B18D'
];

$ch = curl_init('https://api.yourdomain.com/api/v1/vietqr-core/deeplink/intents');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
$data = json_decode($response, true);
if ($data && $data['code'] === '00') {
    $targetUrl = $data['data']['url'];
    header("Location: $targetUrl");
    exit;
}

Cấu hình tham số kiểm thử

Ứng dụng ngân hàng ưu tiên mở

Ngân hàng thụ hưởng (BIN)

Số tài khoản nhận tiền

Lưu ý: App ngân hàng sẽ truy vấn NAPAS247 thật khi mở link. Hãy nhập số tài khoản có thật để app nhận diện đúng ngân hàng & tên người nhận.

Số tiền (VNĐ)

Nội dung chuyển khoản

Kết quả điều hướng

Hỗ trợ tự điền

Đang khởi tạo…

Quét mã QR bằng camera điện thoại để kiểm thử mở ứng dụng ngân hàng.

Đường dẫn điều hướng: Hiệu lực 60s

Mở liên kết trên trình duyệt này

Liên kết sẽ tự động kích hoạt ứng dụng ngân hàng nếu mở trên thiết bị di động, hoặc hiển thị trang thanh toán nếu mở trên máy tính.

Phân tích chuỗi EMVCo TLV

Dán chuỗi thanh toán VietQR bắt đầu bằng mã 000201... để phân tách cấu trúc các Tag dữ liệu.

Dữ liệu phân tích (JSON)

Danh sách Tag TLV

Tag	Độ dài	Nội dung

Danh mục API Endpoints

Các endpoint chuẩn RESTful phục vụ sinh mã, kết xuất đồ họa và phân giải Deeplink tại đường dẫn gốc /api/v1/vietqr-core.

Method	Endpoint	Chức năng	Kiểu trả về
GET	/generate	Sinh chuỗi EMVCo và chuỗi Base64 Data URL	JSON
POST	/generate	Như GET, truyền qua request body (hỗ trợ logo tùy biến)	JSON
GET	/image	Trả về trực tiếp luồng binary hình ảnh (PNG, WebP, SVG)	Binary
POST	/deeplink/intents	Khởi tạo liên kết mở ứng dụng ngân hàng có thời hạn	JSON
GET	/deeplink/apps	Lấy danh mục các ứng dụng hỗ trợ điều hướng Deeplink	JSON
POST	/decode	Giải mã thông tin giao dịch từ file ảnh tải lên	JSON
POST	/parse	Phân tách cấu trúc các Tag dữ liệu từ chuỗi EMVCo	JSON
GET	/banks	Danh mục 76+ ngân hàng thành viên NAPAS247	JSON
GET	/banks/{binOrCode}	Tra cứu 1 ngân hàng theo BIN hoặc mã Code (VD: 970422, MB)	JSON

Quy ước mã phản hồi: 00 Thành công · 01 Thiếu tham số · 02 Số tiền không hợp lệ · 03 Số tài khoản / BIN không đúng · 04 Không tìm thấy ngân hàng · 05 Sai template · 06 Lỗi đọc ảnh · 07 Sai chuẩn chuỗi / cổng lỗi · 99 Lỗi hệ thống.

Ví dụ nhanh

# 1. Sinh chuỗi và ảnh thẻ:
curl "https://your-host/api/v1/vietqr-core/generate?bankBin=970422&accountNo=056789799999&amount=50000&description=thanh%20toan"

# 2. Tạo link Deeplink mở app ngân hàng tự điền:
curl -X POST "https://your-host/api/v1/vietqr-core/deeplink/intents" \
  -H "Content-Type: application/json" \
  -d '{"appCode":"MB","qrCode":"00020101021238560010A0000007270126000697042201120567897999990208QRIBFTTA53037045405500005802VN62230819thanh toan don hang6304B18D"}'

# 3. Nhúng ảnh trực tiếp vào trang web:
<img src="https://your-host/api/v1/vietqr-core/image?bankBin=970422&accountNo=056789799999&amount=50000&description=thanh toan">