Transaction Notification Webhook

Process

Baokim calls the MERCHANT's webhook API to send notification of the transaction result generated from the VCN card.

API Information

URL: Provided by Merchant

Method: POST

• Header:

  • Content-Type: Application/json

  • Signature: $signature

Baokim Sends to Partner (Webhook)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String(100)	✅	Unique ID for each Request from MERCHANT to Baokim.
2	request_time	String(20)	✅	Request sent time. Format: YYYY-MM-DD H:i:s
3	master_merchant_code	String(50)	✅	Unique identifier for MASTER MERCHANT
4	sub_merchant_code	String(50)	✅	Unique identifier for SUB MERCHANT
5	operation	String(50)	✅	Payment transaction: PAYMENT_ICCP_TRANS Refund/Cancel transaction: REFUND_ICCP_TRANS Reversal transaction: REVERSAL_ICCP_TRANS
6	transaction	Object	✅	Transaction information
7	vcn_info	Object	✅	VCN card information
8	merchant_acceptor_info	Object	✅	Information about the location where the cardholder performed the transaction

transaction Information

No.	Field Name	Data Type	Required	Description
1	id	Number(20)	✅	Transaction code
2	original_transaction_id	Number(20)	❌	Original transaction code (Required if it is a reversal transaction, operation = REVERSAL_ICCP_TRANS)
3	refund_reason	String(255)	❌	Refund reason
4	total_amount	Number(15)	✅	Amount incurred on the VCN card (deducted for payment, added for refund)
5	opening_balance	Number(15)	✅	Opening balance
6	amount	Number(15)	✅	Change in merchant balance (negative for payment, positive for refund)
7	balance	Number(15)	✅	Closing balance after the transaction
8	sub_merchant_fee	Number(15)	✅	Fee borne by the merchant
9	master_merchant_fee_borne	Number(15)	✅	Fee borne by the master merchant
10	master_merchant_fee_shared	Number(15)	✅	Fee shared with the master merchant
11	status	Number(4)	✅	Transaction status 1: success
12	completed_at	DateTime	✅	Transaction completion date
13	auth_code	String(50)	❌	Transaction response code issued by the authorizing organization
14	date_time_transaction_local	DateTime	❌	Time the transaction occurred at the card acceptor's location. Format: YYYY-MM-DD H:i:s
15	settlement_amount	Number	❌	Information about the settlement amount.
16	settlement_currency_code	String(3)	❌	Numeric currency code (e.g. 840)
17	settlement_currency_code_alphabetic	String(3)	❌	Alphabetic currency code (e.g. USD)
18	reversal_indicator	Number	❌	Indicator of whether the transaction is a reversal of a clearing transaction. 1. true 0. false
19	clearing_transaction_id	Number	❌	Clearing transaction code
20	authorization_transaction_id	Number	❌	Authorization transaction code
21	created_at	DateTime	✅	Transaction creation date
22	updated_at	DateTime	✅	Transaction update date

vcn_info Information

No.	Field Name	Data Type	Required	Description
1	vcn_id	Number	✅	VCN ID
2	card_number	String(20)	✅	Masked PAN
3	expiry	String(7)	✅	Expiry date. MM/YYYY

Description of data inside merchant_acceptor_info*(8)*

No.	Field Name	Data Type	Required	Description
1	name	String(255)	❌	Merchant name
2	merchant_category_code	String(4)	❌	MCC code
3	merchant_category_code_description	String(255)	❌	MCC description
4	country_code	String(20)	❌	Country code (ISO numeric)
5	city_name	String(255)	❌	City
6	amount	Number(15)	❌	Amount incurred at the merchant (payment or refund)
7	currency_code	String(20)	❌	Numeric currency code (e.g. 704)
8	currency_code_alphabetic	String(20)	❌	Alphabetic currency code (e.g. USD)
9	local_date_time	String(20)	❌	Transaction date and time at the merchant

Request Example

Payment Transaction Webhook:

{
  "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"
  }
}

Reversal Transaction Webhook:

{
  "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"
  }
}

Refund Transaction Webhook:

{
  "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"
  }
}

Partner Responds to Webhook

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	Integer	✅	Result code. 0, 100 or 200 = Success
2	message	String	✅	Processing result message
3	data	Object	❌	Returned data (if any)

Response Example

{
  "code": 200,
  "message": "Successfully",
  "data": null
}