Bỏ qua tới nội dung
Hướng dẫn

Tích hợp thanh toán VietQR: tạo QR theo đơn, đối soát tự động

Hướng dẫn tích hợp thanh toán VietQR vào website, phần mềm: tạo mã QR động theo từng đơn, quy ước nội dung chuyển khoản, nhận webhook và đối soát tự động.

Bởi Đội ngũ ULI· Đăng · Cập nhật · 10 phút đọc
Tích hợp thanh toán VietQR: tạo QR theo đơn, đối soát tự động

Tóm tắt nhanh

Tích hợp thanh toán VietQR là việc phần mềm tự tạo mã QR chuyển khoản cho từng đơn, có sẵn số tiền và nội dung chứa mã đơn, khách quét bằng ứng dụng ngân hàng để trả tiền, rồi hệ thống nhận thông báo giao dịch từ ngân hàng hoặc đơn vị trung gian để tự đối chiếu và cập nhật đơn.

  • VietQR là chuẩn mã QR chuyển khoản liên ngân hàng do NAPAS vận hành, dựa trên chuẩn EMVCo
  • QR động theo từng đơn chứa sẵn số tiền và nội dung, giảm sai sót khi khách tự nhập
  • Nội dung chuyển khoản cần mã đơn ngắn, duy nhất, không dấu để đối soát chính xác
  • Đối soát tự động cần nguồn thông báo giao dịch: API ngân hàng hoặc đơn vị trung gian
  • Luôn có quy trình xử lý ngoại lệ: chuyển thiếu, thừa, sai nội dung, chuyển trùng
Mục lục bài viết

Chuyển khoản bằng mã QR đã trở thành cách thanh toán quen thuộc của khách hàng Việt Nam. Vấn đề nằm ở phía doanh nghiệp: khi đơn nhiều, kế toán phải dò sao kê, đoán xem khoản tiền nào thuộc đơn nào, khách ghi sai nội dung thì càng mất thời gian. Tích hợp thanh toán VietQR giải quyết việc này bằng cách tạo QR riêng cho từng đơn và tự đối soát khi tiền về. Bài viết hướng dẫn 7 bước triển khai, kèm ví dụ dữ liệu webhook.

VietQR là gì và vì sao nên tích hợp?

VietQR là chuẩn mã QR dùng cho chuyển khoản liên ngân hàng tại Việt Nam do NAPAS vận hành, xây dựng trên chuẩn QR thanh toán EMVCo. Hầu hết ứng dụng ngân hàng trong nước đều quét được mã VietQR.

Khi tích hợp vào website hoặc phần mềm bán hàng, bạn nhận được ba lợi ích:

  • Khách không phải gõ tay số tài khoản, số tiền, nội dung, nên giảm chuyển sai.
  • Mỗi đơn một mã QR với nội dung chứa mã đơn, giúp máy đối chiếu chính xác.
  • Xác nhận gần như tức thì: khi có thông báo giao dịch, đơn chuyển sang "đã thanh toán" mà không cần người kiểm tra.

Thông tin chính thức về chuẩn VietQR và danh sách ngân hàng tham gia có tại trang của NAPAS.

Sơ đồ tích hợp thanh toán VietQR: tạo đơn, sinh QR động, khách quét, ngân hàng gửi webhook, phần mềm đối soát và cập nhật đơn
Luồng thanh toán VietQR và đối soát tự động

Bước 1: Chuẩn bị tài khoản nhận và nguồn thông báo giao dịch

Để đối soát tự động, bạn cần hai thứ: tài khoản ngân hàng nhận tiền và một nguồn báo cho phần mềm biết khi có tiền vào. Tạo được QR mà không có nguồn thông báo thì vẫn phải đối soát tay.

Các lựa chọn nguồn thông báo phổ biến:

Nguồn thông báoCách hoạt độngLưu ý
API ngân hàng dành cho doanh nghiệpNgân hàng gửi webhook hoặc cho phép truy vấn lịch sử giao dịchCần đăng ký với ngân hàng, thường yêu cầu tài khoản doanh nghiệp
Đơn vị trung gian thanh toánĐơn vị trung gian theo dõi tài khoản và gửi webhookĐọc kỹ điều khoản bảo mật, phí dịch vụ
Tài khoản định danh/tài khoản ảo theo đơnMỗi đơn nhận tiền vào một số tài khoản riêngĐối soát rất chính xác, tuỳ ngân hàng hỗ trợ

Biểu phí, điều kiện và thủ tục thay đổi theo từng ngân hàng và đơn vị, hãy kiểm tra trên trang chính thức trước khi chọn. Ưu tiên giải pháp có webhook kèm chữ ký xác thực và có môi trường thử nghiệm (sandbox).

Bước 2: Quy ước mã đơn và nội dung chuyển khoản

Nội dung chuyển khoản là "chìa khoá" để ghép giao dịch với đơn hàng. Mã đơn cần ngắn, duy nhất, không dấu và dễ nhận diện.

