Webhook Transaction Notification

Flow

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

API Information

Method: POST

URL (URL configured by Merchant with Baokim)

Request Headers:

Header	Desscription
Signature	Chữ ký số để xác thực tính toàn vẹn dữ liệu

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's reply to Baokim)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	Integer	✅	Result code. 0, 100 or 200 = Success
2	message	String	✅	Processing result message
3	data	Object	❌	Returned data (if any)

Response Example

{
  "code": 200,
  "message": "Successfully",
  "data": null
}