💸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:
|
3 | VietQR | ĐT | VietQR tiến hành hoàn tiề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 |
Last updated