Quy ước mẫu cho một cửa hàng mỹ phẩm hư cấu tên Lam Hương:

  • Tiền tố cố định: LH.
  • Theo sau là số đơn tăng dần hoặc chuỗi ngẫu nhiên: LH10482.
  • Nội dung chuyển khoản chỉ gồm mã đơn, không thêm ký tự đặc biệt.

Tránh dùng dấu tiếng Việt, khoảng trắng thừa hay ký tự như #, /, vì một số ngân hàng có thể bỏ hoặc đổi ký tự khi chuyển nội dung sang ngân hàng nhận. Khi đối soát, hệ thống nên tìm mã đơn bằng biểu thức chính quy (ví dụ LH\d{5}) thay vì so sánh toàn bộ chuỗi, vì ngân hàng có thể chèn thêm thông tin vào nội dung.

Bước 3: Tạo mã QR động cho từng đơn

QR động là mã QR sinh riêng cho một giao dịch, chứa sẵn số tiền và nội dung. Chuỗi dữ liệu bên trong tuân theo cấu trúc EMVCo: mỗi trường gồm mã trường, độ dài và giá trị, kết thúc bằng mã kiểm tra CRC.

Các thông tin chính cần đưa vào:

  • Mã ngân hàng (mã BIN của ngân hàng nhận) và số tài khoản nhận.
  • Số tiền bằng đồng Việt Nam (mã tiền tệ 704).
  • Nội dung chứa mã đơn ở bước 2.

Bạn có ba cách để sinh QR: dùng thư viện mã nguồn mở tạo chuỗi theo chuẩn VietQR, dùng chức năng tạo QR từ API ngân hàng, hoặc dùng dịch vụ của đơn vị trung gian. Dù chọn cách nào, hãy sinh QR ở phía máy chủ dựa trên đơn đã lưu trong cơ sở dữ liệu, không lấy số tiền từ trình duyệt gửi lên, để tránh bị sửa số tiền.

Sau khi tạo, quét thử bằng vài ứng dụng ngân hàng khác nhau để chắc chắn hiển thị đúng tên chủ tài khoản, số tiền và nội dung.

Bước 4: Hiển thị QR trên trang thanh toán

Trang thanh toán cần hiển thị QR rõ ràng, có thông tin dự phòng và tự cập nhật trạng thái. Khách nên biết ngay khi thanh toán thành công mà không phải gọi hỏi.

Trang thanh toán tốt nên có:

  1. Ảnh QR đủ lớn, có nút tải ảnh để khách đang dùng điện thoại có thể mở bằng ứng dụng ngân hàng.
  2. Thông tin chuyển khoản dạng chữ: ngân hàng, số tài khoản, tên chủ tài khoản, số tiền, nội dung, kèm nút sao chép.
  3. Thời hạn thanh toán, ví dụ 15 phút; hết hạn thì đơn huỷ giữ hàng.
  4. Trạng thái cập nhật tự động bằng cách hỏi máy chủ định kỳ vài giây một lần hoặc dùng kết nối thời gian thực.
  5. Lưu ý: "Vui lòng giữ nguyên nội dung chuyển khoản".

Bước 5: Nhận webhook giao dịch

Webhook là cách ngân hàng hoặc đơn vị trung gian chủ động gọi vào máy chủ của bạn mỗi khi có giao dịch. Bạn cần một endpoint an toàn để nhận, xác thực và lưu dữ liệu này. Nếu chưa quen khái niệm, bài API là gì giải thích API và webhook bằng ví dụ dễ hiểu.

Mỗi nhà cung cấp có định dạng riêng, nhưng dữ liệu thường tương tự ví dụ minh hoạ sau (tên trường do nhà cung cấp quy định):

{
  "transactionId": "FT2611170001234",
  "accountNumber": "0123456789",
  "amount": 450000,
  "description": "LH10482 CHUYEN TIEN",
  "transactionTime": "2026-11-17T09:15:42+07:00",
  "type": "credit"
}

Kèm theo là một header chứa chữ ký, thường là HMAC-SHA256 của nội dung với khoá bí mật dùng chung. Đoạn mã Node.js minh hoạ cách kiểm tra:

import crypto from 'node:crypto';

