Authentication

Process

Description:

• Merchant sends card information (encrypted with AES-256-CBC) to Baokim for 3DS authentication.
• Baokim returns a 3DS authentication link for Merchant to redirect the user to enter OTP.
• The amount at this step is not deducted after successful authentication.

API Information

Method: POST

Request

(Parameters sent by merchant)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String(100)	✅	Unique request ID from Merchant to Baokim
2	request_time	String(20)	✅	Request send time. Format: YYYY-MM-DD H:i:s
3	merchant_code	String(50)	✅	Unique merchant identifier
4	amount	Number	✅	Order amount (this amount will not be deducted after authentication)
5	card	Object	✅	Card information for authentication
6	url_success	String(255)	✅	URL Baokim redirects to on successful authentication
7	url_fail	String(255)	✅	URL Baokim redirects to on failed authentication
8	save_token	Number	❌	Should the card token be saved? 0: No (default), 1: Yes
9	extend	Object	❌	Extended data

Card Information

(Choose 1 of 2)

No.	Field Name	Data Type	Required	Description
1	card_data	String	❌	Card information encrypted with AES-256-CBC. Required if card_token is null
2	card_token	String(255)	❌	Token representing the card. Required if card_data is 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)	✅	Security code (CVV)

Extend Information

No.	Field Name	Data Type	Required	Description
1	billing	Object	❌	Card information

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 code. Example: VN
7	email	String(255)	❌	Payer email
8	phone	String(10)	❌	Phone number
9	postal_code	String(6)	❌	Postal code. Example: 100000

Example Request

{
  "request_id": "MERCHANT050015588AXE00",
  "request_time": "2020-08-11 14:41:00",
  "merchant_code": "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,
  "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": "10000"
    }
  }
}

Response

(Parameters returned by Baokim)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	Number(3)	✅	Baokim error code
2	message	String(200)	✅	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)	✅	Authentication transaction code returned by Baokim
3	authen_status	Number	✅	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

Error Code	Description
100	Success
11	Failed
101	Baokim system error
104	OAuth authentication error
105	Signature authentication error
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
422	Validation error: RequestId invalid
422	Validation error: RequestTime invalid
422	Validation error: PartnerCode invalid
422	Card_data invalid
422	Amount invalid