THE VIETQR FIELD GUIDE
Tài liệu Hướng dẫn
1. Cài đặt
Chọn framework và trình quản lý package để nhận lệnh cài đặt phù hợp.
pnpm add @viet-qr/core @viet-qr/react2. Cách sử dụng (Core)
Dùng `generateVietQR` để tạo ra chuỗi thanh toán đạt chuẩn EMVCo, và `parseVietQR` để giải mã, kiểm tra tính toàn vẹn của một mã QR bất kỳ (của bạn hoặc bên thứ ba).
import { generateVietQR, parseVietQR } from '@viet-qr/core';
const payload = generateVietQR({
bankId: 'VCB',
accountNo: '1122334455',
accountName: 'NGUYEN NGOC A',
amount: 50000,
content: 'Thanh toan don hang',
});
console.log(payload);
// Decode & validate any VietQR string (yours or a third-party one)
const result = parseVietQR(payload);
console.log(result.isValid, result.isDynamic, result.beneficiary);accountNo phải là chữ và số (tối đa 50 ký tự), amount phải là số nguyên không âm và tối đa 13 chữ số. Bỏ trống hoặc dùng 0 để tạo QR tĩnh; dữ liệu sai định dạng sẽ báo lỗi.
3. Components
Ví dụ bên dưới thay đổi theo lựa chọn. API core dùng chung cho các framework.
React
Nếu bạn dùng React, chúng tôi cung cấp sẵn một component bọc (wrapper) để tự động hóa mọi thứ từ việc tạo chuỗi đến việc vẽ mã QR.
import { VietQR, VietQRButton } from '@viet-qr/react';
import { CompactCard, PayStandee } from '@viet-qr/templates/react';
function PaymentModal() {
return (
<>
{/* Basic QR */}
<VietQR
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
content="Thanh toan don hang"
renderAs="svg"
size={300}
/>
{/* Payment Button with built-in Modal */}
<VietQRButton
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
label="Thanh toán"
/>
{/* Pre-built Templates */}
<CompactCard
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
/>
<PayStandee
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
/>
</>
);
}Muốn tự chủ hoàn toàn giao diện? @viet-qr/react cũng export sẵn hook/composable useVietQR, trả về object phản ứng { payload, isValid, error } để bạn tự vẽ mã QR theo ý muốn.
Vue
Nếu bạn dùng Vue, chúng tôi cung cấp sẵn một component bọc (wrapper) để tự động hóa mọi thứ từ việc tạo chuỗi đến việc vẽ mã QR.
<script setup>
import { VietQR, VietQRButton } from '@viet-qr/vue';
import { CompactCard, PayStandee } from '@viet-qr/templates/vue';
import '@viet-qr/vue/style.css'; // For VietQRButton Modal
</script>
<template>
<!-- Basic QR -->
<VietQR
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
:amount="50000"
content="Thanh toan don hang"
renderAs="svg"
:size="300"
/>
<!-- Payment Button with built-in Modal -->
<VietQRButton
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
:amount="50000"
label="Thanh toán"
/>
<!-- Pre-built Templates -->
<CompactCard
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
:amount="50000"
/>
<PayStandee
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
:amount="50000"
/>
</template>Muốn tự chủ hoàn toàn giao diện? @viet-qr/vue cũng export sẵn hook/composable useVietQR, trả về object phản ứng { payload, isValid, error } để bạn tự vẽ mã QR theo ý muốn.
Svelte
Nếu bạn dùng Svelte, chúng tôi cung cấp sẵn một component bọc (wrapper) để tự động hóa mọi thứ từ việc tạo chuỗi đến việc vẽ mã QR.
<script>
import { VietQR, VietQRButton } from '@viet-qr/svelte';
import { CompactCard, PayStandee } from '@viet-qr/templates/svelte';
</script>
<!-- Basic QR -->
<VietQR
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
content="Thanh toan don hang"
renderAs="svg"
size={300}
/>
<!-- Payment Button with built-in Modal -->
<VietQRButton
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
label="Thanh toán"
/>
<!-- Pre-built Templates -->
<CompactCard
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
/>
<PayStandee
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
/>Muốn tự chủ hoàn toàn giao diện? @viet-qr/svelte cũng export sẵn hook/composable useVietQR, trả về object phản ứng { payload, isValid, error } để bạn tự vẽ mã QR theo ý muốn.
Lưu ý cho Svelte 4
Thư viện giữ nguyên mã nguồn TypeScript để tối ưu nhắc lệnh. Nếu dùng Svelte 4, hãy cấu hình Vite để xử lý mã nguồn trực tiếp theo 2 file dưới đây:
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
export default defineConfig({
plugins: [svelte()],
optimizeDeps: {
exclude: ['@viet-qr/svelte', '@viet-qr/templates']
}
});import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
export default {
preprocess: vitePreprocess()
};Vanilla JS
Nếu bạn dùng Vanilla JS, chúng tôi cung cấp sẵn một component bọc (wrapper) để tự động hóa mọi thứ từ việc tạo chuỗi đến việc vẽ mã QR.
<!-- Include the library via CDN -->
<script src="https://unpkg.com/@viet-qr/templates/dist/elements/index.global.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@viet-qr/templates/dist/styles.css" />
<!-- Basic QR, no card wrapper -->
<viet-qr-basic
bank-id="VCB"
account-no="1122334455"
account-name="NGUYEN NGOC A"
amount="50000"
></viet-qr-basic>
<!-- Pre-built Templates -->
<viet-qr-compact
bank-id="VCB"
account-no="1122334455"
account-name="NGUYEN NGOC A"
amount="50000"
></viet-qr-compact>
<viet-qr-standee
bank-id="VCB"
account-no="1122334455"
account-name="NGUYEN NGOC A"
amount="50000"
></viet-qr-standee>
<!-- Payment Button with built-in Modal -->
<viet-qr-button
bank-id="VCB"
account-no="1122334455"
account-name="NGUYEN NGOC A"
amount="50000"
label="Thanh toán"
></viet-qr-button>4. Tài liệu API
Bạn muốn tìm hiểu chi tiết về các hàm, tham số (props), và kiểu dữ liệu? Khám phá ngay Tài liệu API đầy đủ của VietQR.
Tài liệu API