💫API VIETQR - Host2Client

Tài liệu API VIETQR - Host to Client

TÀI LIỆU TÍCH HỢP DỊCH VỤ THANH TOÁN QUA MÃ VIETQR

I. Ngữ cảnh

Mô tả tài liệu

• Dịch vụ dành cho các đối tác nền tảng có nhu cầu tích hợp tính năng thanh toán qua mã VietQR.

• Dịch vụ cho phép khách hàng thực hiện các giao dịch thanh toán bằng mã VietQR trực tiếp trên các nền tảng tích hợp.

• Tài liệu này cung cấp thông tin nghiệp vụ:

  • Kích hoạt dịch vụ thanh toán bằng mã VietQR.

  • Đồng bộ thông tin thanh toán, thông tin tài khoản ngân hàng của khách hàng.

  • Tạo mã VietQR.

  • Nhận thông báo biến động số dư.

• Tài liệu này cung cấp thông tin kỹ thuật:

  • Thông tin bảo mật.

  • Cấu hình kết nối dịch vụ.

  • Bộ API Services kết nối dịch vụ.

• Thuật ngữ viết tắt:

Thuật ngữ	Chú thích nội dung
ĐTNT	Đối tác nền tảng
KH	Khách hàng
TK/TKNH	Tài khoản/Tài khoản ngân hàng
LK	Liên kết
GD	Giao dịch
TT	Thanh toán
BĐSD	Biến động số dư

Nghiệp vụ

2.1. Luồng nghiệp vụ

2.2. Mô tả luồng nghiệp vụ

2.2.1. Luồng nghiệp vụ kích hoạt dịch vụ thanh toán bằng mã VietQR

Bước thực hiện	Người thực hiện	Hệ thống	Mô tả
Pre-condition	KH		Đã liên kết TK MBBank hoặc TK BIDV trên hệ thống VietQR.
1	KH	ĐTNT	KH đăng ký dịch vụ thanh toán bằng mã VietQR trên ĐTNT.
2	ĐTNT	VietQR	ĐTNT gọi API lấy mã QR xác thực định danh. Input: key/domain/userId dùng để định danh KH trên ĐTNT.
3	KH	VietQR	KH truy cập vào app VietQR và quét mã QR xác thực định danh. VietQR kiểm tra thông tin QR xác thực định danh. Nếu QR xác thực định danh không khả dụng: VietQR báo lỗi. Nếu QR xác thực định danh khả dụng: KH truy cập vào form kích hoạt sử dụng dịch vụ/cập nhật thông tin sử dụng dịch vụ.
4	KH	VietQR	KH nhập thông tin để kích hoạt và sử dụng dịch vụ thanh toán bằng mã VietQR trên ĐTNT. Input: Thông tin TKNH đã liên kết.
5	VietQR	ĐTNT	VietQR kiểm tra thông tin hợp lệ của KH: Nếu thông tin hợp lệ: VietQR thông báo cho ĐTNT trạng thái kích hoạt/cập nhật thông tin thành công. ĐTNT hiển thị thông tin đã kích hoạt của KH trên hệ thống. Nếu thông tin không hợp lệ: VietQR hiển thị thông tin lỗi cho KH.

2.2.2. Luồng nghiệp vụ thanh toán qua mã VietQR

Bước thực hiện	Người thực hiện	Hệ thống	Mô tả
Pre-condition	KH		Đã liên kết TK MBBank hoặc TK BIDV trên hệ thống VietQR. Đã kích hoạt thành công dịch vụ thanh toán mã VietQR trên ĐTNT.
1	KH	ĐTNT	Tạo đơn hàng/giao dịch cần thanh toán trên hệ thống ĐTNT.
2	ĐTNT	VietQR	ĐTNT gửi yêu cầu tạo mã VietQR giao dịch. VietQR trả về thông tin mã VietQR giao dịch.
3	KH	ĐTNT	Khách hàng thực hiện thanh toán qua mã VietQR ĐTNT.
4	VietQR	ĐTNT	VietQR trả thông tin BĐSD cho ĐTNT, đánh dấu giao dịch TT thành công.

