Refund / Cancel

Process

API Information

Method: POST

URL: /api/merchant-hosted/bank-transfer/refund

Request

(Parameters sent by the partner)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String(50)	✅	Unique request ID. Suggested format: MerchantCode+YYYYMMDDHHIISS+UniqueId
2	request_time	String(19)	✅	Request sent time. Format: YYYY-MM-DD HH:II:SS
3	order_id	Integer	✅	Baokim transaction code
4	refund_reason	String(255)	✅	Reason for cancelling order
5	refund_amount	Integer	✅	Refund amount (can be partial refund)
6	merchant_code	String(30)	✅	Merchant code
7	bank_code	String(30)	❌	Receiving bank code — used for wallet transfer or when recipient information is not found (error code 5)
8	acc_no	String(22)	❌	Receiving account number — used for wallet transfer or when recipient information is not found (error code 5)

Request Example

{
  "request_id": "BK20250717140001",
  "request_time": "2025-07-17 14:00:00",
  "order_id": 1141313,
  "refund_amount": 500000,
  "merchant_code": "PARTNER001",
  "refund_reason": "Yêu cầu hủy"
}

Response

(Parameters returned by Baokim)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	Integer(3)	✅	Baokim error code
2	message	String(200)	✅	Error code message
3	data	Object	✅	Data returned

Data Information

No.	Field Name	Data Type	Required	Description
1	order_id	String(25)	✅	Baokim order code
2	mrc_order_id	String(25)	✅	Merchant order code
3	refund_amount	Integer	✅	Refund amount
4	refund_fee	Integer	✅	Refund fee
5	refund_time	Datetime	✅	Refund time
6	refund_charge_by	Integer	❌	Who bears the fee: 1 = Merchant, 2 = User
7	status	Integer	✅	Refund status: 1 = Success, 2 = Failure, 3 = Pending

Response Example

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_id": "BK20250717140001",
    "mrc_order_id": "ORD123456789",
    "refund_amount": 148000,
    "refund_fee": 2000,
    "refund_charge_by": 2,
    "status": 1,
    "refund_time": "2025-07-17 14:01:10"
  }
}

Error Codes

code	message
100	Success
101	System error
102	Provider error
104	JWT authentication error
105	Invalid digital signature
106	Order amount is insufficient for refund
107	Order cannot be refunded
108	Order cannot be cancelled
109	Order does not exist
110	Merchant order code already exists
422	Validation error