Webhook Transaction Notification

Process

Baokim calls Merchant's webhook API to send transaction notification.

API Information

Method: POST

URL: Merchant provides

Header:

• Content-Type: application/json
• Signature: $signature

Request

(Parameters Baokim sends)

Main Parameters

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 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	store_code	String	❌	Store code
6	branch_code	String	❌	Branch code
7	staff_code	String	❌	Staff code
8	transaction	Object	✅	Transaction information
9	va_info	Object	✅	VA information

Transaction Information

No	Field Name	Data Type	Required	Description
1	id	Integer	✅	Baokim transaction ID
2	order_id	Integer	✅	Baokim order ID
3	mrc_order_id	String	✅	Merchant order ID
4	sub_merchant_fee	Integer	✅	Sub merchant fee
5	master_merchant_fee	Integer	✅	Master merchant fee
6	master_merchant_model	Integer	✅	Master merchant model
7	user_fee	Integer	✅	User fee
8	total_amount	Integer	✅	Total amount user needs to pay
9	amount	Integer	✅	Amount merchant receives
10	description	String	✅	Transaction content
11	status	Integer	✅	Transaction status
12	completed_at	Datetime	✅	Transaction completion time
13	created_at	Datetime	✅	Transaction creation time
14	updated_at	Datetime	✅	Transaction update time

VA_info Information

No.	Field Name	Data Type	Required	Description
1	bank_name	String	✅	VA bank name
2	bank_branch	String	❌	Branch
3	acc_no	String	✅	VA account number
4	acc_name	String	✅	VA account name
5	qr_string	Text	✅	QR code string
6	qr_path	String	✅	QR code image path

Example request from Baokim to Merchant:

{
  "request_id": "MERCHANT050015588AXE012",
  "request_time": "2020-08-11 14:41:00",
  "master_merchant_code": "MASTERMERCHANT",
  "sub_merchant_code": "SUBMERCHANT",
  "store_code": null,
  "branch_code": null,
  "staff_code": null,
  "transaction": {
    "id": 5567261,
    "order_id": 1870436,
    "sub_merchant_fee": 2200,
    "master_merchant_fee": 1100,
    "master_merchant_model": 1,
    "user_fee": 0,
    "total_amount": 200000,
    "amount": 200000,
    "description": "NGUYEN VAN A chuyen tien",
    "status": 1,
    "completed_at": "2020-08-11 14:41:00",
    "created_at": "2020-08-11 14:41:00",
    "updated_at": "2020-08-11 15:41: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": "01234567890123",
    "acc_name": "BAOKIM NGUYEN VAN A",
    "qr_string": "00020101021238550010A0000007270123000697040300000000000020386304C3A4",
    "qr_path": "https://sandbox.baokim.vn/qr/BK1234567890.png"
  }
}

Response

(Merchant returns to Baokim)

Main Parameters

No	Field Name	Data Type	Required	Description
1	code	String(3)	✅	Code returned to Baokim, ensuring merchant received it
2	message	String(20)	✅	Message returned to Baokim
3	data	Object	❌	Data merchant returns to Baokim if any

Response Example

{
  "code": 0,
  "message": "Success",
  "data": null
}

Error Codes

Error Code	Description
100	Success
11	Failed
101	Baokim system error
103	Signature authentication error
104	JWT authentication error
422	Invalid data
710	Sub merchant does not exist
711	Master merchant does not exist
712	Sub merchant is inactive
713	Master merchant is inactive