Webhook thông báo kết quả giao dịch
Quy trình
Mô tả:
- Với mỗi giao dịch đư ợc chuyển đổi thành công / thất bại / hoặc bị huỷ, Baokim gửi request thông báo kết quả cho Merchant.
- Merchant cần xây dựng API webhook để nhận thông báo này.
- Baokim sẽ ký với phần dữ liệu trong request gửi sang phía MERCHANT.
Thông tin API
Method: POST
URL: Merchant cung cấp
Header:
Content-Type: application/json
Signature: $signature
Request
(Tham số 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 của request |
| 2 | request_time | String(20) | ✅ | Thời gian gửi request. Format: YYYY-MM-DD H:i:s |
| 3 | merchant_code | String(50) | ✅ | Mã định danh Merchant |
| 4 | operation | String | ✅ | Loại thao tác: PAYMENT hoặc REFUND |
| 5 | data | Object | ✅ | Thông tin chi tiết giao dịch |
Thông tin data
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | bank_no | String(6) | ✅ | Mã định danh ngân hàng trên Baokim |
| 2 | customer_id_number | String(12) | ❌ | Số CMND / CCCD / hộ chiếu |
| 3 | customer_name | String(200) | ❌ | Tên đầy đủ khách hàng, không dấu, có khoảng trắng |
| 4 | customer_phone | String(10) | ✅ | Số điện thoại khách hàng |
| 5 | customer_email | String(255) | ✅ | Email khách hàng |
| 6 | customer_address | String(500) | ❌ | Địa chỉ khách hàng |
| 7 | product_name | String(255) | ❌ | Tên sản phẩm |
| 8 | auth_code | String(50) | ✅ | Mã chuẩn chi |
| 9 | bin | String(50) | ✅ | Đầu BIN của thẻ |
| 10 | mrc_order_id | String(50) | ✅ | Mã đơn hàng merchant |
| 11 | loan_package | Object | ✅ | Thông tin gói vay |
| 12 | auth_time | String(50) | ✅ | Thời gian thanh toán thẻ |
| 13 | total_payment_amount | Integer | ✅ | Số tiền thanh toán thẻ |
| 14 | status | Integer | ✅ | Trạng thái: Chuyển đổi thành công / Chuyển đổi thất bại / Huỷ chuyển đổi thành công / Huỷ chuyển đổi thất bại |
| 15 | installment_fee_amount | Integer | ✅ | Phí chuyển đổi trả góp |
| 16 | monthly_payment_amount | Integer | ✅ | Số tiền trả góp hàng tháng (tổng tiền vay / kỳ hạn) |
| 17 | installment_amount | Integer | ✅ | Số tiền đăng ký trả góp |
| 18 | order_id | Integer | ✅ | Mã đơn hàng duy nhất do Baokim tạo |
| 19 | created_at | String(20) | ✅ | Thời gian tạo đơn hàng |
| 20 | updated_at | String(20) | ✅ | Thời gian cập nhật đơn hàng |
Thông tin loan_package
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | loan_pack_id | Integer | ✅ | ID gói trả góp trên hệ thống Baokim |
| 2 | package_name | String(255) | ✅ | Tên gói vay |
| 3 | grace_period | Integer | ✅ | Thời hạn trả góp (tháng) |
| 4 | conversion_fee | Decimal | ✅ | Phí chuyển đổi trả góp (%) |
Ví dụ Request
{
"request_id": "MERCHANT050015588AXE012",
"request_time": "2020-08-11 14:41:00",
"merchant_code": "MERCHANT",
"operation": "PAYMENT/REFUND",
"data": {
"bank_no": "970436",
"customer_id_number": "H0119600",
"customer_name": "Nguyễn Trung Quân",
"customer_phone": "0394827170",
"customer_email": "[email protected]",
"customer_address": "40, ngách 16/255 đường Láng, Đống Đa, Hà Nội",
"product_name": "Tủ lạnh LG",
"auth_code": "1312338",
"bin": "5339682111",
"mrc_order_id": "VLAD_1753867524",
"loan_package": {
"loan_pack_id": 638,
"package_name": "Gói vay kỳ hạn 6 tháng",
"grace_period": 6,
"conversion_fee": 2.0
},
"auth_time": "2020-08-11 14:41:00",
"total_payment_amount": 10700000,
"status": 1,
"installment_fee_amount": 700000,
"monthly_payment_amount": 1188889,
"installment_amount": 10700000,
"order_id": 45467,
"created_at": "2020-08-11 14:41:00",
"updated_at": "2020-08-11 15:41:00"
}
}
Response
(Merchant trả lại cho Baokim)
Bảng tham số chính
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | code | String(3) | ✅ | Xác nhận đã nhận (0 = thành công) |
| 2 | message | String(20) | ✅ | Message trả về |
| 3 | data | String(20) | ✅ | Dữ liệu trả về nếu có |
Ví dụ Response
{
"code": 0,
"message": "Success",
"data": null
}
Bảng mã lỗi
| Mã lỗi | Mô tả |
|---|---|
| 200 | Thành công |
| 11 | Thất bại |
| 101 | Lỗi hệ thống Baokim |
| 102 | Lỗi xác thực basic auth |
| 103 | Lỗi xác thực chữ ký |
| 104 | Lỗi validate: RequestId không hợp lệ |
| 105 | Lỗi validate: RequestTime không hợp lệ |
| 106 | Lỗi validate: PartnerCode không hợp lệ |
| 107 | Lỗi validate: CustomerName không hợp lệ |
| 108 | Lỗi validate: CustomerPhone không hợp lệ |
| 109 | Lỗi validate: CustomerEmail không hợp lệ |
| 110 | Lỗi validate: BankCode không hợp lệ |
| 112 | Lỗi validate: ClientIdNo không hợp lệ |
| 113 | Lỗi validate: AuthCode không hợp lệ |
| 114 | Lỗi validate: CardNo không hợp lệ |
| 118 | Lỗi validate: ReferenceId không hợp lệ |
| 122 | Lỗi validate: ConversionMoney không hợp lệ |
| 123 | Lỗi validate: PayPerMonth không hợp lệ |
| 124 | Lỗi validate: InstallmentAmount không hợp lệ |
| 125 | Lỗi validate: TotalPaymentAmount không hợp lệ |
| 126 | Ngân hàng trả góp và ngân hàng phát hành thẻ không khớp |
| 127 | Lỗi validate: Operation không hợp lệ |
| 142 | Trạng thái không hợp lệ |
| 157 | Đầu số thẻ không hỗ trợ trả góp |
| 159 | Thời gian bắt đầu (fromTime) không hợp lệ |
| 160 | Thời gian kết thúc (toTime) không hợp lệ |
| 168 | Kỳ hạn trả góp không hợp lệ |
| 170 | Lỗi gói vay chưa được cấu hình tại Baokim |
| 171 | Giao dịch huỷ không được hỗ trợ |
| 174 | Thời gian huỷ không hợp lệ |
| 176 | Thời gian thanh toán không hợp lệ |
| 177 | Lý do huỷ không hợp lệ |