function verifySignature(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// secret lấy từ biến môi trường, ví dụ process.env.PAYMENT_WEBHOOK_SECRET

Nguyên tắc khi xây endpoint:

  • Chỉ chấp nhận HTTPS, kiểm tra chữ ký trước khi xử lý.
  • Lưu toàn bộ dữ liệu gốc vào bảng giao dịch để tra cứu khi có tranh chấp.
  • Dùng transactionId làm khoá duy nhất để không xử lý trùng nếu webhook được gửi lại.
  • Trả phản hồi thành công nhanh, xử lý nặng (gửi email, cập nhật kho) đưa vào hàng đợi.

Bước 6: Đối soát và cập nhật đơn hàng

Đối soát là ghép giao dịch với đơn hàng dựa trên mã đơn và số tiền. Khi khớp hoàn toàn, hệ thống tự cập nhật đơn mà không cần người can thiệp.

Logic đối soát cơ bản:

  1. Tách mã đơn từ nội dung bằng biểu thức chính quy.
  2. Tìm đơn đang chờ thanh toán có mã đó.
  3. So số tiền nhận được với số tiền đơn.
  4. Nếu khớp: đánh dấu "đã thanh toán", lưu mã giao dịch, gửi xác nhận cho khách qua email hoặc Zalo, chuyển đơn sang bộ phận xử lý.
  5. Nếu không khớp: đưa vào hàng chờ ngoại lệ ở bước 7.

Nếu đơn cần xuất hoá đơn, bước này cũng là điểm kích hoạt quy trình tích hợp hoá đơn điện tử để hoá đơn được tạo ngay sau khi tiền về.

Bước 7: Xử lý ngoại lệ và báo cáo

Không phải giao dịch nào cũng khớp hoàn hảo. Một quy trình xử lý ngoại lệ rõ ràng giúp không bỏ sót tiền của khách và không giao hàng khi chưa nhận đủ tiền.

Tình huốngHệ thống làm gìNgười làm gì
Chuyển thiếu tiềnGiữ đơn ở trạng thái "thanh toán một phần"Liên hệ khách bổ sung hoặc hoàn tiền
Chuyển thừa tiềnĐánh dấu đã thanh toán, ghi nhận phần thừaHoàn phần thừa theo chính sách
Sai hoặc thiếu nội dungĐưa vào danh sách "chưa xác định"Đối chiếu theo số tiền, thời gian, tên người chuyển
Chuyển hai lần cho một đơnGiao dịch thứ hai không gán vào đơnXác nhận với khách và hoàn tiền
Tiền về sau khi đơn hết hạnBáo cho nhân viênMở lại đơn hoặc hoàn tiền
Checklist vận hành tích hợp thanh toán VietQR hằng ngày: xử lý giao dịch chưa xác định, đối chiếu tổng tiền với sao kê ngân hàng
Checklist vận hành thanh toán VietQR mỗi ngày

Cuối ngày, hệ thống nên xuất báo cáo đối soát: tổng tiền theo phần mềm so với tổng tiền theo sao kê ngân hàng. Chênh lệch dù nhỏ cũng cần tìm ra nguyên nhân.

Tóm tắt và bước tiếp theo

Tích hợp thanh toán VietQR gồm 7 bước: chuẩn bị tài khoản và nguồn thông báo, quy ước mã đơn, tạo QR động, hiển thị trang thanh toán, nhận webhook, đối soát và xử lý ngoại lệ. Phần khó nhất không phải tạo QR mà là đối soát chính xác và an toàn, vì vậy hãy đầu tư vào xác thực webhook và quy trình xử lý ngoại lệ.

Nếu bạn muốn thêm thanh toán VietQR vào website hoặc phần mềm quản lý bán hàng đang dùng, ULI – công ty phần mềm có thể khảo sát và tích hợp theo ngân hàng của bạn. Hãy liên hệ ULI để được tư vấn.

Câu hỏi thường gặp

Tích hợp VietQR có mất phí không?

Tạo mã QR theo chuẩn VietQR không phát sinh phí từ phía khách quét. Phí có thể phát sinh ở dịch vụ nhận thông báo giao dịch, API ngân hàng hoặc đơn vị trung gian. Bạn nên xem biểu phí chính thức của ngân hàng hoặc đơn vị cung cấp.

QR tĩnh và QR động khác nhau thế nào?

QR tĩnh chỉ chứa thông tin tài khoản, khách phải tự nhập số tiền và nội dung. QR động được tạo cho từng giao dịch, chứa sẵn số tiền và nội dung có mã đơn, nên phù hợp để đối soát tự động.

Khách chuyển khoản nhưng sửa nội dung thì sao?

Hệ thống sẽ không tìm thấy mã đơn và đưa giao dịch vào danh sách chờ xử lý. Kế toán đối chiếu thủ công theo số tiền, thời gian, tên người chuyển rồi gán vào đơn đúng.

Có cần đăng ký với NAPAS để dùng VietQR không?

Thông thường doanh nghiệp không làm việc trực tiếp với NAPAS mà dùng tài khoản tại ngân hàng thành viên hỗ trợ VietQR. Điều kiện cụ thể do ngân hàng quy định, bạn nên hỏi ngân hàng đang dùng.

VietQR có thay được cổng thanh toán thẻ không?

VietQR phù hợp cho thanh toán chuyển khoản trong nước. Nếu cần nhận thẻ quốc tế, trả góp hay ví điện tử, bạn vẫn cần cổng thanh toán; hai phương thức có thể dùng song song.

Đội ngũ ULI

Biên soạn bởi đội phát triển phần mềm, thiết kế website và SEO của ULI – công ty phần mềm (uli.vn). Nội dung được rà soát và cập nhật định kỳ.

Bài viết liên quan

Mẫu website gợi ý

Tất cả mẫu →

Cần một website chuẩn SEO & GEO cho doanh nghiệp?

Chọn một mẫu trong kho giao diện, ULI tuỳ biến theo thương hiệu, tối ưu tốc độ, schema, sitemap, llms.txt và bàn giao trọn gói.