Webhook Card Authentication Result

(Built by Merchant)

Process

Baokim calls Merchant's webhook API to return card authentication result

API Information

Method: POST

URL: Merchant provides

Header:

• Content-Type: application/json,
• Signature: $signature

Baokim calls Merchant after receiving authentication result from bank.

Request

(Parameters Baokim sends to Merchant)

Main Parameters Table

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 Master Merchant identifier
4	sub_merchant_code	String(50)	✅	Unique Sub Merchant identifier
5	operation	String(20)	✅	AUTHENTICATION: card authentication / REFUND: refund
6	order_code	String(50)	✅	Baokim order code
7	total_amount	Number	✅	Total order amount
8	authen_status	Number	✅	Authentication status: 0 = Pending / 1 = Authenticated / 2 = Failed / 3 = Bypass (3ds off)
9	status	Number	✅	Order status on Baokim
11	save_token	Number	❌	Should token be saved? 0 = No (default) / 1 = Yes
10	type	Number	✅	Payment type: 1 = PaymentByCard / 2 = UCOF-CIT
12	off_3ds	Number	❌	3DS disabling requested? 0 = No / 1 = Yes
13	card_info	Object	❌	Card information (only for UCOF-CIT)
14	extend	Object	❌	Extended data (billing)
15	created_at	Datetime	✅	Order creation time
16	updated_at	Datetime	✅	Order update time

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

Card_info Information (for UCOF-CIT)

No.	Field Name	Data Type	Required	Description
1	token	String	✅	Card information encrypted per Baokim standard, required if card_token null
2	card_number	String(20)	✅	Card number
3	card_brand	String(20)	✅	Brand: Visa / Master / JCB
4	card_issue_bank	Number(1)	✅	Issuing location: 1 = Domestic, 2 = International
5	card_on_us	Number(1)	✅	Same bank? 1 = Onus (same bank), 2 = Offus

Example Request

{
  "request_id": "MERCHANT050015588AXE012",
  "request_time": "2020-08-11 14:41:00",
  "master_merchant_code": "MASTER_MERCHANT",
  "sub_merchant_code": "SUB_MERCHANT",
  "operation": "AUTHENTICATION",
  "order_code": "VLAD_1753867524",
  "total_amount": 10000000,
  "authen_status": 1,
  "status": 5,
  "save_token": 0,
  "type": 1,
  "off_3ds": 0,
  "card_info": {
    "token": "BC151dsTTmdrSpRapya3rKYJmtu2Ue6e",
    "card_number": "979202xxxxx28392",
    "card_brand": "Visa",
    "card_issue_bank": 1,
    "card_on_us": 1
  },
  "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 must return to Baokim

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	String(3)	✅	Confirmation code (typically 0)
2	message	String(20)	✅	Message
3	data	Object	❌	Response data if any

Example Response

{
  "code": 0,
  "message": "Success",
  "data": null
}

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