Webhook VCN Information Notification

Process

• Baokim calls the MERCHANT's webhook API to send the VCN creation result notification along with the VCN information encrypted using Baokim's encryption mechanism.

• If the Partner does not want to receive the webhook, respond with code = 1600 to reject it.

API Information

URL: Provided by the Merchant

Method: POST

• Header:

  • Content-Type: Application/json

  • Signature: $signature

Baokim Sends to the Partner (Webhook)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String(100)	✅	Unique ID for each Request sent from Baokim to the Merchant
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)	✅	CREATE_VCN
6	reference_id	String(50)	✅	Reference code for the VCN creation request
7	status	Number	✅	VCN creation status 3: Success 4: Failed
8	card_data	Object	❌	Card data NULL if the VCN creation status is failed
9	created_at	DateTime	✅	Time the request was received
10	updated_at	DateTime	✅	Time the request was updated

card_data Information

No.	Field Name	Data Type	Required	Description
1	vcn_id	Number	✅	VCN ID
2	card_info_encrypt	String	✅	Encrypted VCN card data
3	card_status	Number	✅	VCN card status
4	control_type	Number	✅	1: accountControl 2: inControlRules
5	account_control	Object	❌	Required if control_type = 1
6	in_control_rules	Object	❌	Required if control_type = 2

object after decrypting card_data.card_info_encrypt Information

No.	Field Name	Data Type	Required	Description
1	card_number	String	✅	VCN card number
2	cvc	String	✅	Card CVC number
3	expiry	String(7)	✅	Card expiry date
4	card_holder	String	✅	Cardholder name

card_data.account_control Information

No.	Field Name	Data Type	Required	Description
1	alias	String	✅	Unique memorable code for the Control
2	card_limit	Object	❌	Sets the general limit for the card - throughout the card's lifetime
3	monthly_limit	Object	❌	Sets a monthly limit for the card
4	daily_limit	Object	❌	Sets a daily limit for the card
5	weekly_limit	Object	❌	Sets a weekly limit for the card
6	quarterly_limit	Object	❌	Sets a quarterly limit for the card
7	yearly_limit	Object	❌	Sets a yearly limit for the card
8	geographies	Object	❌	Sets card usage by geographic region
9	merchant_category_codes	Object	❌	Sets card usage by MCC
10	start_date	String	❌	Card usage period - Start
11	end_date	String	❌	Card usage period - End

card_data.account_control.card_limit Information

No.	Field Name	Data Type	Required	Description
1	card_amount	Number	✅	Transaction value
2	available_balance	Number	❌	Available balance readOnly -> Pass a value if available; MasterCard only uses it to collect information (if any), not to validate information
3	authorisation_count	Number	✅	Number of transactions

card_data.account_control.monthly_limit Information

No.	Field Name	Data Type	Required	Description
1	card_amount	Number	✅	Transaction value
2	available_balance	Number	❌	Available balance readOnly -> Pass a value if available; MasterCard only uses it to collect information (if any), not to validate information
3	authorisation_count	Number	✅	Number of transactions

card_data.account_control.daily_limit Information

No.	Field Name	Data Type	Required	Description
1	card_amount	Number	✅	Transaction value
2	available_balance	Number	❌	Available balance readOnly -> Pass a value if available; MasterCard only uses it to collect information (if any), not to validate information
3	authorisation_count	Number	✅	Number of transactions

card_data.account_control.weekly_limit Information

No.	Field Name	Data Type	Required	Description
1	card_amount	Number	✅	Transaction value
2	available_balance	Number	❌	Available balance readOnly -> Pass a value if available; MasterCard only uses it to collect information (if any), not to validate information
3	authorisation_count	Number	✅	Number of transactions

card_data.account_control.quarterly_limit Information

No.	Field Name	Data Type	Required	Description
1	card_amount	Number	✅	Transaction value
2	available_balance	Number	❌	Available balance readOnly -> Pass a value if available; MasterCard only uses it to collect information (if any), not to validate information
3	authorisation_count	Number	✅	Number of transactions

card_data.account_control.yearly_limit Information

No.	Field Name	Data Type	Required	Description
1	card_amount	Number	✅	Transaction value
2	available_balance	Number	❌	Available balance readOnly -> Pass a value if available; MasterCard only uses it to collect information (if any), not to validate information
3	authorisation_count	Number	✅	Number of transactions

card_data.account_control.geographies Information

No.	Field Name	Data Type	Required	Description
1	country_codes	Array	✅	List of country codes - 3-character format
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.account_control.merchant_category_codes Information

No.	Field Name	Data Type	Required	Description
1	mccs	Array	✅	List of MCCs
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules Information

