Webhook thông báo kết quả giao dịch

Quy trình

Mô tả:

• Với mỗi giao dịch được chuyển đổi thành công / thất bại / hoặc bị huỷ, Baokim gửi request thông báo kết quả cho Merchant.
• Merchant cần xây dựng API webhook để nhận thông báo này.
• Baokim sẽ ký với phần dữ liệu trong request gửi sang phía MERCHANT.

Thông tin API

Method: POST

URL: Merchant cung cấp

Header:

Content-Type: application/json
Signature: $signature

Request

(Tham số Baokim gửi tới 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	merchant_code	String(50)	✅	Mã định danh Merchant
4	operation	String	✅	Loại thao tác: PAYMENT hoặc REFUND
5	data	Object	✅	Thông tin chi tiết giao dịch

Thông tin data

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	bank_no	String(6)	✅	Mã định danh ngân hàng trên Baokim
2	customer_id_number	String(12)	❌	Số CMND / CCCD / hộ chiếu
3	customer_name	String(200)	❌	Tên đầy đủ khách hàng, không dấu, có khoảng trắng
4	customer_phone	String(10)	✅	Số điện thoại khách hàng
5	customer_email	String(255)	✅	Email khách hàng
6	customer_address	String(500)	❌	Địa chỉ khách hàng
7	product_name	String(255)	❌	Tên sản phẩm
8	auth_code	String(50)	✅	Mã chuẩn chi
9	bin	String(50)	✅	Đầu BIN của thẻ
10	mrc_order_id	String(50)	✅	Mã đơn hàng merchant
11	loan_package	Object	✅	Thông tin gói vay
12	auth_time	String(50)	✅	Thời gian thanh toán thẻ
13	total_payment_amount	Integer	✅	Số tiền thanh toán thẻ
14	status	Integer	✅	Trạng thái: Chuyển đổi thành công / Chuyển đổi thất bại / Huỷ chuyển đổi thành công / Huỷ chuyển đổi thất bại
15	installment_fee_amount	Integer	✅	Phí chuyển đổi trả góp
16	monthly_payment_amount	Integer	✅	Số tiền trả góp hàng tháng (tổng tiền vay / kỳ hạn)
17	installment_amount	Integer	✅	Số tiền đăng ký trả góp
18	order_id	Integer	✅	Mã đơn hàng duy nhất do Baokim tạo
19	created_at	String(20)	✅	Thời gian tạo đơn hàng
20	updated_at	String(20)	✅	Thời gian cập nhật đơn hàng

Thông tin loan_package

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	loan_pack_id	Integer	✅	ID gói trả góp trên hệ thống Baokim
2	package_name	String(255)	✅	Tên gói vay
3	grace_period	Integer	✅	Thời hạn trả góp (tháng)
4	conversion_fee	Decimal	✅	Phí chuyển đổi trả góp (%)

Ví dụ Request

{
  "request_id": "MERCHANT050015588AXE012",
  "request_time": "2020-08-11 14:41:00",
  "merchant_code": "MERCHANT",
  "operation": "PAYMENT/REFUND",
  "data": {
    "bank_no": "970436",
    "customer_id_number": "H0119600",
    "customer_name": "Nguyễn Trung Quân",
    "customer_phone": "0394827170",
    "customer_email": "[email protected]",
    "customer_address": "40, ngách 16/255 đường Láng, Đống Đa, Hà Nội",
    "product_name": "Tủ lạnh LG",
    "auth_code": "1312338",
    "bin": "5339682111",
    "mrc_order_id": "VLAD_1753867524",
    "loan_package": {
      "loan_pack_id": 638,
      "package_name": "Gói vay kỳ hạn 6 tháng",
      "grace_period": 6,
      "conversion_fee": 2.0
    },
    "auth_time": "2020-08-11 14:41:00",
    "total_payment_amount": 10700000,
    "status": 1,
    "installment_fee_amount": 700000,
    "monthly_payment_amount": 1188889,
    "installment_amount": 10700000,
    "order_id": 45467,
    "created_at": "2020-08-11 14:41:00",
    "updated_at": "2020-08-11 15: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
}