Hướng dẫn tích hợp và kiểm thử API VietQR

Giới thiệu

Tài liệu này hướng dẫn đối tác cấu hình, tích hợp và kiểm thử bộ API của VietQR nhằm kết nối hệ thống nhận biến động số dư, tạo mã VietQR và đồng bộ dữ liệu thanh toán theo thời gian thực.

Để quá trình tích hợp diễn ra thuận lợi, vui lòng chuẩn bị đầy đủ các thông tin kết nối và thực hiện theo đúng quy trình hướng dẫn trong tài liệu này.

Thông tin đối tác cần cung cấp

Trước khi cấp quyền sử dụng API, đối tác vui lòng cung cấp các thông tin sau:

Thông tinMô tảMerchant NameTên cửa hàng hoặc doanh nghiệp hiển thị trên hệ thống VietQRAPI Base URLĐịa chỉ máy chủ API của đối tácAPI Path (Suffix)Đường dẫn API nhận dữ liệu (nếu có)Webhook URLURL nhận dữ liệu biến động số dư từ VietQRUsernameTên đăng nhập API (đối tác tự đặt hoặc VietQR cấp)PasswordMật khẩu API (đối tác tự đặt hoặc VietQR cấp)Secret Key / API KeyKhóa xác thực dùng để ký và xác minh dữ liệu

Thông tin VietQR cung cấp

Sau khi hoàn tất đăng ký dịch vụ, VietQR sẽ cung cấp:

Merchant ID
API Username
API Password
API Key / Secret Key
Thông tin môi trường Test (Sandbox)
Thông tin môi trường Production
Tài liệu API
Bộ dữ liệu mẫu để kiểm thử

Trong trường hợp đối tác sử dụng tài khoản VietQR riêng, có thể tự cấu hình thông tin API sau khi hoàn tất đăng ký.

Đăng ký tài khoản VietQR

Đăng ký tài khoản Merchant:

https://pro.vietqr.vn/merchant-register

Thông tin dịch vụ API:

https://pro.vietqr.vn/api-service/3a4fb799-7cae-47e4-a56d-59d4944313e3

Nhóm hỗ trợ kỹ thuật

Nhóm Zalo hỗ trợ tích hợp:

https://zalo.me/g/wbclso803

Đăng ký thông tin triển khai:

https://docs.google.com/forms/d/e/1FAIpQLSfNywc4SAYleFZ-d7faUvUyzXzNlu0ahHsAd_H43AqO-opsZg/viewform

Quy trình triển khai

Việc tích hợp API được thực hiện theo 05 bước tuần tự.

Bước 1
Triển khai API Get Token
        │
        ▼
Bước 2
Triển khai Transaction Sync API
        │
        ▼
Bước 3
Thực hiện Call Get Token API
        │
        ▼
Bước 4
Generate VietQR Code API
        │
        ▼
Bước 5
Kiểm thử Callback/Webhook

Đối tác cần hoàn thành lần lượt từng bước trước khi chuyển sang bước tiếp theo.

Nội dung tài liệu

Bộ tài liệu API bao gồm:

1. API Get Token

Sử dụng để xác thực và lấy Access Token trước khi gọi các API khác.

2. Transaction Sync API

Đồng bộ dữ liệu biến động số dư giữa VietQR và hệ thống của đối tác.

3. Call Get Token API

Ví dụ gọi API lấy Token và cách sử dụng Token trong các request tiếp theo.

4. Generate VietQR Code API

Sinh mã VietQR động hoặc tĩnh phục vụ thanh toán.

5. Test Callback API

Kiểm thử việc VietQR gửi dữ liệu giao dịch về Webhook của đối tác.

Hướng dẫn kiểm thử

Bước 1. Cấu hình kết nối

Hoàn thành việc cấu hình:

Merchant
API URL
Username
Password
Secret Key
Webhook URL

Bước 2. Kiểm tra cấu hình

Đảm bảo:

URL chính xác
Secret Key đúng
Username/Password hoạt động
Webhook có thể truy cập từ Internet
Firewall không chặn IP VietQR

Bước 3. Kiểm thử xác thực

Thực hiện gọi API Get Token.

Nếu nhận được Access Token nghĩa là kết nối thành công.

Bước 4. Kiểm thử giao dịch

Tiến hành:

Sinh VietQR
Thanh toán thử
Kiểm tra Transaction Sync
Kiểm tra Callback

Bước 5. Kiểm thử toàn bộ quy trình

Xác nhận:

✅ Lấy Token thành công

✅ Sinh QR thành công

✅ Thanh toán thành công

✅ Nhận Callback

✅ Đồng bộ giao dịch

Nếu toàn bộ bước trên đều thành công, hệ thống đã sẵn sàng Go-Live.

Hướng dẫn Go-Live

Sau khi hoàn tất kiểm thử và được VietQR nghiệm thu, hệ thống sẽ được chuyển sang môi trường Production.

Lúc này đối tác sẽ được:

cấp API Production
cấp Merchant Production
cấu hình tài khoản ngân hàng thật
kích hoạt dịch vụ chính thức

Quy trình nhận biến động số dư

Bước 1

VietQR xác thực đối tác bằng Access Token.

↓

Bước 2

Đối tác tạo VietQR hoặc Virtual Account.

↓

Bước 3

Khách hàng thực hiện thanh toán.

↓

Bước 4

Ngân hàng phát sinh biến động số dư.

↓

Bước 5

VietQR nhận dữ liệu giao dịch.

↓

Bước 6

VietQR gửi Callback/Webhook đến hệ thống đối tác.

↓

Bước 7

Đối tác xác thực dữ liệu.

↓

Bước 8

Lưu giao dịch vào hệ thống và phản hồi HTTP 200 OK.

Lưu ý khi triển khai

Webhook phải hỗ trợ phương thức POST.
Hệ thống phải phản hồi HTTP 200 OK sau khi xử lý thành công.
Khuyến nghị sử dụng HTTPS/TLS 1.2 trở lên.
Nên xác thực dữ liệu bằng API Key, Secret Key, hoặc chữ ký số (HMAC Signature).
Thiết lập cơ chế ghi log và retry để đảm bảo không mất dữ liệu khi xảy ra sự cố.

Thông tin hỗ trợ

Bộ phậnLiên hệHotline0939 603 636Emailsales@vietqr.vnEmail[email protected]