Transaction Notification Webhook

(Built by MERCHANT)

⚠️ Difference from other B2B API groups: QRPay/QRGlobal requires Merchant to reply with code = 100 (not code = 0) to confirm successful webhook receipt. If returning code = 0, Baokim will not record success and will continue retrying.

Process

Payment Flow

Baokim calls this webhook (operation = QR_PAYMENT_TRANS) after receiving payment result from NAPAS. Merchant does not call any API in this flow — only receives notifications.

Refund Flow

Baokim calls this webhook (operation = QR_REFUND_TRANS) with final refund result after Merchant has called Refund API previously.

• Baokim calls webhook API built by MERCHANT to send notifications when payment result or refund request result occurs.
• MERCHANT distinguishes notification type using the operation field: QR_PAYMENT_TRANS (payment) / QR_REFUND_TRANS (refund).
• Webhook notifies both success (status = 1) and failure (status = 2) results for both payment and refund transactions.
• Retry mechanism follows Webhook Mechanism section.

API Information

Method: POST

URL: Provided by Merchant

Header:

• Content-Type: application/json
• Signature: Baokim signs the request body with digital signature, Merchant verifies using Baokim's public key

Request

(Baokim sends to Merchant)

Main Parameters

No.	Field Name	Data Type	Required	Description
1	request_id	String(100)	✅	Unique ID for each Request from Baokim to MERCHANT
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	store_code	String	❌	Store code
6	branch_code	String	❌	Branch code
7	staff_code	String	❌	Staff code
8	operation	String	✅	Notification type: QR_PAYMENT_TRANS = payment / QR_REFUND_TRANS = refund
9	transaction	Object	✅	Transaction information
10	qr_info	Object	✅	QR code and NAPAS transaction information

Transaction Information

No.	Field Name	Data Type	Required	Description
1	id	Integer	✅	Baokim transaction code
2	order_id	Integer	✅	Baokim order code
3	mrc_order_id	String	✅	Merchant order code
4	origin_transaction_id	Integer	❌	Original payment transaction code at Baokim. Only provided when operation = QR_REFUND_TRANS
5	sub_merchant_fee	Integer	✅	Sub merchant fee
6	master_merchant_fee	Integer	✅	Master merchant fee
7	user_fee	Integer	✅	User fee
8	total_amount	Integer	✅	QR_PAYMENT_TRANS: total amount payer needs to pay. QR_REFUND_TRANS: total amount payer receives back
9	amount	Integer	✅	QR_PAYMENT_TRANS: total amount MRC actually receives. QR_REFUND_TRANS: total amount deducted from MRC
10	description	String	✅	Transaction description
11	status	Integer	✅	Transaction status: 1 = Success, 2 = Failed
12	completed_at	Datetime	✅	Transaction completion time
13	created_at	Datetime	✅	Transaction creation time
14	updated_at	Datetime	✅	Transaction update time

QR Information

No.	Field Name	Data Type	Required	Description
1	qr_type	Integer	✅	QR transaction type: 1 = QRPay (domestic), 2 = QRGlobal (cross-border)
2	transaction_reference	String(16)	✅	Transaction code at NAPAS, used for inquiry/reconciliation
3	origin_transaction_reference	String(16)	❌	NAPAS transaction code of original payment transaction. Only provided when operation = QR_REFUND_TRANS
4	payer_name	String	❌	Payer / account holder name
5	content	String	❌	Transfer content from payer side
6	currency_code	String(3)	❌	Transaction currency code (ISO 4217 numeric). 704 = VND. QRGlobal may differ from 704
7	system_trace	String(6)	❌	NAPAS transaction tracing code
8	settlement_status	String(4)	❌	NAPAS settlement status: ACSP = Settled, RJCT = Rejected, PNDG = Pending reconciliation

Request Example — Payment (QR_PAYMENT_TRANS)

{
  "request_id": "BK050015588WH001",
  "request_time": "2026-06-10 14:45:00",
  "master_merchant_code": "MASTERMERCHANT",
  "sub_merchant_code": "SUBMERCHANT",
  "store_code": null,
  "branch_code": null,
  "staff_code": null,
  "operation": "QR_PAYMENT_TRANS",
  "transaction": {
    "id": 5567261,
    "order_id": 1870436,
    "mrc_order_id": "ORD_123456789",
    "origin_transaction_id": null,
    "sub_merchant_fee": 2200,
    "master_merchant_fee": 1100,
    "user_fee": 0,
    "total_amount": 200000,
    "amount": 200000,
    "description": "Thanh toan don hang",
    "status": 1,
    "completed_at": "2026-06-10 14:45:00",
    "created_at": "2026-06-10 14:41:05",
    "updated_at": "2026-06-10 14:45:00"
  },
  "qr_info": {
    "qr_type": 1,
    "transaction_reference": "6077BIDCA2CERVHE",
    "origin_transaction_reference": null,
    "payer_name": "NGUYEN VAN A",
    "content": "NGUYEN VAN A chuyen tien",
    "currency_code": "704",
    "system_trace": "669445",
    "settlement_status": "ACSP"
  }
}

Request Example — Refund (QR_REFUND_TRANS)

{
  "request_id": "BK050015588WH025",
  "request_time": "2026-06-10 17:05:00",
  "master_merchant_code": "MASTERMERCHANT",
  "sub_merchant_code": "SUBMERCHANT",
  "store_code": null,
  "branch_code": null,
  "staff_code": null,
  "operation": "QR_REFUND_TRANS",
  "transaction": {
    "id": 5567399,
    "order_id": 1870436,
    "mrc_order_id": "ORD_123456789",
    "origin_transaction_id": 5567261,
    "sub_merchant_fee": 0,
    "master_merchant_fee": 0,
    "user_fee": 0,
    "total_amount": 100000,
    "amount": 100000,
    "description": "Hoan tien giao dich",
    "status": 1,
    "completed_at": "2026-06-10 17:04:40",
    "created_at": "2026-06-10 16:20:05",
    "updated_at": "2026-06-10 17:04:40"
  },
  "qr_info": {
    "qr_type": 1,
    "transaction_reference": "6A01BKIMA2CKFRK4",
    "origin_transaction_reference": "6077BIDCA2CERVHE",
    "payer_name": "NGUYEN VAN A",
    "content": "Hoan tien giao dich",
    "currency_code": "704",
    "system_trace": "669512",
    "settlement_status": "ACSP"
  }
}

Response

(Merchant's reply to Baokim)

⚠️ Note: unlike other webhooks, QRPay/QRGlobal requires the Merchant to return code = 100 to confirm success (see the note at the top of this page).

Main Parameters Table

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

Response Example

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