Tra cứu giao dịch
Quy trình
- MERCHANT gọi API này để tra cứu thông tin giao dịch theo mã đơn hàng trong hệ thống Baokim. Baokim phản hồi trực tiếp chi tiết giao dịch trong response.
- Phiên bản hiện tại hỗ trợ tra cứu giao dịch của mã QR động (một
mrc_order_idứng với một giao dịch). Tra cứu theo mã QR tĩnh sẽ được mở rộng ở phiên bản sau. - Khuyến nghị sử dụng khi: không nhận được Webhook giao dịch, cần đối soát trạng thái đơn hàng, hoặc xử lý các giao dịch nghi vấn TimeOut.
Thông tin API
Method: POST
URL: /b2b/core/api/ext/mm/qr/inquiry
Bảo mật: Bearer JWT (Authorization header)
Request
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ừ MERCHANT sang Baokim |
| 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 | mrc_order_id | String(50) | ✅ | Mã đơn hàng cần tra cứu |
Ví dụ Request
{
"request_id": "MERCHANT050015588IQ001",
"request_time": "2026-06-11 09:00:00",
"master_merchant_code": "MASTERMERCHANT",
"sub_merchant_code": "SUBMERCHANT",
"mrc_order_id": "ORD_123456789"
}
Response
Bảng tham số chính
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | code | Number(3) | ✅ | Mã lỗi của Baokim |
| 2 | message | String(200) | ✅ | Thông báo mã lỗi của Baokim |
| 3 | data | Object | ✅ | Dữ liệu Baokim trả về |
Thông tin data
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | mrc_order_id | String | ✅ | Mã đơn hàng tra cứu |
| 2 | transaction | Object | ❌ | Chi tiết giao dịch. NULL nếu đơn hàng chưa phát sinh giao dịch |
| 3 | qr_info | Object | ❌ | Thông tin giao dịch tại NAPAS. NULL nếu đơn hàng chưa phát sinh giao dịch |
Thông tin transaction
Cấu trúc giống mục Webhook thông báo giao dịch — 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
Cấu trúc giống mục Webhook thông báo 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ụ Response
{
"code": 100,
"message": "Thành công",
"data": {
"mrc_order_id": "ORD_123456789",
"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"
}
}
}
Bảng mã lỗi
| Mã lỗi | Mô tả |
|---|---|
| 100 | Thành công |
| 11 | Thất bại |
| 101 | Lỗi hệ thống Baokim |
| 103 | Lỗi xác thực chữ ký |
| 104 | Lỗi xác thực JWT |
| 422 | Dữ liệu không hợp lệ (sai định dạng, thiếu trường bắt buộc) |
| 504 | Timeout |
| 710 | Sub Merchant không tồn tại |
| 711 | Master Merchant không tồn tại |
| 712 | Sub Merchant đang không hoạt động |
| 713 | Master Merchant đang không hoạt động |
| 714 | Sub Merchant không thuộc Master Merchant |