Webhook kết quả xác thực thẻ
Quy trình
Mô tả:
- Sau khi Ngân hàng hợp tác gửi kết quả xác thực về Baokim, Baokim gọi webhook của Merchant để thông báo kết quả.
- Merchant cần xây dựng API webhook để nhận thông báo này.
Thông tin API
URL: Merchant cung cấp
Method: POST
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(20) | ✅ | AUTHENTICATION: xác thực thẻ / REFUND: hoàn tiền |
| 5 | order_code | String(50) | ✅ | Mã đơn hàng Baokim |
| 6 | total_amount | String(255) | ✅ | Tổng số tiền của đơn hàng |
| 7 | authen_status | Number | ✅ | Trạng thái authentication: 0 - Chờ xác thực / 1 - Đã xác thực / 2 - Xác thực thất bại / 3 - Bypass (3ds off) |
| 8 | status | Number | ✅ | Trạng thái đơn hàng trên Baokim |
| 9 | save_token | Number | ❌ | 0: Không lưu token, 1: Có lưu |
| 10 | off_3ds | Number | ❌ | 0: Không tắt 3DS (default), 1: Tắt 3DS |
| 11 | extend | Object | ❌ | Dữ liệu mở rộng (billing) |
| 12 | created_at | Datetime | ✅ | Thời gian tạo đơn hàng |
| 13 | updated_at | Datetime | ✅ | Thời gian cập nhật đơn hàng |
Thông tin extend
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | billing | Object | ❌ | Thông tin người thanh toán |
Thông tin billing
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | firstname | String(255) | ❌ | Tên người thanh toán |
| 2 | lastname | String(255) | ❌ | Họ người thanh toán |
| 3 | address | String(500) | ❌ | Địa chỉ |
| 4 | city | String(50) | ❌ | Thành phố. Ví dụ: HANOI |
| 5 | state | String(255) | ❌ | Bang / Tỉnh |
| 6 | country | String(2) | ❌ | Quốc gia, mã ISO2. Ví dụ: VN |
| 7 | String(255) | ❌ | ||
| 8 | phone | String(10) | ❌ | Số điện thoại |
| 9 | postal_code | String(6) | ❌ | Mã bưu điện |
Ví dụ Request
{
"request_id": "MERCHANT050015588AXE012",
"request_time": "2020-08-11 14:41:00",
"merchant_code": "MERCHANT",
"operation": "AUTHENTICATION",
"order_code": "VLAD_1753867524",
"total_amount": 10000000,
"authen_status": 1,
"status": 5,
"save_token": 0,
"off_3ds": 0,
"extend": {
"billing": {
"firstname": "A",
"lastname": "NGUYEN VAN",
"address": "313 Truong Chinh, Dong Da",
"city": "HANOI",
"state": null,
"country": "VN",
"email": "[email protected]",
"phone": "0394899999",
"postal_code": "100000"
}
},
"created_at": "2020-08-11 14:41:00",
"updated_at": "2020-08-11 14: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) | ✅ | Code trả về cho phía Baokim, bảo đảm phía MERCHANT đã nhận được |
| 2 | message | String(20) | ✅ | Message trả về |
| 3 | data | Object | ❌ | Dữ liệu trả về nếu có |
Ví dụ Response
{
"code": 0,
"message": "Success",
"data": null
}
Error Code
| Mã lỗi | Mô tả |
|---|---|
| 100 | Thành công |
| 11 | Thất bại |
| 101 | Lỗi hệ thống Baokim |
| 104 | Lỗi xác thực OAuth |
| 105 | Lỗi xác thực chữ ký |
| 301 | Không tìm thấy đơn hàng theo order_code |
| 302 | Thẻ có vấn đề (không tồn tại, hết hạn) |
| 303 | Thẻ bị từ chối |
| 304 | Thẻ không đủ số dư |
| 305 | User huỷ giao dịch |
| 306 | Sai mã OTP |
| 308 | Giao dịch chưa thực hiện Authentication |
| 309 | Giao dịch chưa thực hiện Authorize |
| 310 | Giao dịch đã Reversal, không thể Capture |
| 311 | Giao dịch đã Capture, không thể Reversal |
| 313 | Lỗi xử lý phía ngân hàng |
| 422 | Lỗi validate: RequestId không hợp lệ |
| 422 | Lỗi validate: RequestTime không hợp lệ |
| 422 | Lỗi validate: PartnerCode không hợp lệ |
| 422 | Card_data không hợp lệ |
| 422 | Amount không hợp lệ |