Webhook Transaction Notification

Flow

Description: Baokim sends transaction result notification to Merchant after receiving payment from customer via VA.

API Information

Method: POST

URL /api/merchant-hosted/bank-transfer/notification

Request

(Parameters Baokim sends to Merchant)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String(50)	✅	Unique request ID from Baokim to Merchant
2	request_time	Datetime	✅	Request sent time. Format: YYYY-MM-DD H:m:s
3	merchant_code	String(30)	✅	Merchant identifier on Baokim system
4	store_code	String	❌	Store code
5	staff_code	String	❌	Staff code
6	signature	String	✅	Digital signature to authenticate request from Baokim
7	transaction	Object	✅	Transaction information
8	va_info	Object	✅	VA account information

Transaction Information

No.	Field Name	Data Type	Required	Description
1	id	Integer	✅	Baokim transaction ID
2	order_id	Integer	✅	Order ID linked
3	mrc_order_id	String(50)	✅	Merchant's order ID
4	type	Integer	✅	1 = Payment, 2 = Refund
5	payment_method	Integer	✅	1 = VA
6	merchant_fee	Integer	✅	Merchant fee
7	user_fee	Integer	✅	User fee
8	total_amount	Integer	✅	Total transaction amount (includes fees)
9	amount	Integer	✅	Amount merchant receives
10	description	String	❌	Transaction description
11	status	Integer	✅	1 = Success
12	bank_code	String(19)	❌	Bank code
13	completed_at	Datetime	✅	Completion time
14	created_at	Datetime	✅	Creation time
15	updated_at	Datetime	✅	Update time

VA Account Information

No.	Field Name	Data Type	Required	Description
1	bank_name	String(255)	✅	VA bank name
2	bank_branch	String(255)	❌	Bank branch
3	acc_no	String(50)	✅	Account identifier number
4	acc_name	String(255)	✅	Recipient name
5	qr_string	String	✅	QR string format
6	qr_path	String	✅	QR image path

Request Example

{
  "request_id": "req_20250717154500123",
  "request_time": "2025-07-07 12:00:00",
  "merchant_code": "MERCHANT001",
  "store_code": "STORE001",
  "staff_code": "STORE001",
  "transaction": {
    "id": 555002,
    "order_id": 987654322,
    "mrc_order_id": "ORDER20250717_002",
    "type": 1,
    "payment_method": 1,
    "merchant_fee": 10000,
    "user_fee": 0,
    "total_amount": 2000000,
    "amount": 1990000,
    "description": "Thanh toán đơn hàng qua tài khoản định danh (VA)",
    "status": 1,
    "bank_code": "VCB",
    "completed_at": "2025-07-17 15:45:00",
    "created_at": "2025-07-17 15:43:00",
    "updated_at": "2025-07-17 15:45:00"
  },
  "va_info": {
    "bank_name": "Ngân hàng TMCP Ngoại Thương Việt Nam (Vietcombank)",
    "bank_branch": "Chi nhánh Hà Nội",
    "acc_no": "0123456789012",
    "acc_name": "Nguyen Van A",
    "qr_string": "00020101021238550010A0000007270123000697040300000000000020386304C3A4",
    "qr_path": "https://sandbox.baokim.vn/qr/BK987654322.png"
  },
  "signature": "0xd329a892110ff6a76cdaf650f6e78fcdf1a79eb0c9f6a5a91bd6aa12be223c05"
}

Response

(Merchant returns to Baokim)

Important

Merchant must respond HTTP 200 with body confirming successful receipt. If valid response not received, Baokim will resend webhook according to retry mechanism.

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