Authentication

Quy trình

Mô tả:

• Merchant gửi thông tin thẻ (đã mã hoá AES-256-CBC) để Baokim xác thực 3DS.
• Baokim trả về link xác thực 3DS để Merchant redirect người dùng tới nhập OTP.
• Số tiền ở bước này không bị trừ sau khi xác thực thành công.

Thông tin API

Method: POST

Request

(Tham số đối tác gửi lên)

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 từ Merchant sang Baokim
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 duy nhất của Merchant
4	amount	Number	✅	Giá trị đơn hàng (số tiền này không bị trừ sau xác thực)
5	card	Object	✅	Thông tin thẻ cần xác thực
6	url_success	String(255)	✅	URL Baokim redirect về khi xác thực thành công
7	url_fail	String(255)	✅	URL Baokim redirect về khi xác thực thất bại
8	save_token	Number	❌	Có lưu token thẻ không? 0: Không (default), 1: Có
9	extend	Object	❌	Dữ liệu mở rộng

Thông tin card

(chọn 1 trong 2)

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_data	String	❌	Thông tin thẻ đã mã hoá AES-256-CBC. Bắt buộc nếu card_token = null
2	card_token	String(255)	❌	Token đại diện cho thẻ. 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 thẻ
4	card_year	String(4)	✅	Năm hết hạn thẻ
5	card_cvv	String(3)	✅	Mã bảo mật (CVV)

Thông tin extend

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	billing	Object	❌	Số thẻ

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ỉ người thanh toán
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	email	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ụ: 100000

Ví dụ 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

(Tham số Baokim trả về)

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
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 trả về
3	authen_status	Number	✅	Trạng thái xác thực: 0: Chờ xác thực / 1: Đã xác thực / 2: Xác thực thất bại / 3: Bypass (3DS off) / 4: Pending
4	3ds_url	String(255)	✅	Link xác thực 3DS — redirect người dùng 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"
  }
}

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ệ