Hướng dẫn tích hợp API nhận Biến động số dư VietQR

Giới thiệu

Dịch vụ API Nhận biến động số dư VietQR giúp hệ thống của đối tác nhận thông tin giao dịch chuyển khoản theo thời gian thực (Real-time) thông qua Webhook. Ngay khi tài khoản ngân hàng phát sinh giao dịch, VietQR sẽ đồng bộ dữ liệu đến hệ thống của đối tác để tự động đối soát, cập nhật trạng thái đơn hàng hoặc thực hiện các nghiệp vụ kinh doanh.

Tài liệu này hướng dẫn toàn bộ quy trình từ đăng ký dịch vụ, cấu hình kết nối, kiểm thử (UAT) đến triển khai chính thức (Go-Live).

1. Đăng ký sử dụng dịch vụ

Để kích hoạt dịch vụ API, đối tác vui lòng đăng ký theo biểu mẫu dưới đây:

Đăng ký dịch vụ

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

Hoặc tự tạo tài khoản tại

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

Sau khi đăng ký, VietQR sẽ tiến hành cấu hình tài khoản và cấp thông tin kết nối.

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

Đối tác chuẩn bị các thông tin sau:

Thông tinMô tảMerchant NameTên doanh nghiệp hoặc cửa hàngAPI Base URLĐịa chỉ máy chủ tiếp nhận dữ liệuWebhook URLURL nhận Callback từ VietQRURL Path (nếu có)Đường dẫn mở rộngMôi trườngTest hoặc ProductionĐịa chỉ IP (nếu whitelist)Theo yêu cầu hệ thống

3. Thông tin VietQR cung cấp

Sau khi đăng ký thành công, VietQR sẽ cấp:

Thông tinMô tảAPI UsernameTài khoản APIAPI PasswordMật khẩu APIClient ID (nếu có)Định danh ứng dụngSecret KeyKhóa xác thựcMerchant IDĐịnh danh MerchantAPI EndpointĐịa chỉ kết nốiTài khoản TestMôi trường UAT

4. Tài liệu dành cho lập trình viên

Portal Developer

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

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

https://zalo.me/g/wbclso803

5. Quy trình tích hợp API

Quá trình triển khai được thực hiện theo đúng thứ tự sau:

Bước 1

Triển khai API Authentication (Get Token)

↓

Bước 2

Triển khai API Transaction Sync

↓

Bước 3

Xác thực và lấy Access Token

↓

Bước 4

Sinh mã thanh toán VietQR

↓

Bước 5

Kiểm thử Callback nhận biến động số dư

↓

Kiểm thử hoàn chỉnh

↓

Go Live

6. Quy trình kiểm thử (UAT)

Bước 1. Authentication

Triển khai API Get Token để lấy Access Token.

Token sẽ được sử dụng trong tất cả các API tiếp theo.

Bước 2. Transaction Sync

Cấu hình Webhook để nhận dữ liệu biến động số dư.

Đối tác cần cung cấp:

• URL Webhook

• Phương thức POST

• HTTPS

• JSON Request

Bước 3. Lấy Access Token

Gọi API Authentication.

Nếu thành công hệ thống trả về:

• access_token

• expires_in

• token_type

Bước 4. Sinh mã VietQR

Gọi API Generate VietQR.

Kiểm tra:

• QR được tạo thành công

• Nội dung QR chính xác

• Thông tin tài khoản

• Nội dung chuyển khoản

Bước 5. Kiểm thử Callback

Sau khi chuyển khoản thành công,

VietQR sẽ tự động gửi Callback đến Webhook của đối tác.

Đối tác cần:

• Xác thực Request

• Kiểm tra chữ ký (nếu có)

• Lưu dữ liệu

• Trả về HTTP 200 OK

Nếu hệ thống không trả về HTTP 200, VietQR sẽ thực hiện gửi lại theo chính sách Retry.

7. Dữ liệu Callback

Thông tin Callback có thể bao gồm:

• Merchant ID

• Mã giao dịch

• Transaction ID

• Bank Transaction ID

• Số tiền

• Số dư sau giao dịch

• Nội dung chuyển khoản

• Thời gian giao dịch

• Mã QR

• Trạng thái giao dịch

• Thông tin tài khoản

(Chi tiết tham khảo phần API Callback)

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

Bước 1

Khách hàng tạo mã VietQR thông qua API.

↓

Bước 2

Người mua thực hiện thanh toán.

↓

Bước 3

Ngân hàng ghi nhận giao dịch.

↓

Bước 4

Hệ thống VietQR nhận biến động số dư theo thời gian thực.

↓

Bước 5

VietQR gửi Callback đến Webhook của đối tác.

↓

Bước 6

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

↓

Bước 7

Cập nhật trạng thái đơn hàng hoặc nghiệp vụ kinh doanh.

↓

Bước 8

Trả về HTTP Status 200 OK.

9. Kiểm tra sau khi tích hợp

Đối tác nên kiểm tra:

• Token còn hiệu lực

• Webhook hoạt động

• HTTPS hợp lệ

• Firewall không chặn IP VietQR

• Callback trả về HTTP 200

• Đối soát số tiền chính xác

• Nhật ký (Logs) không phát sinh lỗi

• Retry hoạt động đúng

10. Go-Live

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

Các bước thực hiện:

1. Kiểm tra toàn bộ API.

2. Chuyển Endpoint sang Production.

3. Cập nhật thông tin Merchant Production.

4. Thực hiện giao dịch kiểm tra.

5. Chính thức đưa hệ thống vào vận hành.

11. Hỗ trợ kỹ thuật

Trong quá trình tích hợp, nếu cần hỗ trợ vui lòng tham gia nhóm kỹ thuật:

Zalo Support

https://zalo.me/g/wbclso803

12. Liên hệ triển khai dịch vụ

Sau khi hoàn tất kiểm thử và có nhu cầu triển khai chính thức, vui lòng liên hệ bộ phận kinh doanh của VietQR.

Họ tênĐiện thoạiEmailLê Hương0968 383 [email protected]Đạo Nguyễn0923 006 234[email protected]Tạ Quang Tuấn0966 266 049[email protected]Hoàng Văn Hiển0565 606 789[email protected]Thịnh Nguyễn0936 381 333[email protected]Tuấn Phạm0922 333 636[email protected]Hotline0939 603 [email protected]

Tài liệu API

Tài liệu kỹ thuật bao gồm:

• API Authentication (Get Token)

• API Generate VietQR

• API Transaction Sync

• API Balance Callback

• API Test Callback

• API Error Code

• API Security

• Webhook Specification

• Retry Policy

• Sandbox Environment

• Production Environment

Tài liệu được cập nhật thường xuyên trên cổng Developer VietQR, giúp đối tác dễ dàng triển khai, kiểm thử và vận hành dịch vụ.