💸API Refund Transaction

TÀI LIỆU TÍCH HỢP DỊCH VỤ HOÀN TIỀN (REFUND)

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 hoàn tiền cho KH sử dụng gói VietQR Pro.

• Dịch vụ cho phép khách hàng thực hiện việc hoàn tiề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 được tích hợp.

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

  • Hoàn tiền đối với giao dịch đã thanh toán

• 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ụ hoàn tiền

  • Bộ API Services dịch vụ hoàn tiền.

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

Thuật ngữ	Chú thích nội dung
ĐT	Đối tác
KH	Khách hàng, người dùng cuối của đối tác
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ụ

Ảnh 1. Khái quát luồng nghiệp vụ hoàn tiền sau khi thanh toán thành công VietQR

Ảnh 2: Mô tả luồng nghiệp vụ hoàn tiền cho gói VietQR Pro

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

Bước thực hiện	Người thực hiện	Hệ thống	Mô tả
Pre-condition	ĐT		- Đã khai báo kết nối đến hệ thống VietQR. - Đã liên kết TK MBBank/BIDV trên hệ thống VietQR. - Sử dụng gói VietQR Pro.
1	ĐT	VietQR	KH yêu cầu hoàn tiền sau khi đã thanh toán thành công và ghi nhận BĐSD
2	VietQR	ĐT	VietQR kiểm tra thông tin: Nếu thông tin không hợp lệ hoặc không khả dụng: VietQR báo lỗi nhận thông tin hoàn tiền không thành công Nếu thông tin hợp lệ: Hệ thống VietQR tiến hành hoàn tiền
3	VietQR	ĐT	VietQR tiến hành hoàn tiền: VietQR sẽ trả thông tin nếu hoàn tiền thành công Người dùng cuối nhận được số tiền hoàn

2.3. Hoàn tiền

• Dịch vụ hoàn tiền khả dụng cho các đối tác sử dụng gói dịch vụ VietQR Pro.

• ĐT sử dụng API hoàn tiền để hoàn tiền cho người dùng cuối.

  • Đối với mỗi giao dịch có thể hoàn tiền được nhiều lần và tổng số tiền hoàn luôn phải bé hơn hoặc bằng số tiền người dùng cuối đã thanh toán cho ĐT,

  • Số tiền còn lại trong TKNH của ĐT phải lớn hơn số tiền hoàn cho người dùng cuối.

• Hệ thống VietQR cần cung cấp secret_key cho ĐT để ĐT có thể sử dụng dịch vụ hoàn tiền.

II. Thông tin kỹ thuật

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

• ĐT sử dụng API Get Token để lấy thông tin xác thực Bearer Token. Đoạn Bearer Token này dùng để gọi API Hoàn tiền.

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

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

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

  • Đối với API Hoàn tiền, hệ thống yêu cầu field “checkSum” trong Request Body. Phía VietQR cung cấp thông tin để ĐT generate checksum:

API	Quy định checksum
API Hoàn tiền	MD5(secretKey + referenceNumber + amount + bankAccount)

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

  • Thời gian hiệu lực: 300 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 ĐT. Vì vậy, ĐT 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ụ

• ĐT 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.

III. Mô tả APIs

API Get Token:

• URL: https://<vietqr-host>/<basepath>/api/token_generate

• Method: POST

• Mô tả:

  • API để lấy Bearer Token, sử dụng để xác thực cho các API khác liên quan đến việc hoàn tiền. Token có thời hạn là 300 giây (5 phút).

  • API yêu cầu sử dụng Basic Authentication. Gửi một yêu cầu HTTP với header Authorization chứa mã hóa base64 của username:password (do VietQR cung cấp)

• Authorization: Basic Authentication

• Request Body: Không.

• Response Body: JSON

Field	Type	Description
access_token	String	Đoạn mã Bearer Token.
token_type	String	Mặc định: Bearer.
expires_in	int	Thời hạn của token, mặc định là 300 giây.

API Hoàn Tiền

• URL: https://<vietqr-host>/<basepath>/api/transaction/refund

• Method: POST

• Mô tả:

  • API này được sử dụng để yêu cầu hoàn tiền cho người dùng cuối của đối tác.

  • Khách hàng có thể yêu cầu hoàn lại tiền nhiều lần cho một giao dịch người dùng cuối đã thực hiện với điều kiện tổng số tiền được hoàn luôn bé hơn hoặc bằng số tiền người dùng cuối đã thanh toán.

  • API yêu cầu sử dụng Bearer Token để xác thực. Bearer Token có thể được lấy từ API Get Token như đã mô tả ở mục 1.

• Authorization: Bearer Token

• Request Body: JSON

Field	Type	Required	Description
bankAccount	String	Có	TK ngân hàng của KH
referenceNumber	String	Có	Mã giao dịch của giao dịch cần hoàn tiền
amount	String	Có	Số tiền cần hoàn tiền cho end-user của KH
content	String	Có	Nội dung hoàn tiền
checkSum	String	Có	Mã checkSum MD5 (secretKey + referenceNumber + amount + bankAccount)

• Response Body: JSON

  • Trường hợp thành công:

Field	Type	Description
status	String	SUCCESS: Hoàn tiền thành công
message	String	Mã giao dịch hoàn tiền

• • Trường hợp khác:

Field	Type	Description
status	String	FAILED: Có lỗi trong quá trình thực hiện
message	String	Mã lỗi

• Bảng mã lỗi:

Message	Description	Status
<Mã giao dịch>	Thành công	200
E05	Lỗi không xác định	400
E41	Checksum không hợp lệ	400
E42	Tài khoản của KH không có quyền hoàn tiền	400
E43	Hoàn tiền không thành công	400
E44	Mã giao dịch của giao dịch không tồn tại	400
E45	Số tiền refund không hợp lệ	400
E46	Request Body không hợp lệ	400
E74	Invalid token	400
E77	Tài khoản ngân hàng không thuộc quản lý của đại lý	400
E104	Không tìm thấy thông tin đại lý của ĐT	400

IV. Bảng mã lỗi

Message	Description	Status
<Mã giao dịch>	Thành công	200
E05	Lỗi không xác định	400
E41	Checksum không hợp lệ	400
E42	Tài khoản của KH không có quyền hoàn tiền	400
E43	Hoàn tiền không thành công	400
E44	Mã giao dịch của giao dịch không tồn tại	400
E45	Số tiền refund không hợp lệ	400
E46	Request Body không hợp lệ	400
E74	Invalid token	400
E77	Tài khoản ngân hàng không thuộc quản lý của đại lý	400
E104	Không tìm thấy thông tin đại lý của ĐT	400