Refund Transaction
Process
Description:
- Merchant calls this API when customer requests return, service cancellation, etc.
- Applies to transactions that have been Captured.
- Supports full or partial refund (
refund_amount). - Baokim distinguishes between 2 types: Void (cancel before settlement) and Refund (refund after settlement).
API Information
Method: POST
Request
(Parameters sent by merchant)
Main Parameters Table
| No. | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | request_id | String(100) | ✅ | Unique request ID from Merchant to Baokim |
| 2 | request_time | String(20) | ✅ | Request send time. Format: YYYY-MM-DD H:i:s |
| 3 | merchant_code | String(50) | ✅ | Unique merchant identifier |
| 4 | order_code | String(50) | ✅ | Baokim order code returned from the Authentication step |
| 5 | refund_amount | Number | ❌ | Refund amount (for partial refund). Leave blank = full refund |
| 6 | reason | Text | ❌ | Reason for refund |
| 7 | extend | Object | ❌ | Extended data |
Example Request
{
"request_id": "MERCHANT050015588AXE014",
"request_time": "2020-08-11 14:41:00",
"merchant_code": "MERCHANT",
"order_code": "VLAD_1753867524",
"reason": "yêu cầu hủy đơn",
"extend": {}
}
Response
(Parameters returned by Baokim)
Main Parameters Table
| No. | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | code | Number(3) | ✅ | Baokim error code |
| 2 | message | String(200) | ✅ | Error message |
| 3 | data | Object | ✅ | Data returned |
Data Information
| No. | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | order_code | Number | ✅ | Baokim order code |
| 2 | refund_status | Number | ✅ | Status: 0-Refund Pending / 1-Refunded / 2-Fail |
| 3 | refund_type | Number | ✅ | Refund type: 1-Void / 2-Refund |
| 4 | status | Number | ✅ | Overall order status of Baokim |
| 5 | extend | Object | ❌ | Extended data |
Example Response
{
"code": 0,
"message": "Success",
"data": {
"order_code": "VLAD_1753867524",
"refund_status": 1,
"refund_type": 1,
"status": 9,
"extend": {}
}
}
Error Code
| Error Code | Description |
|---|---|
| 100 | Success |
| 11 | Failed |
| 101 | Baokim system error |
| 104 | OAuth authentication error |
| 105 | Signature authentication error |
| 301 | Order not found by order_code |
| 302 | Card issue (does not exist, expired) |
| 303 | Card declined |
| 304 | Insufficient card balance |
| 305 | User cancelled transaction |
| 306 | Incorrect OTP |
| 308 | Transaction has not completed Authentication |
| 309 | Transaction has not completed Authorization |
| 310 | Transaction already reversed, cannot capture |
| 311 | Transaction already captured, cannot reverse |
| 313 | Bank-side processing error |
| 422 | Validation error: RequestId invalid |
| 422 | Validation error: RequestTime invalid |
| 422 | Validation error: PartnerCode invalid |
| 422 | Card_data invalid |
| 422 | Amount invalid |