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

Quy trình

Mô tả:

• Baokim gửi webhook cho Merchant khi mỗi giao dịch được duyệt vay hoặc bị huỷ trả chậm.
• Merchant cần xây dựng API webhook để nhận thông báo này.
• Baokim ký dữ liệu request gửi sang Merchant bằng SHA256withRSA.

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 ứng với mỗi 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 cho đối tác: 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	order_id	Number	✅	Mã đơn hàng Baokim
2	mrc_order_id	String(50)	✅	Mã đơn hàng Merchant
3	merchant_code	String(50)	✅	Mã định danh Merchant
4	customer_name	String(200)	✅	Tên đầy đủ khách hàng, không dấu, có khoảng trắng
5	customer_phone	String(10)	✅	Số điện thoại khách hàng
6	customer_email	String(255)	✅	Email khách hàng
7	customer_address	String(500)	✅	Địa chỉ khách hàng
8	package_code	String(255)	✅	Mã gói vay
9	name	String(20)	✅	Tên gói vay
10	period	Number	✅	Kỳ hạn (1, 3, 6, 9, 12 tháng)
11	min_amount	Number	✅	Số tiền tối thiểu áp dụng gói vay
12	max_amount	Number	✅	Số tiền tối đa áp dụng gói vay
13	down_payment_percent	Number	✅	% số tiền trả trước
14	down_payment_amount	Number	✅	Số tiền trả trước
15	original_amount	Number	✅	Số tiền đơn hàng
16	user_fee	Number	✅	Phí người mua chịu
17	merchant_fee	Number	✅	Phí người bán chịu
18	total_paylater_amount	Number	✅	Tổng số tiền trả sau (đã tính phí)
19	payment_per_period	Number	✅	Số tiền trả mỗi kỳ
20	total_amount	Number	✅	Tổng số tiền user cần thanh toán (trả trước + trả sau)
21	difference_amount	Number	✅	Số tiền chênh lệch so với trả thẳng
22	document_required	String(4)	✅	Giấy tờ cần có (CCCD/CMND)
23	provider_code	String(20)	✅	Tên tổ chức tài chính
24	description	String(255)	✅	Mô tả đơn hàng
25	url_success	String(255)	✅	URL redirect khi duyệt vay thành công
26	url_fail	String(255)	✅	URL redirect khi duyệt vay thất bại
27	status	Number	✅	Trạng thái giao dịch
28	extension	Object	✅	Thông tin mở rộng (danh sách sản phẩm)
29	created_at	Datetime	✅	Thời gian tạo đơn hàng
30	updated_at	Datetime	✅	Thời gian cập nhật đơn hàng

Thông tin extension

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	items	Array	✅	Danh sách object thông tin ngân hàng và gói vay

Thông tin items

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	item_id	String(50)	✅	ID sản phẩm
2	item_code	String(50)	✅	Mã sản phẩm
3	item_name	String(255)	✅	Tên sản phẩm
4	item_amount	Number	✅	Giá tiền sản phẩm
5	quantity	Number	✅	Số lượng sản phẩm
6	url	String(500)	✅	Link sản phẩm

Ví dụ Request

{
  "request_id": "MERCHANT050015588AXE012",
  "request_time": "2020-08-11 14:41:00",
  "merchant_code": "MERCHANT",
  "operation": "PAYMENT/REFUND",
  "data": {
    "order_id": 1870436,
    "mrc_order_id": "VLAD_1753867524",
    "merchant_code": "MERCHANT",
    "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",
    "package_code": "homecredit_1month",
    "name": "Home Credit 1 tháng",
    "period": 1,
    "min_amount": 1000000,
    "max_amount": 500000,
    "down_payment_percent": 20,
    "down_payment_amount": 2000000,
    "original_amount": 10000000,
    "user_fee": 0,
    "merchant_fee": 100000,
    "total_paylater_amount": 8000000,
    "payment_per_period": 8000000,
    "total_amount": 10100000,
    "difference_amount": 100000,
    "document_required": "CCCD",
    "provider_code": "HOMECREDIT",
    "description": "Đơn hàng trả chậm",
    "url_success": "https://example.com/success",
    "url_fail": "https://example.com/fail",
    "status": 1,
    "extension": {
      "items": [
        {
          "item_id": 123456,
          "item_code": "AEIQ_4562",
          "item_name": "Máy tính xách tay ABC",
          "item_amount": 10000000,
          "quantity": 1,
          "url": "https://example.com/product-detail"
        }
      ]
    },
    "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
}