# API Refund Transaction

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

### **I. Ngữ cảnh** <a href="#ljo6zvvs2baa" id="ljo6zvvs2baa"></a>

#### **Mô tả tài liệu** <a href="#id-9w7upw7z9soe" id="id-9w7upw7z9soe"></a>

* 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:

<table data-header-hidden><thead><tr><th width="203"></th><th></th></tr></thead><tbody><tr><td><strong>Thuật ngữ</strong></td><td><strong>Chú thích nội dung</strong></td></tr><tr><td>ĐT</td><td>Đối tác</td></tr><tr><td>KH</td><td>Khách hàng, người dùng cuối của đối tác</td></tr><tr><td>TK/TKNH</td><td>Tài khoản/Tài khoản ngân hàng</td></tr><tr><td>LK</td><td>Liên kết</td></tr><tr><td>GD</td><td>Giao dịch</td></tr><tr><td>TT</td><td>Thanh toán</td></tr><tr><td>BĐSD</td><td>Biến động số dư</td></tr></tbody></table>

#### **Nghiệp vụ** <a href="#v0fr7smk6s58" id="v0fr7smk6s58"></a>

**2.1. Luồng nghiệp vụ**

![](https://2094581354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHIyMp8uez10XaYkjnjT8%2Fuploads%2FsIFsY5evimRghBmvOKD9%2F0.png?alt=media)

*Ả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*

<figure><img src="https://2094581354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHIyMp8uez10XaYkjnjT8%2Fuploads%2FvMB2TwPhVJYDEWUyN3nM%2F1.png?alt=media" alt=""><figcaption></figcaption></figure>

*Ả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ụ**

<table data-header-hidden><thead><tr><th width="151"></th><th width="117"></th><th width="88"></th><th></th></tr></thead><tbody><tr><td><strong>Bước</strong><br><strong>thực hiện</strong></td><td><strong>Người</strong><br><strong>thực hiện</strong></td><td><strong>Hệ thống</strong></td><td><strong>Mô tả</strong></td></tr><tr><td>Pre-condition</td><td>ĐT</td><td></td><td><p>- Đã khai báo kết nối đến hệ thống VietQR.<br>- Đã liên kết TK MBBank/BIDV trên hệ thống VietQR.</p><p>- Sử dụng gói VietQR Pro.</p></td></tr><tr><td>1</td><td>ĐT</td><td>VietQR</td><td>KH yêu cầu hoàn tiền sau khi đã thanh toán thành công và ghi nhận BĐSD</td></tr><tr><td>2</td><td>VietQR</td><td>ĐT</td><td><p>VietQR kiểm tra thông tin:</p><ul><li>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</li><li>Nếu thông tin hợp lệ: Hệ thống VietQR tiến hành hoàn tiền</li></ul></td></tr><tr><td>3</td><td>VietQR</td><td>ĐT</td><td><p>VietQR tiến hành hoàn tiền:</p><ul><li>VietQR sẽ trả thông tin nếu hoàn tiền thành công</li><li>Người dùng cuối nhận được số tiền hoàn</li></ul></td></tr></tbody></table>

**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** <a href="#id-9bx34lr8zs3t" id="id-9bx34lr8zs3t"></a>

#### **Quy định về xác thực bảo mật** <a href="#noarbtz0rhsc" id="noarbtz0rhsc"></a>

* Đ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ụ** <a href="#yrsk38w3p795" id="yrsk38w3p795"></a>

* Đ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** <a href="#y6ndvhlr36p6" id="y6ndvhlr36p6"></a>

#### **API Get Token:** <a href="#fu64uo3nsv4s" id="fu64uo3nsv4s"></a>

* 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** <a href="#l3r6wttnijyw" id="l3r6wttnijyw"></a>

* 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

<table data-header-hidden><thead><tr><th width="197"></th><th width="118"></th><th width="102"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td><td><strong>Description</strong></td></tr><tr><td>bankAccount</td><td>String</td><td>Có</td><td>TK ngân hàng của KH</td></tr><tr><td>referenceNumber</td><td>String</td><td>Có</td><td>Mã giao dịch của giao dịch cần hoàn tiền</td></tr><tr><td>amount</td><td>String</td><td>Có</td><td>Số tiền cần hoàn tiền cho end-user của KH</td></tr><tr><td>content</td><td>String</td><td>Có</td><td>Nội dung hoàn tiền</td></tr><tr><td>checkSum</td><td>String</td><td>Có</td><td>Mã checkSum MD5 (secretKey + referenceNumber + amount + bankAccount)</td></tr></tbody></table>

* 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:

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

### **IV. Bảng mã lỗi** <a href="#id-9hbrnld8rs54" id="id-9hbrnld8rs54"></a>

<table data-header-hidden><thead><tr><th width="170"></th><th width="516"></th><th></th></tr></thead><tbody><tr><td><strong>Message</strong></td><td><strong>Description</strong></td><td><strong>Status</strong></td></tr><tr><td>&#x3C;Mã giao dịch></td><td>Thành công</td><td>200</td></tr><tr><td>E05</td><td>Lỗi không xác định</td><td>400</td></tr><tr><td>E41</td><td>Checksum không hợp lệ</td><td>400</td></tr><tr><td>E42</td><td>Tài khoản của KH không có quyền hoàn tiền</td><td>400</td></tr><tr><td>E43</td><td>Hoàn tiền không thành công</td><td>400</td></tr><tr><td>E44</td><td>Mã giao dịch của giao dịch không tồn tại</td><td>400</td></tr><tr><td>E45</td><td>Số tiền refund không hợp lệ</td><td>400</td></tr><tr><td>E46</td><td>Request Body không hợp lệ</td><td>400</td></tr><tr><td>E74</td><td>Invalid token</td><td>400</td></tr><tr><td>E77</td><td>Tài khoản ngân hàng không thuộc quản lý của đại lý</td><td>400</td></tr><tr><td>E104</td><td>Không tìm thấy thông tin đại lý của ĐT</td><td>400</td></tr></tbody></table>