Query VCN

Process

Merchant calls this API to query a VCN in case the VCN creation request times out or the VCN creation webhook is not received.

API Information

URL: /b2b-iccp-service/api/ext/iccp/vcn-inquery

Method: POST

Request

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String	✅	Unique ID for each Request from MERCHANT to Baokim.
2	request_time	String	✅	Request sent time. Format: YYYY-MM-DD H:i:s
3	master_merchant_code	String	✅	Unique identifier for MASTER MERCHANT
4	sub_merchant_code	String	✅	Unique identifier for SUB MERCHANT
5	reference_id	String	✅	Reference code for the VCN creation request

Request Example

{
    "request_id": "MERCHANT050015588AXE014",
    "request_time": "2025-08-11 14:41:00",
    "master_merchant_code": "MASTERMERCHANTCODE",
    "sub_merchant_code": "SUBMERCHANTCODE",
    "reference_id": "RF_123456789abcxyz"
}

Response

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	Number	✅	Baokim error code
2	message	String	✅	Baokim error code message
3	data	Object	✅	Data returned by Baokim

data Information

No.	Field Name	Data Type	Required	Description
1	master_merchant_code	String	✅	Unique identifier for MASTER MERCHANT
2	sub_merchant_code	String	✅	Unique identifier for SUB MERCHANT
3	reference_id	String	✅	Reference code for the VCN creation request
4	status	Number	✅	VCN creation status 1. Initiated 2. Processing 3. Success 4. Failed
5	card_data	Object	❌	Card data
6	created_at	DateTime	✅	Time the request was received
7	updated_at	DateTime	✅	Time the request was updated

data.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 data.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

data.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	❌	General limit settings for the card - throughout the card's lifetime
3	monthly_limit	Object	❌	Monthly limit settings for the card
4	daily_limit	Object	❌	Daily limit settings for the card
5	weekly_limit	Object	❌	Weekly limit settings for the card
6	quarterly_limit	Object	❌	Quarterly limit settings for the card
7	yearly_limit	Object	❌	Yearly limit settings for the card
8	geographies	Object	❌	Card usage settings by geographic region
9	merchant_category_codes	Object	❌	Card usage settings by MCC
10	start_date	String	❌	Card usage period - Start
11	end_date	String	❌	Card usage period - End

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

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

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

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

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

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

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

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

data.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	❌	Amount limit settings per card transaction
3	geographies	Object	❌	Card usage settings by geographic region
4	velocities	Object	❌	Settings for limiting the frequency and/or total transaction amount of the card within a given 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	❌	Settings that control which Merchants/Acquirers the card is allowed to transact with
8	ageing_velocities	Object	❌	Settings and controls for the available credit limit on the card
9	curfews	Object	❌	Settings that control card transactions by time window on specific days, and can define the applicable time zone
10	time_of_days	Object	❌	Settings that control card transactions within specific time windows of each day
11	merchant_category_codes	Object	❌	Settings that control card transactions by the merchant's MCC
12	merchant_names	Object	❌	Settings that control card transactions by Merchant name (card acceptance unit)
13	merchant_amounts	Object	❌	Settings that control card transactions by the amount per transaction in a specific currency
14	transaction_environments	Object	❌	Settings that control card transactions by transaction method
15	approve_control	Object	❌	Settings that control card transactions - All configured rules will be used to approve/decline the transaction
16	entry_modes	Object	❌	Settings that control transactions by card entry mode

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 up 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

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

in_control_rules.velocities Information

No.	Field Name	Data Type	Required	Description
1	max_trans	Number	✅	Maximum number of transactions allowed within a given period - min: 1 - max: 99999999
2	cumulative_limit	Number	❌	Maximum cumulative transaction amount allowed within a given period If passed as 0, it means - unlimited (this limit setting is ignored) - 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 (a notification is triggered 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

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

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

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

in_control_rules.acceptor_ids.acceptors Information

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

in_control_rules.ageing_velocities Information

No.	Field Name	Data Type	Required	Description
1	authorization_hold_days	Number	✅	Number of days to hold transactions on the virtual card to calculate when to reset the configured credit limit min: 0 max: 9999
2	cumulative_limit	Number	✅	Total limit If passed as 0 - it means unlimited (this limit setting is ignored) min: 0 max: 99999999999999
3	time_zone	String	✅	Time zone applied for calculating the date and time to unhold the transaction in order to remove it from the available credit calculation
4	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

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 declined)
3	time_zone	String(3)	❌	Time zone applied to the above time window 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

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 declined) An array of configs can be passed
2	time_zone	String	✅	Time zone applied to the above time window (fromTime-toTime) Note: the default applied is GMT (not the timezone registered for the RCN) Be sure to pass this value in Example: UTC
3	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