No.	Field Name	Data Type	Required	Description
1	alias	String	✅	Unique memorable code for the Control
2	transaction_limits	Object	❌	Sets the amount limit per card transaction
3	geographies	Object	❌	Sets card usage by geographic region
4	velocities	Object	❌	Sets the frequency limit and/or total card transaction amount within a given time period
5	validity_periods	Object	❌	Controls the validity period of the control
6	amount_ranges	Object	❌	Controls the transaction value within a min, max range
7	acceptor_ids	Object	❌	Sets which Merchants/Acquirers the card is allowed to transact with
8	ageing_velocities	Object	❌	Sets and controls the available credit limit on the card
9	curfews	Object	❌	Sets card transaction controls by time slot on given days, and can specify the applicable timezone
10	time_of_days	Object	❌	Sets card transaction controls within specific time slots of each day
11	merchant_category_codes	Object	❌	Sets card transaction controls by the merchant's MCC
12	merchant_names	Object	❌	Sets card transaction controls by Merchant name (card acceptance unit)
13	merchant_amounts	Object	❌	Sets card transaction controls by amount per transaction for a specific currency
14	transaction_environments	Object	❌	Sets card transaction controls by transaction method
15	approve_control	Object	❌	Sets card transaction controls - the entire rule setup will be for approving/declining the transaction
16	entry_modes	Object	❌	Sets transaction controls by card entry type

card_data.in_control_rules.transaction_limits Information

No.	Field Name	Data Type	Required	Description
1	amount	Float	✅	Maximum transaction value per transaction This value is set according to the billing currency of the RCN registered with BPC min: 0 max: 99999999999999
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.geographies Information

No.	Field Name	Data Type	Required	Description
1	country_codes	Array	✅	List of country codes - 3-character format
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.velocities Information

No.	Field Name	Data Type	Required	Description
1	max_trans	Number	✅	Maximum number of transactions allowed within a given time period min: 1 max: 99999999
2	cumulative_limit	Number	❌	Maximum cumulative transaction amount allowed within a given time period If passed as 0 - it means unlimited (ignore this limit setting) min: 0 max: 99999999999999
3	period	String	✅	Applicable period - DAILY -> Daily - WEEKLY -> Weekly - QUARTERLY -> Quarterly - CONTINUOUS -> From the time of setup with no reset date for counting/accumulating (reports whenever the threshold is reached) - MONTHLY -> Monthly - YEARLY -> Yearly
4	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.validity_periods Information

No.	Field Name	Data Type	Required	Description
1	from	String	✅	Start time of the control's validity
2	to	String	✅	End time of the control's validity
3	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.amount_ranges Information

No.	Field Name	Data Type	Required	Description
1	min_amount	Float	✅	Minimum transaction amount min: 0 max: 99999999999999 min_amount < max_amount
2	max_amount	Float	✅	Maximum transaction amount min: 0 max: 99999999999999 min_amount < max_amount
3	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.acceptor_ids Information

No.	Field Name	Data Type	Required	Description
1	acceptors	Object	✅	Can set merchant or acquirer
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.acceptor_ids.acceptors Information

No.	Field Name	Data Type	Required	Description
1	acceptor_id	String	✅	Merchant ID – identifier of the card-accepting unit (merchant) where the transaction takes place.
2	acquirer_id	String	✅	Acquirer ID – identifier of the bank/payment unit (acquirer) processing the transaction for the merchant.

card_data.in_control_rules.ageing_velocities Information

No.	Field Name	Data Type	Required	Description
1	authorization_hold_days	Number	✅	Number of days the transaction on the virtual card is held to calculate when the currently set credit limit resets min: 0 max: 9999
2	cumulative_limit	Number	✅	Total limit If passed as 0 - it means unlimited (ignore this limit setting) min: 0 max: 99999999999999
3	time_zone	String	✅	Timezone applied to calculating the date and time for unholding the transaction to remove it from the availableCredit calculation
4	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.curfews Information

No.	Field Name	Data Type	Required	Description
1	from_time	String	✅	Start time transactions are allowed.
2	to_time	String	✅	End time transactions are allowed (after this time, the transaction is rejected)
3	time_zone	String	❌	Timezone applied to the above time slot Example: UTC
4	days	Array	✅	List of days of the week the limit applies to: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY. Can be passed as multiple values, separated by commas
5	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.time_of_days Information

No.	Field Name	Data Type	Required	Description
1	times	Array	✅	List of objects configuring the time allowed for transactions (after this time, the transaction is rejected) An array of configs can be passed
2	time_zone	String	✅	Timezone applied to the above time slot (fromTime-toTime) Note that the default applied is GMT (not the timezone registered for the RCN) Be sure to pass this in Example: UTC
3	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

Description of the object inside card_data.in_control_rules.time_of_days.times(1)

No.	Field Name	Data Type	Required	Description
1	from_time	String	✅	Start time transactions are allowed.
2	to_time	String	✅	End time transactions are allowed (after this time, the transaction is rejected)
3	days	Array	✅	Days of the week the limit applies to: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY. Can be passed as multiple values, separated by commas

card_data.in_control_rules.merchant_category_codes Information

No.	Field Name	Data Type	Required	Description
1	mccs	Array	✅	List of MCCs
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.merchant_names Information

