Webhook kết quả xác thực thẻ

(Merchant xây dựng)

Quy trình

Baokim gọi API webhook của MERCHANT để trả kết quả xác thực thẻ

Thông tin API

Method: POST

URL: Merchant cung cấp

Header:

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

Baokim gọi về Merchant sau khi nhận kết quả xác thực từ ngân hàng.

Request

(Tham số Baokim gửi lên Merchant)

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	operation	String(20)	✅	AUTHENTICATION: xác thực thẻ / REFUND: hoàn tiền
6	order_code	String(50)	✅	Mã đơn hàng Baokim
7	total_amount	Number	✅	Tổng tiền đơn hàng
8	authen_status	Number	✅	Trạng thái authentication: 0 = Chờ / 1 = Đã xác thực / 2 = Thất bại / 3 = Bypass (3ds off)
9	status	Number	✅	Trạng thái đơn hàng trên Baokim
11	save_token	Number	❌	Có lưu token không ? 0 = Không (default) / 1 = Có
10	type	Number	✅	Loại thanh toán: 1 = PaymentByCard / 2 = UCOF-CIT
12	off_3ds	Number	❌	Có yêu cầu tắt xác thực 3DS không ?: 0 = Không / 1 = Có
13	card_info	Object	❌	Thông tin thẻ (chỉ có khi UCOF-CIT)
14	extend	Object	❌	Dữ liệu mở rộng (billing)
15	created_at	Datetime	✅	Thời gian tạo đơn
16	updated_at	Datetime	✅	Thời gian cập nhật đơn

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

Thông tin card_info (khi UCOF-CIT)

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	token	String	✅	Thông tin thẻ đã được mã hoá theo chuẩn của Baokim, bắt buộc nếu card_token null
2	card_number	String(20)	✅	Số thẻ
3	card_brand	String(20)	✅	Thương hiệu: Visa / Master / JCB
4	card_issue_bank	Number(1)	✅	Nơi phát hành thẻ: 1 = Trong nước, 2 = Nước ngoài
5	card_on_us	Number(1)	✅	Có phải cùng ngân hàng không: 1 = Onus (cùng ngân hàng), 2 = Offus

Ví dụ 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 phản hồi lại Baokim)

Bảng tham số chính

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	Integer	✅	Mã kết quả. 0, 100 hoặc 200 = Thành công
2	message	String	✅	Thông báo kết quả xử lý
3	data	Object	❌	Dữ liệu trả về (nếu có)

Ví dụ Response

{
  "code": 200,
  "message": "Successfully",
  "data": null
}