Authorization

Quy trình

• MERCHANT gọi đến api này để cấp phép cho giao dịch đã được xác thực ở trên, khách hàng sẽ bị trừ tiền trên thẻ, khoản tiền này sẽ được tạm giữ và đóng băng trong tài khoản của khách hàng.
• Chỉ gọi API cấp phép giao dịch sau khi đã hoàn tất bước Authentication.
• Thời gian Hold tiền 5-7 ngày, trong khoản thời gian này, nếu không gọi capture (thu tiền) thì tiền sẽ được tự động reversal (Hoàn trả lại cho khách hàng).
• Incremental authorize được sử dụng khi muốn gia tăng số tiền hold của 1 giao dịch đã được authorize trước đó.

Thông tin API

Method: POST

URL: (Baokim cung cấp)

Request

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
2	request_time	String(20)	✅	Thời gian gửi Request. Format: YYYY-MM-DD H:i:s
3	master_merchant_code	String(50)	✅	Mã định danh duy nhất cho master merchant
4	sub_merchant_code	String(50)	✅	Mã định danh duy nhất cho sub merchant
5	order_code	String(50)	✅	Mã đơn Baokim từ bước Authentication
6	authorize_type	Number	✅	Loại authorize: 1 = Authorize / 2 = Incremental Authorize
7	authorize_amount	Number	✅	Số tiền hold. Nếu type=2: số tiền muốn tăng thêm
8	card	Object	✅	Thông tin thẻ
9	extend	Object	❌	Dữ liệu mở rộng
10	description	String(255)	❌	Mô tả giao dịch

Thông tin card

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_data	String(255)	❌	Thông tin thẻ đã được mã hoá theo chuẩn của Baokim, bắt buộc nếu card_token null
2	card_token	String(255)	❌	Token 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
4	card_year	String(4)	✅	Năm hết hạn
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 extend.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ố (VD: HANOI)
5	state	String(255)	❌	Bang/Tỉnh
6	country	String(2)	❌	Quốc gia ISO2 (VD: 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ụ Request

{
"request_id": "MERCHANT050015588AXE014",
"request_time":" 2020-08-11 14:41:00 ",
"master_merchant_code":"MASTER_MERCHANT",
"sub_merchant_code":"SUB_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

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 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_code	String	✅	Mã đơn hàng Baokim
2	auth_code	String(50)	✅	Mã authorize từ ngân hàng
3	authorize_status	Number	✅	Trạng thái authorization: 0 = Pending, 1 = Authorized, 2 = Fail
4	status	Number	✅	Trạng thái tổng giao dịch
5	authorize_amount	Number	✅	Số tiền authorize lần này
6	total_amount	Number	✅	Tổng tiền đã authorize
7	bk_token	String(50)	✅	Token của thẻ

Ví dụ Response

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_code": "VLAD_1753867524",
    "auth_code": "AUTH456789",
    "authorize_status": 1,
    "status": 1,
    "amount": 1000000,
    "total_amount": 1000000
  }
}

Bảng mã lỗi Response 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ý
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ệ
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