Hoàn tiền giao dịch
Quy trình
- MERCHANT gọi API hoàn tiền khi khách hàng có yêu cầu trả hàng, hủy dịch vụ...
- Đây là luồng bất đồng bộ: Baokim kiểm tra điều kiện và phản hồi đã tiếp nhận yêu cầu (code 100). Kết quả hoàn tiền cuối cùng được thông báo qua Webhook thông báo giao dịch với
operation = QR_REFUND_TRANS. - Cho ph ép hoàn một phần; tổng số tiền các lần hoàn không vượt quá số tiền giao dịch gốc.
Thông tin API
Method: POST
URL: /b2b/core/api/ext/mm/qr/refund
Bảo mật: Bearer JWT (Authorization header)
Request
Bảng tham số chính
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | request_id | String(100) | ✅ | ID duy nhất ứng với mỗi Request từ MERCHANT sang Baokim |
| 2 | request_time | String(20) | ✅ | Thời gian gửi Request. Format: YYYY-MM-DD H:i:s |
| 3 | master_merchant_code | String(50) | ✅ | Mã định danh duy nhất cho MASTER MERCHANT |
| 4 | sub_merchant_code | String(50) | ✅ | Mã định danh duy nhất cho SUB MERCHANT |
| 5 | transaction_id | Integer | ✅ | Mã giao dịch thanh toán gốc tại Baokim, là trường transaction.id Baokim trả về trên Webhook thông báo giao dịch |
| 6 | amount | Integer | ✅ | Số tiền hoàn (VND, số nguyên). Cho phép hoàn một phần; không vượt quá số tiền có thể hoàn còn lại của giao dịch gốc |
| 7 | description | String(100) | ✅ | Nội dung/Lý do hoàn tiền |
Ví dụ Request
{
"request_id": "MERCHANT050015588RF001",
"request_time": "2026-06-10 16:20:00",
"master_merchant_code": "MASTERMERCHANT",
"sub_merchant_code": "SUBMERCHANT",
"transaction_id": 5567261,
"amount": 100000,
"description": "Khach hang yeu cau tra hang"
}
Response
Bảng tham số chính
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | code | Number(3) | ✅ | Mã lỗi của Baokim |
| 2 | message | String(200) | ✅ | Thông báo mã lỗi của Baokim |
| 3 | data | Object | ✅ | Dữ liệu Baokim trả về |
Thông tin data
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | refund_id | Integer | ✅ | Mã yêu cầu hoàn tiền tại Baokim, dùng đối chiếu khi nhận Webhook |
| 2 | transaction_id | Integer | ✅ | Mã giao dịch thanh toán gốc |
| 3 | amount | Integer | ✅ | Số tiền hoàn đã tiếp nhận |
Ví dụ Response
{
"code": 100,
"message": "Tiếp nhận yêu cầu hoàn tiền thành công",
"data": {
"refund_id": 990012,
"transaction_id": 5567261,
"amount": 100000
}
}
Ghi chú: Phản hồi của API này chỉ xác nhận Baokim đã tiếp nhận yêu cầu hoàn tiền. Kết quả hoàn tiền cuối cùng (thành công/thất bại) được thông báo qua Webhook thông báo giao dịch với
operation = QR_REFUND_TRANS.
Bảng mã lỗi
| Mã lỗi | Mô tả |
|---|---|
| 100 | Tiếp nhận yêu cầu thành công |
| 11 | Thất bại |
| 101 | Lỗi hệ thống Baokim |
| 103 | Lỗi xác thực chữ ký |
| 104 | Lỗi xác thực JWT |
| 422 | Dữ liệu không hợp lệ (sai định dạng, thiếu trường bắt buộc) |
| 504 | Timeout |
| 710 | Sub Merchant không tồn tại |
| 711 | Master Merchant không tồn tại |
| 712 | Sub Merchant đang không hoạt động |
| 713 | Master Merchant đang không hoạt động |
| 714 | Sub Merchant không thuộc Master Merchant |
| 725 | Không tồn tại giao dịch gốc |
| 726 | Giao dịch gốc không đủ điều kiện hoàn tiền |
| 727 | Trạng thái giao dịch gốc không hợp lệ |
| 728 | Số tiền hoàn vượt quá số tiền có thể hoàn của giao dịch gốc |