Chuyển tới nội dung chính

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​

STTTên trườngKiểu dữ liệuBắt buộcMô tả
1request_idString(100)✅ID duy nhất ứng với mỗi Request từ Baokim sang MERCHANT
2request_timeString(20)✅Thời gian gửi Request. Format: YYYY-MM-DD H:i:s
3master_merchant_codeString(50)✅Mã định danh duy nhất cho MASTER MERCHANT
4sub_merchant_codeString(50)✅Mã định danh duy nhất cho SUB MERCHANT
5store_codeString❌Mã cửa hàng
6branch_codeString❌Mã chi nhánh
7staff_codeString❌Mã nhân viên
8operationString✅Loại thông báo giao dịch: QR_PAYMENT_TRANS = thanh toán / QR_REFUND_TRANS = hoàn tiền
9transactionObject✅Thông tin giao dịch
10qr_infoObject✅Thông tin mã QR và dữ liệu giao dịch tại NAPAS

Thông tin transaction​

STTTên trườngKiểu dữ liệuBắt buộcMô tả
1idInteger✅Mã giao dịch của Baokim
2order_idInteger✅Mã đơn hàng của Baokim
3mrc_order_idString✅Mã đơn hàng Merchant
4origin_transaction_idInteger❌Mã giao dịch thanh toán gốc tại Baokim. Chỉ trả khi operation = QR_REFUND_TRANS
5sub_merchant_feeInteger✅Phí của sub merchant
6master_merchant_feeInteger✅Phí của master merchant
7user_feeInteger✅Phí của user
8total_amountInteger✅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
9amountInteger✅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
10descriptionString✅Nội dung giao dịch
11statusInteger✅Trạng thái giao dịch: 1 = Thành công, 2 = Thất bại
12completed_atDatetime✅Thời gian hoàn thành giao dịch
13created_atDatetime✅Thời gian tạo giao dịch
14updated_atDatetime✅Thời gian cập nhật giao dịch

Thông tin qr_info​

STTTên trườngKiểu dữ liệuBắt buộcMô tả
1qr_typeInteger✅Loại giao dịch QR: 1 = QRPay (nội địa), 2 = QRGlobal (xuyên biên giới)
2transaction_referenceString(16)✅Mã giao dịch tại NAPAS, dùng cho tra soát/đối soát
3origin_transaction_referenceString(16)❌Mã giao dịch NAPAS của giao dịch thanh toán gốc. Chỉ trả khi operation = QR_REFUND_TRANS
4payer_nameString❌Tên người thanh toán/chủ tài khoản
5contentString❌Nội dung chuyển tiền phía người thanh toán
6currency_codeString(3)❌Mã tiền tệ giao dịch (ISO 4217 numeric). 704 = VND. Với QRGlobal có thể khác 704
7system_traceString(6)❌Mã truy vết giao dịch tại NAPAS
8settlement_statusString(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 trả lại cho Baokim)

Bảng tham số chính​

STTTên trườngKiểu dữ liệuBắt buộcMô tả
1codeString(3)✅Code xác nhận đã nhận: 100 = thành công
2messageString(200)✅Message trả về cho Baokim
3dataObject❌Dữ liệu Merchant trả về nếu có

Ví dụ Response​

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