Authorization

Quy trình

Mô tả:

• Merchant gọi API này để cấp phép giao dịch đã xác thực ở bước Authentication.
• Tiền khách hàng bị tạm hold và đóng băng trong tài khoản (5–7 ngày).
• API Chỉ gọi sau khi hoàn tất bước Authentication.
• Nếu không gọi Capture trong thời gian hold, tiền sẽ tự động Reversal.
• Incremental Authorize dùng khi muốn tăng thêm số tiền hold của giao dịch đã authorize.

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	order_code	String(50)	✅	Mã đơn hàng Baokim trả về tại bước Authentication
5	authorize_type	Number	✅	Loại authorize: 1-Authorize / 2-Incremental Authorize
6	authorize_amount	Number	✅	Số tiền authorize. Nếu authorize_type = 2 thì đây là số tiền muốn tăng thêm
7	card	Object	✅	Thông tin thẻ (card_data hoặc card_token)
8	extend	Object	❌	Dữ liệu mở rộng (billing)
9	description	String(255)	❌	Mô tả giao dịch Authorize

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(255)	❌	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 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 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ỉ
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": "MERCHANT050015588AXE014",
  "request_time": "2020-08-11 14:41:00",
  "merchant_code": "MERCHANT",
  "order_code": "VLAD_1753867524",
  "authorize_type": 1,
  "authorize_amount": 1000000,
  "card": {
    "card_data": "yeAhZHfP6cWkLCL28svcXv2F9ntN3I1xBFGJG17JfxERkg8913ZxV",
    "card_token": null
  },
  "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"
    }
  },
  "description": "description GD authorize"
}

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 của Baokim
3	data	Object	✅	Dữ liệu trả về

Thông tin data

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	order_code	Number	✅	Mã đơn hàng Baokim
2	auth_code	String(50)	✅	Mã authorize do Ngân hàng hợp tác trả về
3	authorize_status	Number	✅	Trạng thái: 0-Pending / 1-Authorized / 2-Fail
4	status	Number	✅	Trạng thái tổng của giao dịch Baokim
5	authorize_amount	Number	✅	Số tiền authorize
6	total_amount	Number	✅	Tổng tiền đã authorize
7	token	String(500)	❌	Token thẻ trả về sau khi khách hàng xác thực 3DS thành công nếu bước Authentication có tham số save_token = 1

Ví dụ Response

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_code": "VLAD_1753867524",
    "auth_code": "AUTH456789",
    "authorize_status": 1,
    "status": 1,
    "authorize_amount": 100000,
    "total_amount": 10100000,
    "token": "BC151dsTTmdrSpRapya3rKYJmtu2Ue6e"
  }
}

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ệ