vietqr-core-sdk

API Reference & QuickLink / Deeplink Documentation

1. QuickLink Image Generation (Direct URL Rendering)

Embed VietQR payment codes directly into HTML <img> tags, PDF receipts, or invoices without intermediary API calls.

URL Format:

https://{domain}/image/{bin_or_code}-{account}-{template}.png

Supported Templates:

• compact: Clean layout showing bank logo, QR code, and transfer amount.
• compact2: Rich payment frame with beneficiary name, amount, memo, and NAPAS / VietQR branding.
• qr_only: Minimalist QR code with centered bank logo.
• standee: Vertical table-stand layout designed for retail counters and restaurants.
• sepay: Modern fintech payment design.

Query Parameters:

| Parameter | Type | Required | Description | | :— | :— | :— | :— | | amount | Integer | No | Transfer amount in VND (e.g., 50000). | | addInfo | String | No | Transfer memo / description (max 50 chars, auto-normalized to ASCII). | | accountName | String | No | Beneficiary account holder name (e.g., NGUYEN VAN A). |

HTML Example:

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

---

2. Interactive Deeplink Hub

Responsive web hub for mobile and desktop checkout. Customers selecting their bank automatically trigger the installed banking app on iOS/Android with recipient account and amount pre-filled.

URL Format:

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

Example:

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

---

3. REST API Endpoints

3.1. Generate VietQR (POST /api/v1/generate)

Generates the EMVCo TLV string, self-hosted QuickLink URL, Deeplink Hub URL, and optional Base64 PNG.

Request Body:

{
  "bank": "970436",
  "account": "1234567890",
  "amount": 100000,
  "memo": "Order payment #100",
  "account_name": "NGUYEN VAN A",
  "template": "compact2",
  "return_base64": true
}

Response (200 OK):

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

---

3.2. Parse & Validate VietQR (POST /api/v1/parse)

Decodes any VietQR EMVCo string, parses sub-tags, and validates the CRC16-CCITT checksum.

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. Bank Catalog (GET /api/v1/banks)

Returns all supported Vietnamese banks with local self-hosted logo URLs.

---

3.4. Deeplink Schemas (GET /api/v1/deeplinks)

Returns direct mobile URL schemes for 35+ banking applications.

This site is open source. Improve this page.