vietqr-core-sdk

Tài Liệu API & Liên Kết QuickLink / Deeplink

1. QuickLink Image Generation (Sinh ảnh VietQR qua URL)

Hệ thống cho phép nhúng trực tiếp thẻ <img> vào website, email hoặc hóa đơn điện tử mà không cần qua bước gọi API phức tạp.

Cú pháp đường dẫn:

https://{domain}/image/{bin_hoặc_code}-{account}-{template}.png

Danh sách Template:

• compact: Khung thanh toán gọn gàng kèm logo ngân hàng, mã VietQR và số tiền.
• compact2: Khung thanh toán nâng cao gồm thông tin đầy đủ, tên tài khoản, nội dung và dải nhận diện NAPAS / VietQR.
• qr_only: Chỉ hiển thị mã QR kèm logo ngân hàng ở tâm.
• standee: Khung dọc chuẩn standee để bàn cho cửa hàng / nhà hàng.
• sepay: Khung phong cách thanh toán hiện đại.

Các tham số Query Parameters:

| Tham số | Kiểu dữ liệu | Bắt buộc | Mô tả | | :— | :— | :— | :— | | amount | Số nguyên | Không | Số tiền thanh toán (VND). Ví dụ: 50000 | | addInfo | Chuỗi | Không | Nội dung chuyển khoản (Tối đa 50 ký tự, tự động bỏ dấu tiếng Việt) | | accountName | Chuỗi | Không | Tên chủ tài khoản thụ hưởng. Ví dụ: NGUYEN VAN A |

Ví dụ:

<img src="https://qr.yourdomain.com/image/970436-1234567890-compact2.png?amount=100000&addInfo=DH12345&accountName=NGUYEN+VAN+A" alt="VietQR Payment" />

---

2. Interactive Deeplink Hub (Cổng chuyển tiền tự động)

Đường dẫn mở giao diện thanh toán thông minh trên Web và Mobile Browser. Khi khách hàng bấm vào ngân hàng của họ, hệ thống tự động kích hoạt App ngân hàng trên điện thoại (iOS / Android) với thông tin số tài khoản và số tiền điền sẵn.

Cú pháp đường dẫn:

https://{domain}/qr/pay?bin={bin}&acc={acc}&amount={amount}&desc={desc}&name={name}

Ví dụ:

https://qr.yourdomain.com/qr/pay?bin=970436&acc=1234567890&amount=150000&desc=DH98765

---

3. REST API Endpoints

3.1. Tạo mã VietQR (POST /api/v1/generate)

Sinh chuỗi TLV EMVCo, đường dẫn QuickLink, đường dẫn Deeplink Hub và ảnh Base64.

Request Body:

{
  "bank": "970436",
  "account": "1234567890",
  "amount": 100000,
  "memo": "Thanh toan don hang #100",
  "account_name": "NGUYEN VAN A",
  "template": "compact2",
  "return_base64": true
}

Response (200 OK):

{
  "qr_data": "00020101021238540010A00000072701240006970436011012345678900208QRIBFTTA530370454061000005802VN62250821Thanh toan don hang 1006304C92E",
  "quicklink_url": "https://qr.yourdomain.com/image/970436-1234567890-compact2.png?amount=100000&addInfo=Thanh+toan+don+hang+100",
  "deeplink_url": "https://qr.yourdomain.com/qr/pay?bin=970436&acc=1234567890&amount=100000",
  "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

---

3.2. Giải mã và kiểm tra mã VietQR (POST /api/v1/parse)

Đọc chuỗi QR bất kỳ và phân tích cú pháp TLV, kiểm tra tính hợp lệ của mã kiểm tra CRC16-CCITT.

Request Body:

{
  "qr_data": "00020101021238540010A00000072701240006970436011012345678900208QRIBFTTA530370454061000005802VN62250821Thanh toan don hang 1006304C92E"
}

Response (200 OK):

{
  "valid_crc": true,
  "bin": "970436",
  "account_number": "1234567890",
  "amount": 100000,
  "memo": "Thanh toan don hang 100",
  "account_name": null,
  "service_code": "QRIBFTTA",
  "bank_info": {
    "bin": "970436",
    "code": "VCB",
    "name": "Ngoại thương Việt Nam",
    "short_name": "Vietcombank",
    "logo_url": "https://qr.yourdomain.com/assets/banks/VCB.png"
  }
}

---

3.3. Danh sách Ngân hàng (GET /api/v1/banks)

Trả về danh mục hơn 60 ngân hàng thành viên hệ thống NAPAS với đường dẫn logo local self-hosted.

Response (200 OK):

[
  {
    "bin": "970436",
    "code": "VCB",
    "name": "Ngoại thương Việt Nam",
    "short_name": "Vietcombank",
    "logo_url": "https://qr.yourdomain.com/assets/banks/VCB.png"
  },
  {
    "bin": "970422",
    "code": "MB",
    "name": "Quân Đội",
    "short_name": "MBBank",
    "logo_url": "https://qr.yourdomain.com/assets/banks/MB.png"
  }
]

---

3.4. Danh sách Deeplink Apps (GET /api/v1/deeplinks)

Trả về danh sách URL Scheme của hơn 35 ứng dụng ngân hàng di động trên thiết bị.

This site is open source. Improve this page.