Webhook thông báo giao dịch

Quy trình

Baokim gọi API webhook của MERCHANT để gửi thông báo kết quả giao dịch được phát sinh từ thẻ VCN.

Thông tin API

URL: Merchant cung cấp

Method: POST

• Header:

  • Content-Type: Application/json

  • Signature: $signature

Baokim gửi lên Đối tác (Webhook)

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	master_merchant_code	String(50)	✅	Mã định danh duy nhất cho MASTER MERCHANT
4	sub_merchant_code	String(50)	✅	Mã định danh duy nhất cho SUB MERCHANT
5	operation	String(50)	✅	GD Thanh toán: PAYMENT_ICCP_TRANS GD Hoàn hủy: REFUND_ICCP_TRANS GD Reversal: REVERSAL_ICCP_TRANS
6	transaction	Object	✅	Thông tin giao dịch
7	vcn_info	Object	✅	Thông tin thẻ VCN
8	merchant_acceptor_info	Object	✅	Thông tin nơi chủ thẻ thực hiện giao dịch

Thông tin transaction

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	id	Number(20)	✅	Mã giao dịch
2	original_transaction_id	Number(20)	❌	Mã giao dịch gốc (Bắt buộc nếu là giao dịch reversal, operation = REVERSAL_ICCP_TRANS)
3	refund_reason	String(255)	❌	Lý do hoàn tiền
4	total_amount	Number(15)	✅	Số tiền phát sinh trên thẻ VCN (trừ khi thanh toán, cộng khi refund)
5	opening_balance	Number(15)	✅	Số dư đầu
6	amount	Number(15)	✅	Biến động số dư merchant (âm khi thanh toán, dương khi refund)
7	balance	Number(15)	✅	Số dư cuối sau giao dịch
8	sub_merchant_fee	Number(15)	✅	Phí merchant chịu
9	master_merchant_fee_borne	Number(15)	✅	Phí master merchant chịu
10	master_merchant_fee_shared	Number(15)	✅	Phí master merchant nhận chia sẻ
11	status	Number(4)	✅	Trạng thái giao dịch 1: thành công
12	completed_at	DateTime	✅	Ngày hoàn thành giao dịch
13	auth_code	String(50)	❌	Mã phản hồi giao dịch do tổ chức cấp phép
14	date_time_transaction_local	DateTime	❌	Thời điểm giao dịch diễn ra tại địa điểm đơn vị chấp nhận thẻ. Format: YYYY-MM-DD H:i:s
15	settlement_amount	Number	❌	Thông tin về số tiền quyết toán (settlement).
16	settlement_currency_code	String(3)	❌	Mã tiền tệ dạng số (vd: 840)
17	settlement_currency_code_alphabetic	String(3)	❌	Mã tiền tệ dạng chữ (vd: USD)
18	reversal_indicator	Number	❌	Chỉ báo giao dịch có phải là đảo (reversal) của một giao dịch clearing hay không. 1. true 0. false
19	clearing_transaction_id	Number	❌	Mã giao dịch Clearing
20	authorization_transaction_id	Number	❌	Mã giao dịch Authorization
21	created_at	DateTime	✅	Ngày tạo giao dịch
22	updated_at	DateTime	✅	Ngày cập nhật giao dịch

Thông tin vcn_info

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	vcn_id	Number	✅	ID của VCN
2	card_number	String(20)	✅	PAN đã mask
3	expiry	String(7)	✅	Ngày hết hạn. MM/YYYY

Mô tả dữ liệu bên trong merchant_acceptor_info*(8)*

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	name	String(255)	❌	Tên merchant
2	merchant_category_code	String(4)	❌	Mã MCC
3	merchant_category_code_description	String(255)	❌	Mô tả MCC
4	country_code	String(20)	❌	Mã quốc gia (ISO numeric)
5	city_name	String(255)	❌	Thành phố
6	amount	Number(15)	❌	Số tiền phát sinh tại merchant (thanh toán hoặc hoàn tiền)
7	currency_code	String(20)	❌	Mã tiền tệ dạng số (vd: 704)
8	currency_code_alphabetic	String(20)	❌	Mã tiền tệ dạng chữ (vd: USD)
9	local_date_time	String(20)	❌	Ngày giờ giao dịch tại merchant

Ví dụ Request

Webhook GD thanh toán:

