# API Refund Transaction ## **TÀI LIỆU TÍCH HỢP DỊCH VỤ HOÀN TIỀN (REFUND)** ### **I. Ngữ cảnh** #### **Mô tả tài liệu** * Dịch vụ dành cho các đối tác nền tảng có nhu cầu tích hợp tính năng hoàn tiền cho KH sử dụng gói VietQR Pro. * Dịch vụ cho phép khách hàng thực hiện việc hoàn tiền các giao dịch đã thanh toán bằng mã VietQR trực tiếp trên các nền tảng được tích hợp. * Tài liệu cung cấp thông tin nghiệp vụ: * Hoàn tiền đối với giao dịch đã thanh toán * Tài liệu này cung cấp thông tin kỹ thuật: * Thông tin bảo mật * Cấu hình kết nối dịch vụ hoàn tiền * Bộ API Services dịch vụ hoà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 dùng cuối của đối tá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ụ** ![](/files/dgdflAmf37OhG8Ww3UCt) *Ảnh 1. Khái quát luồng nghiệp vụ hoàn tiền sau khi thanh toán thành công VietQR*

*Ảnh 2: Mô tả luồng nghiệp vụ hoàn tiền cho gó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ử dụng gói VietQR Pro.
1	ĐT	VietQR	KH yêu cầu hoàn tiền sau khi đã thanh toán thành công và 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 khả dụng: VietQR báo lỗi nhận thông tin hoàn tiền không thành công Nếu thông tin hợp lệ: Hệ thống VietQR tiến hành hoàn tiền
3	VietQR	ĐT	VietQR tiến hành hoàn tiền: VietQR sẽ trả thông tin nếu hoàn tiền thành công Người dùng cuối nhận được số tiền hoàn

**2.3. Hoà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 hoàn tiền** để hoàn tiền cho người dùng cuối. * Đối với mỗi giao dịch có thể hoàn tiền được nhiều lần và tổng số tiền hoàn luôn phải **bé hơn hoặc bằng** số tiền người dùng cuối đã thanh toán cho ĐT, * Số tiền còn lại trong TKNH của ĐT phải **lớn hơn** số tiền hoàn cho người dùng cuối. * Hệ thống VietQR cần cung cấp **secret\_key** cho ĐT để ĐT có thể sử dụng dịch vụ hoà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 Hoà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 Hoà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 Hoà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ô tả APIs** #### **API Get Token:** * URL: https\://\/\/api/token\_generate * Method: POST * Mô tả: * 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 Hoàn Tiền** * URL: https\://\/\/api/transaction/refund * Method: POST * Mô tả: * API này được sử dụng để yêu cầu hoàn tiền cho người dùng cuối của đối tá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 dùng cuối đã thực hiện với điều kiện tổng số tiền được hoàn luôn **bé hơn hoặc bằng** số tiền người dùng cuối đã thanh toá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ả ở mục 1. * Authorization: Bearer Token * Request Body: JSON


Field	Type	Required	Description
bankAccount	String	Có	TK ngân hàng của KH
referenceNumber	String	Có	Mã giao dịch của giao dịch cần hoàn tiền
amount	String	Có	Số tiền cần hoàn tiền cho end-user của KH
content	String	Có	Nội dung hoàn tiền
checkSum	String	Có	Mã checkSum MD5 (secretKey + referenceNumber + amount + bankAccount)

* Response Body: JSON * Trường hợp thành công: | **Field** | **Type** | **Description** | | --------- | -------- | -------------------------------- | | status | String | SUCCESS: Hoàn tiền thành công | | message | String | Mã giao dịch hoàn tiền | * * Trường hợp khác: | **Field** | **Type** | **Description** | | --------- | -------- | ---------------------------------------------- | | status | String | FAILED: Có lỗi trong quá trình thực hiện | | message | String | Mã lỗi | * Bảng mã lỗi:


Message	Description	Status
<Mã giao dịch>	Thành công	200
E05	Lỗi không xác định	400
E41	Checksum không hợp lệ	400
E42	Tài khoản của KH không có quyền hoàn tiền	400
E43	Hoàn tiền không thành công	400
E44	Mã giao dịch của giao dịch không tồn tạ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	Tài khoản ngân hàng không thuộc quản lý của đại lý	400
E104	Không tìm thấy thông tin đại lý của ĐT	400

### **IV. Bảng mã lỗi**


Message	Description	Status
<Mã giao dịch>	Thành công	200
E05	Lỗi không xác định	400
E41	Checksum không hợp lệ	400
E42	Tài khoản của KH không có quyền hoàn tiền	400
E43	Hoàn tiền không thành công	400
E44	Mã giao dịch của giao dịch không tồn tạ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	Tài khoản ngân hàng không thuộc quản lý của đại lý	400
E104	Không tìm thấy thông tin đại lý của ĐT	400

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doc.vietqr.vn/doc/api-vietqr-callback/api-refund-transaction.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.