TÀI LIỆU HƯỚNG DẪN

Chuẩn kết nối API cho đối tác merchant

1. Thông Tin Cần Chuẩn Bị Trước Khi Cấu Hình

Để cấu hình kết nối API với VietQR, đối tác vui lòng cung cấp và đối chiếu các thông tin dưới đây trước khi bắt đầu.

Liên kết tham khảo

Nhóm Zalo hỗ trợ test: https://zalo.me/g/wbclso803

Biểu mẫu thông tin ký hợp đồng

Đăng ký merchant VietQR

Tài liệu API service

2. Cấu Trúc Triển Khai — 5 Phần

Quá trình triển khai và kiểm thử kết nối API VietQR gồm 5 phần chính, thực hiện tuần tự:

1.     Implement Get Token API — triển khai API lấy token xác thực

2.     Execute Transaction Sync API — đồng bộ giao dịch/biến động số dư

3.     Call Get Token API — gọi thử API lấy token

4.     Generate VietQR Code API — sinh mã VietQR

5.     Test Callback — kiểm thử luồng callback

3. Hướng Dẫn Thực Hiện Từng Bước

Bước 1 — Cấu hình và kết nối API

Khách hàng thực hiện lần lượt theo đúng thứ tự sau, sau đó mới bắt đầu test kết nối:

✔ Bước 1: Triển khai API Get Token

✔ Bước 2: Triển khai API Transaction Sync

✔ Bước 3: Gọi thử API Get Token

✔ Bước 4: Triển khai API Generate VietQR Code

✔ Bước 5: Gọi thử API Test Callback

Bước 2 — Kiểm tra dữ liệu

•      Kiểm tra lại dữ liệu đã cấu hình tại Bước 1 và Bước 2 để đảm bảo tính chính xác.

•      Nếu phát hiện lỗi, cần chỉnh sửa trước khi tiếp tục các bước tiếp theo.

Lưu ý: Sau khi hoàn tất các bước trên, khách hàng có thể tiến hành kiểm thử toàn bộ quy trình để đảm bảo hệ thống hoạt động đúng yêu cầu.

4. Hướng Dẫn Sau Khi Hoàn Tất Test (Go-live)

Sau khi test thành công, khách hàng sẽ được nghiệm thu và triển khai trên môi trường dịch vụ thực của tài khoản ngân hàng.

Liên hệ bộ phận kinh doanh (Khối Khách hàng Doanh nghiệp số) để được hỗ trợ triển khai:

5. Mô Tả Chi Tiết Tài Liệu API

5.1. API Get Token

API xác thực, dùng để lấy token truy cập trước khi gọi các API khác (Transaction Sync, Generate VietQR Code, Test Callback).

5.2. API Transaction Sync

Áp dụng để đối tác đồng bộ biến động số dư do VietQR trả về, theo 5 bước sau:

Bước 1: Cấp quyền truy cập API

•      Đối tác cần cấp quyền cho VietQR bằng cách thiết lập quyền truy cập vào API Transaction Sync.

•      Cấu hình điểm nhận dữ liệu (webhook) để VietQR có thể gửi thông tin biến động số dư.

Bước 2: Cấu hình đầu hứng (webhook)

•      Đối tác cung cấp URL endpoint để nhận dữ liệu.

•      Đảm bảo endpoint hỗ trợ nhận dữ liệu từ VietQR qua phương thức POST.

•      Kiểm tra bảo mật, xác thực request gửi đến từ VietQR.

Bước 3: VietQR gửi dữ liệu biến động số dư

Khi có giao dịch mới, VietQR gửi thông tin biến động số dư theo thời gian thực đến webhook của đối tác. Dữ liệu bao gồm:

Bước 4: Xác nhận và xử lý dữ liệu từ VietQR

•      Đối tác nhận request từ VietQR và xác thực dữ liệu.

•      Lưu trữ hoặc xử lý thông tin theo nhu cầu (cập nhật hệ thống, hiển thị trên ứng dụng, v.v.).

•      Trả về response 200 OK để xác nhận đã nhận dữ liệu thành công.

Bước 5: Kiểm tra và giám sát

•      Định kỳ kiểm tra log để đảm bảo không có lỗi kết nối.

•      Nếu có lỗi (mất kết nối, dữ liệu sai, v.v.), kiểm tra lại cấu hình webhook hoặc liên hệ bộ phận hỗ trợ của VietQR.

Lưu ý: VietQR có thể yêu cầu xác thực webhook bằng token hoặc chữ ký số để đảm bảo an toàn khi truyền dữ liệu.