Hướng dẫn API QR ảnh v1 | VietQR PNG

01 / BẮT ĐẦU

Chỉ cần một URL ảnh

Thay BIN và số tài khoản ví dụ bằng thông tin đã xác minh; ngân hàng phải có BIN trong danh sách hỗ trợ trên server.

01

Chọn ngân hàng

Dùng mã BIN 6 chữ số (ví dụ MBBank: 970422), không dùng mã SWIFT hoặc tên viết tắt.

02

Truyền thông tin

Chỉ bank và account là bắt buộc. Có thể thêm amount, purpose và size qua query string.

03

Nhúng ảnh

Đặt URL vào src của thẻ img. Trình duyệt tải PNG qua CDN và Nginx đến Go QR Service.

02 / THỬ TRỰC TIẾP

Tạo URL và xem trước QR

Trình thử chỉ gửi request khi bạn nhấn nút Tạo ảnh. Code HTML, URL và lệnh curl sẽ cập nhật theo mẫu đã nhập.

Thông số QR

Dữ liệu mẫu chỉ dùng để kiểm thử, không dùng chuyển tiền thật.

Xem trước PNG

Ảnh chỉ được tải sau khi bạn nhấn Tạo ảnh QR.

Ảnh QR sẽ xuất hiện tại đây.

URL được tạo

https://vietnam-bank.com/qr/v1/image.png?bank=970422&account=00123456789&amount=150000&purpose=TEST&size=320

03 / NHÚNG VÀ GỌI API

Sao chép mã để sử dụng

Dùng thẻ img cho trang web; dùng curl nếu cần thử response HTTP. Dấu & phải viết thành & trong mã HTML.

https://vietnam-bank.com/qr/v1/image.png?bank=970422&account=00123456789&amount=150000&purpose=TEST&size=320

<img
  src="https://vietnam-bank.com/qr/v1/image.png?bank=970422&amp;account=00123456789&amp;amount=150000&amp;purpose=TEST&amp;size=320"
  width="320" height="320"
  alt="VietQR bank transfer"
  loading="lazy" referrerpolicy="no-referrer"
>

curl -L --fail --output vietqr.png 'https://vietnam-bank.com/qr/v1/image.png?bank=970422&account=00123456789&amount=150000&purpose=TEST&size=320'

Không cần thẻ script hoặc CORS để chỉ hiển thị ảnh bằng img. Hãy dùng URLSearchParams hoặc encodeURIComponent khi ghép query bằng JavaScript.

04 / THÔNG SỐ

Các tham số được hỗ trợ

Endpoint là GET /qr/v1/image.png. Những tham số không được định nghĩa hoặc trùng tên đều bị từ chối.

Tham số	Bắt buộc	Ví dụ	Quy tắc xử lý
`bank`	Có	`970422`	BIN 6 chữ số; phải tồn tại trong danh sách BIN cục bộ của Go Service.
`account`	Có	`00123456789`	Từ 1 đến 19 ký tự chữ ASCII hoặc số, không dấu cách; chuẩn hóa thành chữ in hoa.
`amount`	Không	`150000`	Số nguyên VND dương (1–13 chữ số). Chấp nhận dạng nhóm hàng nghìn 1.234.567; không chấp nhận dấu phẩy hoặc số thập phân.
`purpose`	Không	`THANH TOAN DH123`	Tối đa 25 ký tự sau khi bỏ dấu và gộp khoảng trắng; nội dung không chuyển được sang ASCII sẽ bị từ chối.
`size`	Không	`320`	Số nguyên từ 128 đến 1024. Mặc định 320 nếu không truyền.

Không có tham số tên người nhận/holder hoặc QR có logo trong v1. Cung cấp sai BIN có thể khiến QR không dùng được, dù ảnh vẫn tạo thành công.

05 / PHẢN HỒI HTTP

Định dạng phản hồi và mã lỗi

Thành công trả về image/png; lỗi trả JSON cùng trường error, message và đôi khi có field.

200Thành công

PNG trong body; Content-Type: image/png. HEAD trả header mà không có body.

400Tham số sai

Thiếu BIN/tài khoản, sai định dạng, trùng tham số, BIN không được chấp nhận.

404Đường dẫn không tồn tại

Endpoint khác /image.png (hoặc route công khai không được định tuyến).

405Method không hỗ trợ

Chỉ cho phép GET và HEAD; request khác trả Allow: GET, HEAD.

422Không thể mã hóa

Payload quá lớn hoặc kích thước ảnh quá nhỏ so với độ dày QR.

503Service quá tải

Giới hạn đồng thời hoặc hàng chờ; có thể nhận Retry-After: 1.

414URL quá dài

Request URI vượt giới hạn hệ thống; cần rút ngắn query.

{"error":"Bad Request","field":"account","message":"account must have 1 to 19 letters/digits"}

06 / LƯU Ý TÍCH HỢP

Thông tin tài khoản và CDN

API ảnh Go khác với công cụ VietQR JavaScript tạo mã hoàn toàn trong trình duyệt.

Các tham số bank, account, amount và purpose nằm trong URL và được gửi tới CDN/server; có thể xuất hiện trong URL đã chia sẻ hoặc hệ thống phân tích/log của bên tích hợp. Chỉ dùng với thông tin bạn đồng ý công khai. Không để mật khẩu, mã xác thực hay thông tin nhạy cảm trong purpose. CDN phải phân biệt đầy đủ query string để tránh trả nhầm QR. Origin Go và Nginx không lưu cache ảnh.

Ảnh QR không xác minh chủ tài khoản, không xác nhận giao dịch thành công. Luôn kiểm tra tên người nhận và số tiền trên ứng dụng ngân hàng trước khi chuyển tiền.

07 / CÂU HỎI THƯỜNG GẶP

Cần biết trước khi đưa lên website

Có cần cài JavaScript, SDK hay API key không?

Không. Để hiển thị ảnh QR, chỉ cần thẻ img và URL hợp lệ. API phiên bản này không yêu cầu API key.

Có cần CORS để nhúng QR trên website khác?

Không, đối với thẻ img thông thường. Nếu đọc pixel bằng canvas hoặc dùng fetch từ domain khác, yêu cầu CORS có thể áp dụng.

Tại sao QR báo lỗi dù BIN đúng 6 chữ số?

BIN còn phải tồn tại trong registry của Go Service. Kiểm tra ngân hàng và khả năng nhận VietQR trước khi công khai.

Có thể để trống amount và purpose không?

Có. Chỉ bank và account bắt buộc; khi bỏ amount, mã QR không cố định số tiền.

Có dùng QR v1 cùng công cụ tạo QR JavaScript được không?

Có. API ảnh xử lý trên server để nhúng img; công cụ tạo VietQR hiện tại chạy trong trình duyệt và phù hợp hơn nếu cần giữ số tài khoản/số tiền trên thiết bị.

Muốn tạo mã hoàn toàn trên thiết bị?

Hãy dùng trang tạo VietQR bằng JavaScript: không cần gửi số tài khoản hay số tiền tới QR Image API của chúng tôi.

Mở công cụ tạo VietQR