Webhook thông báo giao dịch

(MERCHANT xây dựng)

⚠️ Khác biệt so với các nhóm API B2B khác: QRPay/QRGlobal yêu cầu Merchant reply code = 100 (không phải code = 0) để xác nhận đã nhận webhook thành công. Nếu trả về code = 0, Baokim sẽ không ghi nhận thành công và tiếp tục retry.

Quy trình

Luồng Thanh toán

Baokim gọi webhook này (operation = QR_PAYMENT_TRANS) sau khi nhận kết quả thanh toán từ NAPAS. Merchant không gọi API nào ở luồng này — chỉ nhận thông báo.

Luồng Hoàn tiền

Baokim gọi webhook này (operation = QR_REFUND_TRANS) với kết quả hoàn tiền cuối cùng, sau khi Merchant đã gọi API Hoàn tiền ở bước truớc.

• Baokim gọi API Webhook do MERCHANT xây dựng để gửi thông báo khi có kết quả giao dịch thanh toán hoặc kết quả xử lý yêu cầu hoàn tiền.
• MERCHANT phân biệt loại thông báo bằng trường operation: QR_PAYMENT_TRANS (thanh toán) / QR_REFUND_TRANS (hoàn tiền).
• Webhook thông báo cả kết quả thành công (status = 1) và thất bại (status = 2) cho cả giao dịch thanh toán và giao dịch hoàn tiền.
• Cơ chế gửi và gửi lại tuân theo phần Cơ chế Webhook.

Thông tin API

Method: POST

URL: Merchant cung cấp

Header:

• Content-Type: application/json
• Signature: Baokim ký số vào dữ liệu body, Merchant xác thực bằng public key của Baokim

Request

(Baokim gửi tới Merchant)

Bảng tham số chính

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	request_id	String(100)	✅	ID duy nhất ứng với mỗi Request từ Baokim sang MERCHANT
2	request_time	String(20)	✅	Thời gian gửi Request. Format: YYYY-MM-DD H:i:s
3	master_merchant_code	String(50)	✅	Mã định danh duy nhất cho MASTER MERCHANT
4	sub_merchant_code	String(50)	✅	Mã định danh duy nhất cho SUB MERCHANT
5	store_code	String	❌	Mã cửa hàng
6	branch_code	String	❌	Mã chi nhánh
7	staff_code	String	❌	Mã nhân viên
8	operation	String	✅	Loại thông báo giao dịch: QR_PAYMENT_TRANS = thanh toán / QR_REFUND_TRANS = hoàn tiền
9	transaction	Object	✅	Thông tin giao dịch
10	qr_info	Object	✅	Thông tin mã QR và dữ liệu giao dịch tại NAPAS

Thông tin transaction

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	id	Integer	✅	Mã giao dịch của Baokim
2	order_id	Integer	✅	Mã đơn hàng của Baokim
3	mrc_order_id	String	✅	Mã đơn hàng Merchant
4	origin_transaction_id	Integer	❌	Mã giao dịch thanh toán gốc tại Baokim. Chỉ trả khi operation = QR_REFUND_TRANS
5	sub_merchant_fee	Integer	✅	Phí của sub merchant
6	master_merchant_fee	Integer	✅	Phí của master merchant
7	user_fee	Integer	✅	Phí của user
8	total_amount	Integer	✅	QR_PAYMENT_TRANS: tổng số tiền user cần thanh toán. QR_REFUND_TRANS: tổng số tiền user được hoàn lại
9	amount	Integer	✅	QR_PAYMENT_TRANS: tổng số tiền MRC thực nhận. QR_REFUND_TRANS: tổng số tiền cần trừ MRC
10	description	String	✅	Nội dung giao dịch
11	status	Integer	✅	Trạng thái giao dịch: 1 = Thành công, 2 = Thất bại
12	completed_at	Datetime	✅	Thời gian hoàn thành giao dịch
13	created_at	Datetime	✅	Thời gian tạo giao dịch
14	updated_at	Datetime	✅	Thời gian cập nhật giao dịch

Thông tin qr_info

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	qr_type	Integer	✅	Loại giao dịch QR: 1 = QRPay (nội địa), 2 = QRGlobal (xuyên biên giới)
2	transaction_reference	String(16)	✅	Mã giao dịch tại NAPAS, dùng cho tra soát/đối soát
3	origin_transaction_reference	String(16)	❌	Mã giao dịch NAPAS của giao dịch thanh toán gốc. Chỉ trả khi operation = QR_REFUND_TRANS
4	payer_name	String	❌	Tên người thanh toán/chủ tài khoản
5	content	String	❌	Nội dung chuyển tiền phía người thanh toán
6	currency_code	String(3)	❌	Mã tiền tệ giao dịch (ISO 4217 numeric). 704 = VND. Với QRGlobal có thể khác 704
7	system_trace	String(6)	❌	Mã truy vết giao dịch tại NAPAS
8	settlement_status	String(4)	❌	Trạng thái quyết toán tại NAPAS: ACSP = Được quyết toán, RJCT = Bị từ chối, PNDG = Chờ đối soát

Ví dụ Request — Thanh toán (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"
  }
}

Ví dụ Request — Hoàn tiền (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 phản hồi lại Baokim)

⚠️ Lưu ý: khác với các webhook khác, QRPay/QRGlobal yêu cầu Merchant trả về code = 100 để xác nhận thành công (xem ghi chú ở đầu trang).

Bảng tham số chính

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	Integer	✅	Mã kết quả. 100 = Thành công (bắt buộc, không dùng 0)
2	message	String	✅	Thông báo kết quả xử lý
3	data	Object	❌	Dữ liệu trả về (nếu có)

Ví dụ Response

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