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 trả lại cho 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	String(3)	❌	Xác nhận đã nhận (0 = thành công)
2	message	String(20)	❌	Message trả về
3	data	String(20)	❌	Dữ liệu trả về nếu có

Ví dụ Response

{
  "code": 0,
  "message": "Success",
  "data": null
}

Bảng mã lỗi

Mã lỗi	Mô tả
100	Thành công
101	Lỗi hệ thống
102	Lỗi nhà cung cấp
104	Lỗi xác thực JWT
105	Chữ ký số không hợp lệ
106	Số tiền đơn hàng không đủ để hoàn tiền
107	Đơn hàng không thể hoàn
108	Đơn hàng không thể hủy
109	Đơn hàng không tồn tại
110	Mã đơn hàng merchant đã tồn tại
422	Lỗi validate