API VÀ TÀI LIỆU KỸ THUẬT
Tóm tắt
Tài liệu này cung cấp hướng dẫn tổng quan để đối tác kết nối, tích hợp và sử dụng dịch vụ API VietQR trên môi trường Production tại https://api.vietqr.org. Bộ API VietQR hỗ trợ các loại mã QR động, tĩnh và bán động để tích hợp quy trình thanh toán QR vào hệ thống của mình. Các nhóm API dịch vụ bao gồm Get Token API, Generate QR Code API, Create terminalCode API, Transaction Sync API, Check Transaction API, Refund API. Quy trình tích hợp cơ bản gồm xác thực, tạo mã QR, khách hàng thanh toán, nhận dữ liệu giao dịch, đối soát và tra cứu giao dịch. Đối tác sử dụng Bearer Token để gọi các API cần xác thực và VietQR sử dụng secretKey và checkSum để tăng cường bảo mật cho yêu cầu API. Tài liệu nhằm giúp đội ngũ kỹ thuật của đối tác nhanh chóng thiết lập kết nối với VietQR, kiểm thử API trên môi trường Production, tích hợp chức năng tạo và thanh toán bằng VietQR, đồng bộ và xử lý dữ liệu giao dịch, quản lý giao dịch theo từng cửa hàng/điểm bán, tra cứu và đối soát giao dịch.
TỔNG QUAN TÀI LIỆU KỸ THUẬT API VIETQR
Tài liệu này cung cấp hướng dẫn tổng quan và các thông tin kỹ thuật cần thiết để đối tác kết nối, tích hợp và sử dụng các dịch vụ API VietQR trên môi trường Production tại https://api.vietqr.org.
Thông qua bộ API VietQR, đối tác có thể tích hợp quy trình thanh toán QR vào hệ thống của mình, từ xác thực kết nối, tạo mã QR, quản lý điểm bán, nhận dữ liệu giao dịch, tra cứu giao dịch đến hoàn tiền. API Generate VietQR Code hỗ trợ các loại mã QR động, QR tĩnh và QR bán động, phù hợp với nhiều mô hình thanh toán và điểm bán khác nhau.
Tổng quan các nhóm API dịch vụ
Nhóm API | Chức năng chính |
|---|---|
Get Token API | Xác thực tài khoản và cấp |
Generate QR Code API | Tạo mã thanh toán VietQR gồm QR động, QR tĩnh và QR bán động theo nhu cầu của đối tác. |
Create terminalCode API | Tạo và đồng bộ thông tin điểm bán/cửa hàng, phục vụ việc quản lý giao dịch theo từng địa điểm. |
Transaction Sync API | Nhận và đồng bộ dữ liệu biến động giao dịch từ hệ thống VietQR về hệ thống của đối tác. |
Check Transaction API | Tra cứu và kiểm tra thông tin giao dịch dựa trên |
Refund API | Cho phép đối tác thực hiện hoàn tiền cho các giao dịch đã thanh toán qua VietQR. API sử dụng |
Quy trình tích hợp tổng quát
Quy trình kết nối cơ bản gồm:
1. Xác thực → 2. Tạo QR → 3. Khách hàng thanh toán → 4. Nhận dữ liệu giao dịch → 5. Đối soát/tra cứu giao dịch → 6. Hoàn tiền khi cần thiết
Đối tác sử dụng API Get Token để lấy Bearer Token, sau đó sử dụng token này để gọi các API cần xác thực. Với dịch vụ hoàn tiền, VietQR sử dụng thêm secretKey và checkSum để tăng cường bảo mật cho yêu cầu API.
Mục đích của tài liệu
Tài liệu được xây dựng nhằm giúp đội ngũ kỹ thuật của đối tác:
Nhanh chóng thiết lập kết nối với VietQR.
Kiểm thử API trên môi trường Production.
Tích hợp chức năng tạo và thanh toán bằng VietQR.
Đồng bộ và xử lý dữ liệu giao dịch.
Quản lý giao dịch theo từng cửa hàng/điểm bán.
Tra cứu và đối soát giao dịch.
Tích hợp chức năng hoàn tiền.
Xử lý các trường hợp bất thường như QR hết hạn, callback lỗi hoặc giao dịch hoàn tiền thất bại.
Ứng dụng khuyến nghị để kiểm thử: Postman.
Các phần tiếp theo của tài liệu sẽ trình bày chi tiết endpoint, phương thức HTTP, header, tham số request, cấu trúc response, cURL mẫu, cơ chế xác thực và các quy định xử lý lỗi cho từng API.