{
  "request_id": "REQ-20260624-00123456789",
  "request_time": "2026-06-24 10:30:00",
  "master_merchant_code": "MASTER_MERCHANT_CODE",
  "sub_merchant_code": "SUB_MERCHANT_CODE",
  "operation": "PAYMENT_ICCP_TRANS",
  "transaction": {
    "id": 1251960,
    "original_transaction_id": null,
    "refund_reason": null,
    "total_amount": 500000,
    "opening_balance": 10000000,
    "amount": -500000,
    "balance": 9500000,
    "sub_merchant_fee": 5000,
    "master_merchant_fee_borne": 0,
    "master_merchant_fee_shared": 2000,
    "status": 1,
    "completed_at": "2026-06-24 10:29:55",
    "auth_code": "425110",
    "date_time_transaction_local": "2026-06-24 17:29:55",
    "settlement_amount": null,
    "settlement_currency_code": null,
    "settlement_currency_code_alphabetic": null,
    "reversal_indicator": 0,
    "clearing_transaction_id": null,
    "authorization_transaction_id": null,
    "created_at": "2026-06-24 10:29:50",
    "updated_at": "2026-06-24 10:29:55"
  },
  "vcn_info": {
    "vcn_id": 2800,
    "card_number": "526287******6822",
    "expiry": "08/2026"
  },
  "merchant_acceptor_info": {
    "name": "Shopee Vietnam",
    "merchant_category_code": "5411",
    "merchant_category_code_description": "GROCERY STORES, SUPERMARKETS",
    "country_code": "704",
    "city_name": "HANOI",
    "amount": 500000,
    "currency_code": "704",
    "currency_code_alphabetic": "VND",
    "local_date_time": "2026-06-24 17:29:55"
  }
}

Webhook GD reversal:

{
  "request_id": "REQ-20260624-00174256790",
  "request_time": "2026-06-24 11:10:00",
  "master_merchant_code": "MASTER_MERCHANT_001",
  "sub_merchant_code": "SUB_MERCHANT_001",
  "operation": "REFUND_ICCP_TRANS",
  "transaction": {
    "id": 1251962,
    "original_transaction_id": 1251952,
    "refund_reason": null,
    "total_amount": 500000,
    "opening_balance": 9500000,
    "amount": 500000,
    "balance": 10000000,
    "sub_merchant_fee": 5000,
    "master_merchant_fee_borne": 0,
    "master_merchant_fee_shared": 2000,
    "status": 1,
    "completed_at": "2026-06-25 13:01:55",
    "auth_code": "425110",
    "date_time_transaction_local": "2026-06-25 13:01:55",
    "settlement_amount": null,
    "settlement_currency_code": null,
    "settlement_currency_code_alphabetic": null,
    "reversal_indicator": 0,
    "clearing_transaction_id": null,
    "authorization_transaction_id": null,
    "created_at": "2026-06-25 13:01:55",
    "updated_at": "2026-06-25 13:01:57"
  },
  "vcn_info": {
    "vcn_id": 2800,
    "card_number": "526287******6822",
    "expiry": "08/2026"
  },
  "merchant_acceptor_info": {
    "name": "Shopee Vietnam",
    "merchant_category_code": "5411",
    "merchant_category_code_description": "GROCERY STORES, SUPERMARKETS",
    "country_code": "704",
    "city_name": "HANOI",
    "amount": 500000,
    "currency_code": "704",
    "currency_code_alphabetic": "VND",
    "local_date_time": "2026-06-25 13:01:55"
  }
}

Webhook GD Hoàn tiền:

{
  "request_id": "REQ-20260624-00123452790",
  "request_time": "2026-06-24 12:15:00",
  "master_merchant_code": "MASTER_MERCHANT_001",
  "sub_merchant_code": "SUB_MERCHANT_001",
  "operation": "REFUND_ICCP_TRANS",
  "transaction": {
    "id": 1251965,
    "original_transaction_id": null,
    "refund_reason": null,
    "total_amount": 500000,
    "opening_balance": 9500000,
    "amount": 500000,
    "balance": 10000000,
    "sub_merchant_fee": 5000,
    "master_merchant_fee_borne": 0,
    "master_merchant_fee_shared": 2000,
    "status": 1,
    "completed_at": "2026-06-25 13:01:55",
    "auth_code": "425110",
    "date_time_transaction_local": "2026-06-25 13:01:55",
    "settlement_amount": null,
    "settlement_currency_code": null,
    "settlement_currency_code_alphabetic": null,
    "reversal_indicator": 0,
    "clearing_transaction_id": null,
    "authorization_transaction_id": null,
    "created_at": "2026-06-25 13:01:55",
    "updated_at": "2026-06-25 13:01:57"
  },
  "vcn_info": {
    "vcn_id": 2800,
    "card_number": "526287******6822",
    "expiry": "08/2026"
  },
  "merchant_acceptor_info": {
    "name": "Shopee Vietnam",
    "merchant_category_code": "5411",
    "merchant_category_code_description": "GROCERY STORES, SUPERMARKETS",
    "country_code": "704",
    "city_name": "HANOI",
    "amount": 500000,
    "currency_code": "704",
    "currency_code_alphabetic": "VND",
    "local_date_time": "2026-06-25 13:01:55"
  }
}