2.3. Kích hoạt dịch vụ thanh toán bằng mã VietQR

• Nghiệp vụ kích hoạt dịch vụ thanh toán bằng mã VietQR nhằm mục đích là xác thực thông tin của người dùng đăng ký dịch vụ. Đồng thời hệ thống VietQR và ĐTNT ghi nhận thông tin đăng ký dịch vụ.

• Hệ thống VietQR cần xác nhận được khách hàng đăng ký dịch vụ thanh toán qua mã VietQR thông qua nền tảng nào. Các thông tin liên quan tới thông tin TKNH, thông tin TT.

2.4. Tạo mã VietQR

• ĐTNT sử dụng API tạo mã VietQR để tạo mã QR, mã VietQR này ứng với 1 giao dịch mới có trạng thái “Chờ TT”.

• ĐTNT có thể đánh dấu giao dịch thông qua các tham số:

  • orderId: Là mã đơn hàng.

  • terminalCode: Là mã cửa hàng/điểm bán.

• Thời hạn khả dụng cho 1 mã VietQR là 15 phút. Nếu hết thời gian khả dụng cho 1 mã VietQR thanh toán, KH/ĐTNT phải tạo lại một mã VietQR thanh toán mới.

• Để sử dụng công cụ quản lý và thống kê cửa hàng hiệu quả trên hệ thống VietQR, KH cần thực hiện bước đồng bộ cửa hàng/điểm bán của mình lên hệ thống VietQR. Thông tin liên hệ kỹ thuật của VietQR.

2.5. Nhận thông báo Biến động số dư

• Hiện tại, hệ thống VietQR khả dụng dịch vụ nhận thông báo biến động số dư cho TKNH BIDV và MBBank.

• Hệ thống VietQR chấp nhận loại TKNH cá nhân và TKNH doanh nghiệp.

• Đối soát là quy trình đánh dấu trạng thái giao dịch. Một GD mới được khởi tạo với trạng thái là “Chờ TT”, khi KH TT thành công và hệ thống VietQR khớp được GD, GD được chuyển trạng thái từ “Chờ TT” sang “TT thành công”.

• Các lưu ý khi nhận BĐSD:

  • Đối với KH sử dụng gói dịch vụ VietQR Plus:

    • Khi quét mã VietQR để thanh toán, nếu KH thay đổi số tiền + nội dung chuyển khoản, hệ thống VietQR sẽ không đối soát được giao dịch tương ứng với mã VietQR đã tạo.

    • Trong trường hợp không đối soát thành công, hệ thống VietQR vẫn ghi nhận KH có GD mới. Tuy nhiên, giao dịch được tạo từ mã VietQR trước đó sẽ không được đánh dấu trạng thái “TT thành công”.

    • Trong trường hợp đối soát thành công, hệ thống VietQR ghi nhận KH đã “TT thành công” giao dịch được tạo từ mã VietQR trước đó.

  • Đối với KH sử dụng gói dịch vụ VietQR Pro:

    • Khi quét mã VietQR để thanh toán, KH có thể thay đổi nội dung thanh toán mà không ảnh hưởng tới quy trình đối soát giao dịch.

    • Khi quét mã VietQR để thanh toán, trong trường hợp KH thay đổi số tiền chuyển khoản, hệ thống sẽ đánh dấu GD thất bại và từ chối chuyển khoản. Thông báo sẽ được hiển thị trực tiếp trên các app banking/ví điện tử của phía KH chuyển tiền.

    • Trong trường hợp đối soát thành công, hệ thống VietQR ghi nhận KH đã “TT thành công” giao dịch được tạo từ mã VietQR trước đó.

II. Thông tin kỹ thuật

Quy định về xác thực bảo mật

