Create VCN

⚠️ This API returns the result of receiving the request, not the final VCN creation result (status only has value 2-Processing or 4-Failed). The actual VCN creation result (card information) is sent via Webhook notifying VCN information.

Process

• MERCHANT calls this API to create a VCN.

API Information

URL: /b2b-iccp-service/api/ext/mm/iccp/vcn-create

Method: POST

Request

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	reference_id	String(50)	✅	Reference code
6	customer_name	String(255)	✅	Customer name
7	expiry	String(7)	✅	VCN card expiry date, format MM/YYYY expiry must be at least 1 month greater than the current time and max 24 months from the current time
8	control_type	Number	✅	1: accountControl 2: inControlRules
9	account_control	Object	❌	Required if control_type = 1
10	in_control_rules	Object	❌	Required if control_type = 2
11	real_card_guid	String	✅	Card identifier of the physical RCN card provided by Baokim

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 overall limit for the card - throughout the card's lifetime
3	monthly_limit	Object	❌	Sets the monthly limit for the card
4	daily_limit	Object	❌	Sets the daily limit for the card
5	weekly_limit	Object	❌	Sets the weekly limit for the card
6	quarterly_limit	Object	❌	Sets the quarterly limit for the card
7	yearly_limit	Object	❌	Sets the 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 time - Start
11	end_date	String	❌	Card usage time - 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

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 specific 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 control over 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 control over card transactions by time slot on specific days, and can specify the applicable time zone
10	time_of_days	Object	❌	Sets control over card transactions within specific time slots of each day
11	merchant_category_codes	Object	❌	Sets control over card transactions by merchant MCC code
12	merchant_names	Object	❌	Sets control over card transactions by Merchant name (card acceptor)
13	merchant_amounts	Object	❌	Sets control over card transactions by amount per transaction for a specific currency
14	transaction_environments	Object	❌	Sets control over card transactions by Transaction Method
15	approve_control	Object	❌	Sets control over card transactions - The entire rule set will be used to approve/decline transactions
16	entry_modes	Object	❌	Sets control over transactions by card type

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 based on 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 specific time period min: 1 max: 99999999
2	cumulative_limit	Number	❌	Maximum cumulative transaction amount allowed within a specific time period If passed as 0 - equivalent to 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 the count/accumulation (reported 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	✅	Control validity start time
2	to	String	✅	Control validity end time
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 be set to merchant or acquirer
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

Description of the data inside in_control_rules.acceptor_ids.acceptors(1)

No.	Field Name	Data Type	Required	Description
1	acceptor_id	String	✅	Merchant ID – identifier of the merchant (card acceptor) where the transaction takes place.
2	acquirer_id	String	✅	Acquirer ID – identifier of the bank/payment entity (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 the transaction on the virtual card is held, used to calculate when to reset the currently configured Credit limit min: 0 max: 9999
2	cumulative_limit	Number	✅	Total limit If passed as 0 - equivalent to 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 so it is excluded from the availableCredit 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 slot Example: UTC
4	days	Array	✅	List of days of the week the limit applies to: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY. 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 configuration objects for 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 slot (fromTime-toTime) Note: 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 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 declined)
3	days	Array	✅	Days of the week the limit applies to: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY. 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 the (ISO) 4217 standard Default: 704
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 (transaction placed by mail/phone, card and cardholder not present). - PAYPASS – Contactless payment. - POS – In-store transaction (swiped on a POS machine). - 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	✅	Card acceptance type Default: EMV
2	negate	Number	✅	Determines whether the rule is applied in reverse? 1. true 0. false => Default

Request Example

{
  "request_id": "TT20260209163542",
  "request_time": "2026-03-24 16:28:32",
  "master_merchant_code": "MASTERMERCHANTCODE",
  "sub_merchant_code": "SUBMERCHANTCODE",
  "reference_id": "TT20260209163542",
  "customer_name": "NGUYỄN VĂN A",
  "expiry": "12/2026",
  "control_type": 1,
  "account_control": {
    "alias": "TT20260209163542",
    "card_limit": {
      "card_amount": 10000000000,
      "available_balance": 0,
      "authorisation_count": 100
    },
    "daily_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "weekly_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "monthly_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "quarterly_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "yearly_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "geographies": {
      "country_codes": [
        "704",
        "840"
      ],
      "negate": 0
    },
    "merchant_category_codes": {
      "mccs": [
        "3001",
        "3005"
      ],
      "negate": 0
    },
    "start_date": "2025-12-01",
    "end_date": "2035-12-01"
  },
  "real_card_guid": "real_card_guid_test"
}

Request Example

{
  "request_id": "TT20260209163542",
  "request_time": "2026-03-24 15:33:06",
  "master_merchant_code": "MASTERMERCHANTCODE",
  "sub_merchant_code": "SUBMERCHANTCODE",
  "reference_id": "TT20260209163542",
  "customer_name": "NGUYỄN VĂN A",
  "expiry": "12/2026",
  "control_type": 2,
  "in_control_rules": {
    "alias": "TT20260209163542",
    "transaction_limits": {
      "amount": 100,
      "negate": 0
    },
    "velocities": {
      "max_trans": 100,
      "cumulative_limit": 1500000,
      "period": "CONTINUOUS",
      "negate": 0
    },
    "validity_periods": {
      "from": "2026-07-24 15:35:06",
      "to": "2035-12-01 00:00:00",
      "negate": 0
    },
    "acceptor_ids": {
      "acceptors": {
        "acceptor_id": "126548888899997",
        "acquirer_id": "12325435"
      },
      "negate": 0
    },
    "ageing_velocities": {
      "authorization_hold_days": 0,
      "cumulative_limit": 0,
      "time_zone": "UTC",
      "negate": 0
    },
    "time_of_days": {
      "times": [
        {
          "from_time": "00:00",
          "to_time": "23:59",
          "days": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY"
          ]
        }
      ],
      "time_zone": "UTC",
      "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
    }
  },
  "real_card_guid": "real_card_guid_test"
}

Response

Main Parameters Table

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

data Information

No.	Field Name	Data Type	Required	Description
1	reference_id	String	✅	Reference code for the VCN creation request
2	status	Number	✅	VCN creation status 2: Processing 4: Failed
3	created_at	DateTime	✅	Request received time
4	updated_at	DateTime	✅	Request updated time

Response Example - when the request is created successfully

{
  "code": 100,
  "message": "Success",
  "data": {
    "reference_id": "MERCHANT1774336134305",
    "status": 2,
    "created_at": "2026-03-24 16:33:47",
    "updated_at": "2026-03-24 16:33:47"
  }
}

Response Example - when the request creation fails

{
  "code": 11,
  "message": "Fail",
  "data": {
    "reference_id": "MERCHANT1774336134305",
    "status": 4,
    "created_at": "2026-03-24 16:33:47",
    "updated_at": "2026-03-24 16:33:47"
  }
}

Error Codes

Error Code	Description
100	Success
11	Failed
104	Unauthorized
401	Merchant verify failed
422	Validation error
1000	Failed to save ICCP request
1001	Failed to save VCN card
1100	JWT is invalid or has expired
1101	Signature verification failed
1200	master_merchant_code and sub_merchant_code do not match the real_card_guid configuration
1202	real_card_guid does not exist
1500	Request {request_id} already exists
1501	reference_id already exists
1502	Alias already exists