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 /api/merchant-hosted/bank-transfer/notification

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 trả lại cho Baokim)

Quan trọng

Merchant cần response HTTP 200 với body xác nhận đã nhận thành công. Nếu không nhận được phản hồi hợp lệ, Baokim sẽ gửi lại webhook theo cơ chế retry.

Error Codes

code	message
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