• ĐTNT sử dụng API Get Certificate để lấy thông tin và hiển thị mã QR xác thực định danh KH trên hệ thống ĐTNT.

• ĐTNT sử dụng API Get User Information để lấy thông tin xác thực Bearer Token. Đoạn Bearer Token này dùng để gọi API Tạo mã VietQR.

• VietQR sẽ cung cấp 1 đoạn “secretKey” cho các ĐTNT để xác thực và mã hoá thông tin.

• Quy định mã hoá thông tin dựa vào “secretKey”:

  • Secret Key: Liên hệ kỹ thuật VietQR để được cung cấp thông tin.

  • Đối với API Get Certificate và API Get User Information, hệ thống yêu cầu field “checksum” trong Request Body. Phía VietQR cung cấp thông tin để ĐTNT generate checksum:

API	Quy định checksum
API Get Certificate	MD5(secretKey + userId)
API Get User Information	MD5(secretKey + userId)

• Quy định về thông tin xác thực Bearer Token:

  • Thời gian hiệu lực: 59 giây.

  • Đoạn Bearer Token đánh dấu thông tin khách hàng sử dụng dịch vụ thanh toán qua mã VietQR, được sử dụng trên hệ thống ĐTNT. Vì vậy, ĐTNT không thể sử dụng đoạn 1 Bearer Token cho tất cả các KH.

Quy định về quy trình kết nối dịch vụ

• ĐTNT và KH tuân thủ theo quy trình kết nối dịch vụ để đảm bảo hệ thống vận hành một cách hiệu quả nhất, giảm thiểu rủi ro không mong muốn.

• ĐTNT có 2 phương án để nhận phản hồi thông tin từ phía VietQR trả về:

  • Phương án 1: Đối tác thực hiện implement webhook để nhận thông tin phản hồi. Hệ thống VietQR yêu cầu các webhook phục vụ cho các mục đích sau:

    • Nhận thông báo kích hoạt dịch vụ thành công.

    • Nhận thông tin hiển thị mã VietQR.

    • Nhận thông báo BĐSD.

  • Phương án 2: Đối tác thực hiện implement Websocket của phía VietQR cung cấp để nhận thông tin phản hồi. Websocket sẽ phản hồi cho các mục đích sau:

    • Nhận thông báo kích hoạt dịch vụ thành công.

    • Nhận thông tin hiển thị mã VietQR.

    • Nhận thông báo BĐSD.

• Thông tin webhook yêu cầu đáp ứng bảo mật bằng field “checksum”.

• Websocket được trả về tương ứng với mỗi KH đăng ký dịch vụ. ĐTNT lấy thông tin webhook từ API Get User Information.

III. Mô tả APIs và Web Socket

API Get Certificate

• 1. URL: http://112.78.1.209:8084/vqr/api/tid/sync-certificate

  2. Method: POST

  3. Request Body:

• Xác thực: Bearer auth.

Field	Type	Description
webhook	String	webhook dùng để đăng ký dịch vụ
checkSum	String	Do VietQR cung cấp với định dạng MD5(secretKey + userId)

• 1. Response:

Field	Type	Description
qrCertificate	String	Mã QR dùng để hiển thị đối với máy box QR mới được lưu dưới firmware
certificateId	String	certificateId (Dùng để kết nối websocket)

API Get User Information

• URL: https://api.vietqr.org/vqr/api/tid/infomation/{boxCode}

• Method: GET

• Xác thực: Bearer.

• Mô tả:

• API dùng để xem chi tiết thông tin của máy QR Box

• Request Param:

Param	Type	Description
userId	String	Id của user mà muốn lấy thông tin
checkSum	String	Do VietQR cung cấp với định dạng MD5(secretKey + userId)

• Response:

