Authentication
Quy trình
- MERCHANT gửi yêu cầu tới Baokim
Thông tin API
Method: POST
URL:
Merchant gửi thông tin thẻ → Baokim trả về link 3DS để redirect user xác thực OTP.
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 của request |
| 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 | amount | Number | ✅ | Giá trị đơn hàng (không bị trừ sau xác thực thành công) |
| 6 | card | Object | ✅ | Thông tin thẻ — xem bên dưới |
| 7 | url_success | String(255) | ✅ | URL redirect khi xác thực thành công |
| 8 | url_fail | String(255) | ✅ | URL redirect khi xác thực thất bại |
| 9 | save_token | Number | ❌ | Có lưu token không ?: 0 = Không (default) ; 1 = Có |
| 10 | type | Number | ✅ | Loại thanh toán: 1 = PaymentByCard (default), 2 = UCOF-CIT |
| 11 | off_3ds | Number | ❌ | Có yêu cầu tắt xác thực 3DS không ?: 0 = Không (default) / 1 = Tắt 3DS |
| 12 | extend | Object | ❌ | Thông tin mở rộng (billing) |
Thông tin card
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | card_data | String | ❌ | Thông tin thẻ đã được mã hoá theo chuẩn của Baokim, bắt buộc nếu card_token null. Nếu type = 2 (UCOF-CIT), bắt buộc truyền card_data |
| 2 | card_token | String(255) | ❌ | Token thẻ đã lưu. Bắt buộc nếu card_data null |
Thông tin card_data trước khi mã hoá
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | card_number | String(20) | ✅ | Số thẻ |
| 2 | card_name | String(255) | ✅ | Tên chủ thẻ |
| 3 | card_month | String(2) | ✅ | Tháng hết hạn |
| 4 | card_year | String(4) | ✅ | Năm hết hạn |
| 5 | card_cvv | String(3) | ✅ | Mã bảo mật trên thẻ |
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 extend.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ỉ người thanh toán |
| 4 | city | String(50) | ❌ | Thành phố (VD: HANOI) |
| 5 | state | String(255) | ❌ | Bang/Tỉnh |
| 6 | country | String(2) | ❌ | Quốc gia ISO2 (VD: VN) |
| 7 | String(255) | ❌ | Email người thanh toán | |
| 8 | phone | String(10) | ❌ | Số điện thoại |
| 9 | postal_code | String(6) | ❌ | Mã bưu điện |
Ví dụ Request
{
"request_id": "MERCHANT050015588AXE00",
"request_time": "2020-08-11 14:41:00",
"master_merchant_code": "MASTER_MERCHANT",
"sub_merchant_code": "SUB_MERCHANT",
"amount": 20000,
"card": {
"card_data": "yeAhZHfP6cWkLCL28svcXv2F9ntN3I1xBFGJG17JfxERkg8913ZxV",
"card_token": null },
"url_success": "https://example.com/success",
"url_fail": "https://example.com/fail",
"save_token": 0,
"type": 1,
"off_3ds": 0,
"extend": {
"billing": {
"firstname": "A",
"lastname": "NGUYEN VAN",
"city": "HANOI",
"state": null,
"country": "VN",
"email": "[email protected]",
"phone": "0394899999"
"postal_code": "10000"
}
}
}
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 | order_id | Number | ✅ | Mã đơn hàng Baokim |
| 2 | order_code | String(50) | ✅ | Mã giao dịch xác thực Baokim |
| 3 | authen_status | Number | ✅ | Trạng thái xác thực thẻ: 0 = Chờ / 1 = Đã xác thực / 2 = Thất bại / 3 = Bypass (3DS off) / 4 = Pending |
| 4 | 3ds_url | String(255) | ✅ | Link xác thực 3DS — redirect user tới đây |
Ví dụ Response
{
"code": 0,
"message": "Success",
"data": {
"order_id": 1870436,
"order_code": "VLAD_1753867524",
"authen_status": 0,
"3ds_url": "https://payment-page.baokim.vn/payment/?oid=38260&checksum=d863a2d66f76e3fc7bcfe302bfc19ff3e5253f5c"
}
}
Bảng mã lỗi Response 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ý |
| 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ệ |
| 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 |