Authentication
Process
- Merchant sends a request to Baokim
API Information
Method: POST
URL:
Merchant sends card information → Baokim returns 3DS link to redirect user to authenticate OTP.
Request
Main Parameters
| No | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | request_id | String(100) | ✅ | Unique request ID |
| 2 | request_time | String(20) | ✅ | Request send time. Format: YYYY-MM-DD H:i:s |
| 3 | master_merchant_code | String(50) | ✅ | Unique identifier for master merchant |
| 4 | sub_merchant_code | String(50) | ✅ | Unique identifier for sub merchant |
| 5 | amount | Number | ✅ | Order amount (will not be deducted after successful authentication) |
| 6 | card | Object | ✅ | Card information — see below |
| 7 | url_success | String(255) | ✅ | URL redirect on successful authentication |
| 8 | url_fail | String(255) | ✅ | URL redirect on failed authentication |
| 9 | save_token | Number | ❌ | Save token or not?: 0 = No (default) / 1 = Yes |
| 10 | type | Number | ✅ | Payment type: 1 = PaymentByCard (default), 2 = UCOF-CIT |
| 11 | off_3ds | Number | ❌ | Disable 3DS authentication? 0 = No (default) / 1 = Disable 3DS |
| 12 | extend | Object | ❌ | Extended data (billing) |
Card Information
| No | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | card_data | String | ❌ | Card information encrypted per Baokim standard, required if card_token null. If type = 2 (UCOF-CIT), must provide card_data |
| 2 | card_token | String(255) | ❌ | Saved card token. Required if card_data null |
Card_data Information Before Encryption
| No. | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | card_number | String(20) | ✅ | Card number |
| 2 | card_name | String(255) | ✅ | Cardholder name |
| 3 | card_month | String(2) | ✅ | Card expiry month |
| 4 | card_year | String(4) | ✅ | Card expiry year |
| 5 | card_cvv | String(3) | ✅ | Card security code |
Extend Information
| No. | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | billing | Object | ❌ | Payer information |
Extend.billing Information
| No. | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | firstname | String(255) | ❌ | Payer first name |
| 2 | lastname | String(255) | ❌ | Payer last name |
| 3 | address | String(500) | ❌ | Payer address |
| 4 | city | String(50) | ❌ | City (Example: HANOI) |
| 5 | state | String(255) | ❌ | State/Province |
| 6 | country | String(2) | ❌ | Country ISO2 (Example: VN) |
| 7 | String(255) | ❌ | Payer email | |
| 8 | phone | String(10) | ❌ | Phone number |
| 9 | postal_code | String(6) | ❌ | Postal code |
Example 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
Main Parameters Table
| No. | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | code | Number(3) | ✅ | Baokim error code |
| 2 | message | String(200) | ✅ | Baokim error message |
| 3 | data | Object | ✅ | Data returned by Baokim |
Data Information
| No. | Field Name | Data Type | Required | Description |
|---|---|---|---|---|
| 1 | order_id | Number | ✅ | Baokim order ID |
| 2 | order_code | String(50) | ✅ | Baokim authentication transaction code |
| 3 | authen_status | Number | ✅ | Card authentication status: 0 = Pending / 1 = Authenticated / 2 = Failed / 3 = Bypass (3DS off) / 4 = Pending |
| 4 | 3ds_url | String(255) | ✅ | 3DS authentication link — redirect user here |
Example 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"
}
}
Error Code Table
| Error Code | Description |
|---|---|
| 100 | Success |
| 11 | Failed |
| 101 | Baokim system error |
| 104 | OAuth authentication error |
| 105 | Signature authentication error |
| 422 | Validation error: RequestId invalid |
| 422 | Validation error: RequestTime invalid |
| 422 | Validation error: PartnerCode invalid |
| 422 | Card_data invalid |
| 422 | Amount invalid |
| 301 | Order not found by order_code |
| 302 | Card issue (does not exist, expired) |
| 303 | Card declined |
| 304 | Insufficient card balance |
| 305 | User cancelled transaction |
| 306 | Incorrect OTP |
| 308 | Transaction has not completed Authentication |
| 309 | Transaction has not completed Authorization |
| 310 | Transaction already reversed — cannot capture |
| 311 | Transaction already captured — cannot reverse |
| 313 | Bank-side processing error |