Refund Transaction

Process

• MERCHANT calls refund API when customer requests return, service cancellation, etc.
• This is an asynchronous flow: Baokim verifies conditions and returns acknowledgment (code 100). Final refund result is notified via webhook transaction notification with operation = QR_REFUND_TRANS.
• Allows partial refund; total refund amount cannot exceed original transaction amount.

API Information

Method: POST

URL: /b2b/core/api/ext/mm/qr/refund

Security: Bearer JWT (Authorization header)

Request

Main Parameters

No.	Field Name	Data Type	Required	Description
1	request_id	String(100)	✅	Unique ID for each Request from MERCHANT to Baokim
2	request_time	String(20)	✅	Request send time. Format: YYYY-MM-DD H:i:s
3	master_merchant_code	String(50)	✅	Unique identifier for MASTER MERCHANT
4	sub_merchant_code	String(50)	✅	Unique identifier for SUB MERCHANT
5	transaction_id	Integer	✅	Original payment transaction code at Baokim, which is the transaction.id field returned by Baokim in the transaction notification webhook
6	amount	Integer	✅	Refund amount (VND, integer). Allows partial refund; cannot exceed remaining refundable amount of original transaction
7	description	String(100)	✅	Refund reason/description

Request Example

{
  "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

Main Parameters

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

Data Information

No.	Field Name	Data Type	Required	Description
1	refund_id	Integer	✅	Refund request code at Baokim, used for matching when receiving webhook
2	transaction_id	Integer	✅	Original payment transaction code
3	amount	Integer	✅	Accepted refund amount

Response Example

{
  "code": 100,
  "message": "Refund request accepted successfully",
  "data": {
    "refund_id": 990012,
    "transaction_id": 5567261,
    "amount": 100000
  }
}

Note: The response of this API only confirms that Baokim has accepted the refund request. Final refund result (success/failure) is notified via webhook transaction notification with operation = QR_REFUND_TRANS.

Error Codes

Error Code	Description
100	Request accepted successfully
11	Failed
101	Baokim system error
103	Signature verification error
104	JWT authentication error
422	Invalid data (incorrect format, missing required fields)
504	Timeout
710	Sub Merchant does not exist
711	Master Merchant does not exist
712	Sub Merchant is inactive
713	Master Merchant is inactive
714	Sub Merchant does not belong to Master Merchant
725	Original transaction does not exist
726	Original transaction does not meet refund conditions
727	Original transaction status is invalid
728	Refund amount exceeds refundable amount of original transaction