Field	Type	Description
userId	String	ID của KH
phoneNo	String	Số điện thoại của KH
bankAccount	String	Số TK ngân hàng được liên kết của KH
userBankName	String	Tên chủ TK ngân hàng được liên kết
bankCode	String	Mã của NH
bankShortName	String	Tên viết tắt của ngân hàng
registerPlatform	String	nền tảng đăng ký của KH
address	String	Địa chỉ KH đăng ký
qrCode	String	Mã QR Code hiển thị dùng để thanh toán

API Tạo mã VietQR

• URL: http://112.78.1.209:8084/vqr/api/tid/generate-qr

• Method: POST

• Request Body:

Field	Type	Description
bankAccount	String	Số TK ngân hàng đã liên kết
bankName	String	Tên ngân hàng đã liên kết
bankShortName	String	Tên viết tắt của ngân hàng đã liên kết
userBankName	String	Tên chủ TK ngân hàng đã liên kết
note	String	Ghi chú giao dịch
amount	String	Số tiền gán trên giao dịch
content	String	Nội dung chuyển khoản gán trên giao dịch
imgId	String	Mã id hình ảnh của ngân hàng
qrCode	String	Mã QR Code của giao dịch QR động
transType	String	Loại giao dịch đến “C” hoặc đi “D”
bankCode	String	Mã code của ngân hàng
orderId	String	Mã giao dịch gán với giao dịch
terminalCode	String	Mã code cửa hàng để đối soát

• Response:

Field	Type	Description
status	String	“SUCCESS” or “FAILED”
message	String	SUCCESS: “” FAILED: “E05” or “E46”

Web Socket nhận thông báo

• Websocket:: wss://api.vietqr.org/vqr/socket?userId={userId}

• Mô tả: Web Socket dùng để nhận BĐSD khi có giao dịch tới

• Method: POST

• Response:

Field	Type	Description
notificationType	String	Mã của notificationType ‘N05’: Mã code nhận biết BĐSD tới
notificationId	String	Mã định danh của thông báo lưu dưới hệ thống VietQR
transactionReceiveId	String	Mã định danh của giao dịch lưu dưới hệ thống VietQR
bankAccount	String	Số TK của TK nhận BĐSD
bankName	String	Tên TK ngân hàng của TK nhận BĐSD
bankCode	String	Mã code của TK ngân hàng của TK nhận BĐSD
bankId	String	Mã định danh của TK ngân hàng lưu dưới hệ thống
terminalName	String	Tên cửa hàng (Mặc định ‘’)
terminalCode	String	Mã code của cửa hàng (Mặc định ‘’)
rawTerminalCode	String	Mã code cửa hàng raw (Mặc định ‘’)
content	String	Nội dung chuyển khoản
orderId	String	Mã đơn hàng của giao dịch
referenceNumber	String	Mã code giao dịch của giao dịch
amount	String	Số tiền của giao dịch
timePaid	String	Thời gian thanh toán giao dịch
type	String	Loại giao dịch
time	String	Thời gian tạo giao dịch
refId	String	Mã định danh của giao dịch đánh dấu của ngân hàng
status	String	0: Chờ thanh toán 1: Thành công 2: Đã hủy
traceId	String	Mã trace của transaction
transType	String	C: Giao dịch đến D: Giao dịch đi
urlLink	String	Mặc định ‘’

IV. Mô tả Webhook

• Mô tả: Webhook là một cơ chế cho phép một ứng dụng gửi thông báo hoặc dữ liệu tới các ứng dụng khác một cách tự động khi một sự kiện cụ thể xảy ra.

• Thiết lập webhook: Người dùng hoặc ứng dụng đăng ký một URL (được gọi là webhook endpoint) với một dịch vụ. URL này sẽ nhận các thông báo về sự kiện từ dịch vụ đó.

( VD: https://112.78.1.209:8084/webhook/sync-certificate )

• Khi KH quét mã QR để thanh toán thì hệ thống sẽ gửi yêu cầu POST đến URL đã đăng ký về thông tin của đơn thành mà KH thanh toán