in_control_rules.time_of_days.times 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 declined)
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

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

in_control_rules.merchant_names Information

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

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 applied according to ISO 4217 standard
3	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

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 (card and cardholder not present). - PAYPASS – Contactless payment. - POS – In-store transaction (swiped on a POS terminal). - PWCB – Purchase with Cash Back.
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

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

in_control_rules.entry_modes Information

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

Response Example

{
  "code": 100,
  "message": "Success",
  "data": {
    "master_merchant_code": "MASTERMERCHANTCODE",
    "sub_merchant_code": "SUBMERCHANTCODE",
    "reference_id": "RF_123456789abcxyz",
    "status": 3,
    "card_data": {
      "vcn_id": 423677,
      "card_info_encrypt": "eyJpdiI6InpRUktuZFZleHZCbUhNcXA0aUdyMEE9PSIsInZhbHVlIjoibTlTdllGK0l1elQ1REh4d0FiSFJZcEhxKzBIUmdmOTZWcDdCRzVuNnpIRTBRMm9BS0VVN3cyN1BzMUM3Q1dBOVlEbUt4UzByTjQwazgramtpOWMxV2F6cWNRMlBGMXFmYXN2UHZKMnNaUkkvc1gyTVBiYnI4bUEyVFJMMU5uYmQwQWd5cGZGWXl2RDdVNHhKZVY4dWtSWENYblBRQWtWMWpldWYveGdPU2JIc2pZNkNBSjZqR1NJODE5ZHFFd2ZLTE95OHFHQzViNG8xWXhvOHd4dkQzY2JoakVMUDZQaTZOSnl4aWV0dkJtL2t3M1kybFhubXhYQ3JZd2hJYmxrSjBpc1ora0YrYm5tcUhVdnUvMTlaK1Rpc280RFJHWHduM1B3UzNYR21mUkhYK1VObU1Xd21wQnQrVG9YVUxMUkV3ckticTArcUc1R3hYK0NIT1cxd0hlbzJhT0xYU1BuNVFUVkc2STcvTFEwPSIsIm1hYyI6ImJhZjQxYmM5ZWJiZTFjODEzYWI3NzMxYTg2ZTgwYWMwN2QxNWJlYWFkNzdlZGI3NzE5MjlkMjdlY2IyNDkyZGIifQ==",
      "card_status": 1,
      "control_type": 2,
      "account_control": null,
      "in_control_rules": {
        "alias": "Virtual Card Complex Rules",
        "transaction_limits": {
          "amount": 10000000000,
          "negate": 0
        },
        "geographies": {
          "country_codes": [
            "704",
            "840"
          ],
          "negate": 0
        },
        "velocities": {
          "max_trans": 9999999,
          "cumulative_limit": 1500,
          "period": "CONTINUOUS",
          "negate": 0
        },
        "validity_periods": {
          "from": "2025-12-01 00:00:00",
          "to": "2035-12-01 00:00:00",
          "negate": 0
        },
        "amount_ranges": {
          "min_amount": 100000,
          "max_amount": 100000000,
          "negate": 0
        },
        "acceptor_ids": {
          "acceptors": {
            "acceptor_id": "12315341236547",
            "acquirer_id": "1232135435"
          },
          "negate": 0
        },
        "ageing_velocities": {
          "authorization_hold_days": 30,
          "cumulative_limit": 0,
          "time_zone": "UTC",
          "negate": 0
        },
        "curfews": {
          "from_time": "00:00",
          "to_time": "23:59",
          "time_zone": "UTC",
          "days": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY"
          ],
          "negate": 0
        },
        "time_of_days": {
          "times": [
            {
              "from_time": "00:00",
              "to_time": "23:59",
              "days": [
                "MONDAY",
                "TUESDAY",
                "WEDNESDAY"
              ]
            }
          ],
          "time_zone": "UTC",
          "negate": 0
        },
        "merchant_category_codes": {
          "mccs": [
            "3001",
            "3005"
          ],
          "negate": 0
        },
        "merchant_names": {
          "merchant_names": [
            "Amazon"
          ],
          "negate": 0
        },
        "merchant_amounts": {
          "value": 10000000,
          "currency_code": "704",
          "negate": 0
        },
        "transaction_environments": {
          "environment_codes": [
            "ECOM",
            "POS"
          ],
          "negate": 0
        },
        "approve_control": {
          "negate": 0
        },
        "entry_modes": {
          "mode": "EMV",
          "negate": 0
        }
      }
    },
    "created_at": "2026-05-01 10:51:30",
    "updated_at": "2026-05-01 10:51:30"
  }
}

Error Codes

Error Code	Description
100	Success
11	Failed
401	Merchant verify failed
422	Validation error
1201	vcn_id does not exist