No.	Field Name	Data Type	Required	Description
1	merchant_names	Array	✅	List of merchant names (sent in field DE43 of the authorization message) This name must match the name in the bank's payment data (field DE43)
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.merchant_amounts Information

No.	Field Name	Data Type	Required	Description
1	value	Float	✅	Maximum amount per transaction according to the currency_code set below min: 0 max: 99999999999999
2	currency_code	String	✅	Currency code according to (ISO) 4217 standard
3	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.transaction_environments Information

No.	Field Name	Data Type	Required	Description
1	environment_codes	Array	✅	List of transaction methods - ATM – Transaction at an automated teller machine. - ECOM – E-commerce transaction (online). - MOTO – Mail Order/Telephone Order (ordered by mail/phone, card and cardholder not present). - PAYPASS – Contactless payment. - POS – In-store transaction (swiped at a POS terminal). - PWCB – Purchase with cash back (Purchase with Cash Back).
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.approve_control Information

No.	Field Name	Data Type	Required	Description
1	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

card_data.in_control_rules.entry_modes Information

No.	Field Name	Data Type	Required	Description
1	mode	String	✅	Card entry type accepted for payment Default: EMV
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

Request Example

{
  "request_id": "818bca12-f0aa-4152-ba27-e3bd4dcb3abe",
  "request_time": "2026-05-21 10:14:14",
  "master_merchant_code": "mmthiither22",
  "sub_merchant_code": "b2bthiither127",
  "operation": "CREATE_VCN",
  "status": 3,
  "reference_id": "TT1774927943",
  "card_data": {
    "vcn_id": 2393,
    "card_info_encrypt": "d3VY98QAQCvAmZsEj8u6JHHE7+sswy7cNluSXPy5HJc6Tf/fl9JFXK/GTdZdetE4sMw/bwjVn7HDRa/7Z2Lqjrmey5BHxYLBizRxZGsLMGSlm8PyBoZg8N8akGpORFa3cgWWbCOJji/MVl56jrN3UzoRgee43B+62HUObWwqAUM=",
    "card_status": 1,
    "control_type": 2,
    "account_control": null,
    "in_control_rules": {
      "alias": "TT1774927943",
      "velocities": {
        "period": "CONTINUOUS",
        "negate": 0,
        "max_trans": 100,
        "cumulative_limit": 1500000
      },
      "curfews": {
        "days": [
          "MONDAY",
          "TUESDAY",
          "WEDNESDAY"
        ],
        "negate": 0,
        "from_time": "00:00",
        "to_time": "23:59",
        "time_zone": "UTC"
      },
      "transaction_limits": {
        "amount": 100,
        "negate": 0
      },
      "validity_periods": {
        "from": "2026-03-31 10:34:22",
        "to": "2035-12-01 00:00:00",
        "negate": 0
      },
      "amount_ranges": {
        "negate": 0,
        "min_amount": 0,
        "max_amount": 100000000
      },
      "acceptor_ids": {
        "acceptors": {
          "acceptor_id": "126548888899997",
          "acquirer_id": "12325435"
        },
        "negate": 0
      },
      "ageing_velocities": {
        "negate": 0,
        "authorization_hold_days": 0,
        "cumulative_limit": 0,
        "time_zone": "UTC"
      },
      "time_of_days": {
        "times": [
          {
            "days": [
              "MONDAY",
              "TUESDAY",
              "WEDNESDAY"
            ],
            "from_time": "00:00",
            "to_time": "23:59"
          }
        ],
        "negate": 0,
        "time_zone": "UTC"
      },
      "merchant_category_codes": {
        "mccs": [
          "3001",
          "3005"
        ],
        "negate": 0
      },
      "merchant_names": {
        "negate": 0,
        "merchant_names": [
          "Amazon"
        ]
      },
      "merchant_amounts": {
        "value": 10000000,
        "negate": 0,
        "currency_code": "704"
      },
      "transaction_environments": {
        "negate": 0,
        "environment_codes": [
          "ECOM",
          "POS"
        ]
      },
      "approve_control": {
        "negate": 0
      },
      "entry_modes": {
        "mode": "EMV",
        "negate": 0
      }
    }
  },
  "created_at": "2026-03-31 10:32:34",
  "updated_at": "2026-05-21 10:14:14"
}

Request Example

{
  "request_id": "818bca12-f0aa-4152-ba27-e3bd4dcb3abe",
  "request_time": "2026-05-21 10:14:14",
  "master_merchant_code": "MASTERMERCHANTCODE",
  "sub_merchant_code": "SUBMERCHANTCODE",
  "operation": "CREATE_VCN",
  "status": 4,
  "reference_id": "TT1774927943",
  "card_data": null,
  "created_at": "2026-03-31 10:32:34",
  "updated_at": "2026-05-21 10:14:14"
}

Partner Responds to Webhook

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	String	✅	code returned to Baokim, confirming that the MERCHANT has received it
2	message	String	✅	Message returned to Baokim
3	data	Object	❌	Merchant data returned to Baokim, if any

Response Example

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