Webhook thông báo giao dịch

Quy trình

Mô tả: Baokim gửi thông báo kết quả giao dịch tới Merchant sau khi nhận tiền từ khách hàng qua VA.

Thông tin API

Method: POST

URL (URL do Merchant cấu hình với Baokim)

Request Headers:

Header	Mô tả
Signature	Digital signature to verify data integrity

Request

(Tham số Baokim gửi cho 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(50)	✅	ID duy nhất của request từ Baokim gửi sang Merchant
2	request_time	Datetime	✅	Thời gian gửi request. Format: YYYY-MM-DD H:m:s
3	merchant_code	String(30)	✅	Mã định danh Merchant trên hệ thống Baokim
4	store_code	String	❌	Mã cửa hàng
5	staff_code	String	❌	Mã nhân viên
6	signature	String	✅	Chữ ký số xác thực request từ Baokim
7	transaction	Object	✅	Thông tin giao dịch
8	va_info	Object	✅	Thông tin tài khoản VA

Thông tin transaction

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	id	Integer	✅	Mã giao dịch trên Baokim
2	order_id	Integer	✅	ID đơn hàng liên kết
3	mrc_order_id	String(50)	✅	Mã đơn hàng merchant
4	type	Integer	✅	1 = Thanh toán, 2 = Hoàn tiền
5	payment_method	Integer	✅	1 = VA
6	merchant_fee	Integer	✅	Phí merchant chịu
7	user_fee	Integer	✅	Phí user chịu
8	total_amount	Integer	✅	Tổng tiền giao dịch (bao gồm phí)
9	amount	Integer	✅	Số tiền merchant thực nhận
10	description	String	❌	Mô tả nội dung giao dịch
11	status	Integer	✅	1 = Thành công
12	bank_code	String(19)	❌	Mã ngân hàng
13	completed_at	Datetime	✅	Thời gian thành công
14	created_at	Datetime	✅	Thời gian tạo
15	updated_at	Datetime	✅	Thời gian cập nhật

Thông tin va_info

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	bank_name	String(255)	✅	Tên ngân hàng VA
2	bank_branch	String(255)	❌	Chi nhánh ngân hàng
3	acc_no	String(50)	✅	Số tài khoản định danh
4	acc_name	String(255)	✅	Tên người nhận
5	qr_string	String	✅	Mã QR dạng text
6	qr_path	String	✅	Đường dẫn ảnh QR

Ví dụ Request

{
  "request_id": "req_20250717154500123",
  "request_time": "2025-07-07 12:00:00",
  "merchant_code": "MERCHANT001",
  "store_code": "STORE001",
  "staff_code": "STORE001",
  "transaction": {
    "id": 555002,
    "order_id": 987654322,
    "mrc_order_id": "ORDER20250717_002",
    "type": 1,
    "payment_method": 1,
    "merchant_fee": 10000,
    "user_fee": 0,
    "total_amount": 2000000,
    "amount": 1990000,
    "description": "Thanh toán đơn hàng qua tài khoản định danh (VA)",
    "status": 1,
    "bank_code": "VCB",
    "completed_at": "2025-07-17 15:45:00",
    "created_at": "2025-07-17 15:43:00",
    "updated_at": "2025-07-17 15:45:00"
  },
  "va_info": {
    "bank_name": "Ngân hàng TMCP Ngoại Thương Việt Nam (Vietcombank)",
    "bank_branch": "Chi nhánh Hà Nội",
    "acc_no": "0123456789012",
    "acc_name": "Nguyen Van A",
    "qr_string": "00020101021238550010A0000007270123000697040300000000000020386304C3A4",
    "qr_path": "https://sandbox.baokim.vn/qr/BK987654322.png"
  },
  "signature": "0xd329a892110ff6a76cdaf650f6e78fcdf1a79eb0c9f6a5a91bd6aa12be223c05"
}

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
}