Skip to navigation
Virtual Card Management

Create Virtual Card Accounts

View as Markdown

Create a virtual card and set its associated spending controls, custom reference data and payment beneficiaries. It allows you to place a a virtual card account creation request for secure purchasing, with increased transaction-Level controls, limit card number use by MCC, amounts, dates and even specific suppliers.

Note: In a Create VCA Request call for a Mastercard program, you must specify at least one instance of whichever velocity control the purchase template that is setup in the VCA application contains. Other controls are optional in the API request to Citi, even if they are included in the purchase template that is setup in the VCA application. If you indicate that you would like to use an optional control by sending the enable flag as TRUE, you have to specify all parameters listed in the control section unless otherwise specified, else, the API request will be rejected.

Authentication

AuthorizationBearer

Headers

AuthorizationstringRequired
Oauth token
countrystringRequired
country of the Client
regionstringRequired

region of the client(Apac/EMEA/NAM)

req-sys-idstringRequired

Client Unique id to identify the particular request.
Format: UUID
Example: 123d837e-958a-4e9f-bc97-4843ec948123

Request

Request body description
fundingSourceIdstringRequired
Unique identifier of the funding source to which the virtual card rolls up
programIdstringRequired
Unique ID of the company record defined in the virtual cards system
messageIdstringRequired
Unique ID of the API message sent. The messageId will be provided back in the corresponding response. The ID can be used for investigation and troubleshooting. The ID must be unique per integration
timeZonestringRequired

Defines the time zone applicable for any date or time parameters within controls set for a VCA.If any of the following controls are used, timeZone is required:Validity Period Control,Aging Velocity Control (Mastercard only), Curfew Control and Time of Day Control.It sets the specific timeframe when the account and its controls will become active.

customReferencelist of objectsRequired
fundingSourceNamestringOptional
Descriptive name of the real card to which the virtual card rolls up
mccGroupinglist of stringsOptional
Limits authorizations to defined Merchant Category Codes.
mccRangelist of stringsOptional

Limits authorizations to a defined range of Merchant Category Codes.(eg: [0000-9999, 2000-2999])

mccgAllowedbooleanOptional

Required if the mccGrouping field is populated with either a range of MCCs, or a MCCG (ex: AUTO, AIR).Specify whether the mccGrouping are allowed or disallowed.If true is passed, the mccGrouping are allowed.If false is passed, then the mccGrouping field are disallowed

getCardImagebooleanOptional

  • Specifies whether cardImage field needs to be included in the response or not.

  • True = cardImage field will be sent in the response

  • False = cardImage field will not be sent in the response.

  • Optional field if not included, cardImage will be sent in the response.

currencyCodestringOptional

Currency Code in which VCA amounts are expressed. Mastercard currencyCode is not required if currencyType = B” Visa Specifies whether Merchant transactions are limited to the VCA currency provided in the currencyCode field. The only possibe value is “M”. Value “M” stands for Merchant Currency which indicates that merchant transactions are limited to the VCA currency specified in the currencyCpde field. If a currencyType is not provided, then the VCA can be used for any merchant transaction currency.

currencyTypestringOptional

Mastercard Defines the type of the VCA currency. - Value “B” stands for Billing Currency which indicates that the VCA currency is equal to the billing currency of the underlying funding source. - Value “M” stands for Merchant Currency which indicates that Merchant transactions are limited to the VCA currency provided in the currencyCode field. Visa Specifies whether Merchant transactions are limited to the VCA currency provided in the currencyCode field. The only possibe value is “M”. - Value “M” stands for Merchant Currency which indicates that merchant transactions are limited to the VCA currency specified in the currencyCpde field. If a currencyType is not provided, then the VCA can be used for any merchant transaction currency.

paymentBeneficiaryIddoubleOptional
Uniquely identifies the payment beneficiary for which the virtual card is created
paymentBeneficiaryEmailslist of stringsOptional

Lists the email addresses to which the virtual card details should be sent to.In order for emails to get delivered, the following two settings must be enabled in the VCA system:1. Allow VCN details to be emailed to this supplier2. Allow VCN requestor to manually enter a new email address when requesting a VCN

templateIddoubleOptional
Identifies the template that was setup in the VCA system and that should be used for this virtual card.The template setup in the VCA system defines which controls, custom data fields and MCC groupings can be used.
expiryDatestringOptional
Expiry Date of the virtual card account.
cumulativeSpendLimitdoubleOptional
Limits the overall amount spend on the virtual card account.
enableSpendVelocityControlbooleanOptional

Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period. Mastercard: The control is mandatory unless Aging Velcotiy Control is used. This control cannot be used in combination with the Aging Velocity Control.Visa: Spend Velocity Control is mandatory.

spendVelocitylist of objectsOptional
enableValidityPeriodControlbooleanOptional
Limits authorization activity to a specific time period.
validityStartDatestringOptional
Identifies the date from which the virtual card account can be used for transactions.
validityEndDatestringOptional
Identifies the date until which the virtual card account can be used for transactions.
enableAmountRangeControlbooleanOptional
Approves a transaction only if the requested amount for authorization is equal to or greater than the Minimum Amount and less than or equal to the Maximum Amount.
maxAmountdoubleOptional
Identifies the maximum allowed transaction amount.
minAmountdoubleOptional
Identifies the minimum allowed transaction amount.
enableTransactionLimitControlbooleanOptional
Limits individual transactions to a maximum amount.
amountLimitdoubleOptional
Identifies the maximum allowed transaction amount.
enableCurfewControlbooleanOptional
Limits authorization activity to a single time period for each day selected.
curfewTimeobjectOptional
enableTimeOfDayControlbooleanOptional
Limits authorization request to defined time periods each day
timeOfDaylist of objectsOptional
enableAgingVelocityControlbooleanOptional
Sets a cumulative amount and keeps track of the current remaining balance. Allows the requester to 'age off' approved authorization requests that have not been cleared by the merchant after a defined number of days.
authorizationHoldDaysdoubleOptional
Identifies the number of days after which an authorization gets aged off if no matching clearing record was received.
enableGeographyControlbooleanOptional
Limits authorization requests to a defined geographic location. This is an optional control. If this control is not used, pass False or leave this section out from the request. If value passed is True, all fields in this section are required.
countryCodeslist of stringsOptional
Defines the merchant country in which the VCA can or cannot be used.
allowedbooleanOptional

Indicate whether the values in countryCode are allowed or disallowed. True = values provided in countryCode are allowed False = values provided in countryCode are not allowed

enableMerchantIdControlbooleanOptional

Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa).

merchantIdobjectOptional

Response

Create Virtual Card response
vcaIdstringOptional
A reference number that uniquely identifies the virtual card account.
cardImagestringOptional
A visual representation of the virtual card account front and back.
currencyCodestringOptional

Currency Code in which VCA amounts are expressed. Mastercard currencyCode is not required if currencyType = B” Visa Specifies whether Merchant transactions are limited to the VCA currency provided in the currencyCode field. The only possibe value is “M”. Value “M” stands for Merchant Currency which indicates that merchant transactions are limited to the VCA currency specified in the currencyCpde field. If a currencyType is not provided, then the VCA can be used for any merchant transaction currency.

timeZonestringOptional
Defines the time zone applicable for any date or time parameters within controls set for a VCA.
virtualCardAccountNumberstringOptional
The virtual card account number to use for transactions.
expiryDatestringOptional
Expiry Date of the virtual card account.
securityCodestringOptional

The security code (i.e. cvv) corresponding to the virtual card accunt.

programIdstringOptional
Unique ID of the company record defined in the virtual cards system.
messageIdstringOptional
Unique ID of the API message sent. The messageId will be provided back in the corresponding response. The ID can be used for investigation and troubleshooting. The ID must be unique per integration.
mccGroupinglist of stringsOptional
Limits authorizations to defined Merchant Category Codes.
mccRangelist of stringsOptional

Limits authorizations to a defined range of Merchant Category Codes.(eg: [0000-9999, 2000-2999])

mccgAllowedbooleanOptional

Required if the mccGrouping field is populated with either a range of MCCs, or a MCCG (ex: AUTO, AIR).Specify whether the mccGrouping are allowed or disallowed.If true is passed, the mccGrouping are allowed.If false is passed, then the mccGrouping field are disallowed

currencyTypestringOptional

Mastercard Defines the type of the VCA currency. - Value “B” stands for Billing Currency which indicates that the VCA currency is equal to the billing currency of the underlying funding source. - Value “M” stands for Merchant Currency which indicates that Merchant transactions are limited to the VCA currency provided in the currencyCode field. Visa Specifies whether Merchant transactions are limited to the VCA currency provided in the currencyCode field. The only possibe value is “M”. - Value “M” stands for Merchant Currency which indicates that merchant transactions are limited to the VCA currency specified in the currencyCpde field. If a currencyType is not provided, then the VCA can be used for any merchant transaction currency.

paymentBeneficiaryIddoubleOptional
Uniquely identifies the payment beneficiary for which the virtual card is created.
paymentBeneficiaryEmailslist of stringsOptional
Specifies up to five email addresses to which the virtual card account details should be delivered. Email addresses specified in the request will not override any default email addresses specified in the virtual card application.
customReferencelist of objectsOptional
templateIddoubleOptional
Identifies the template that was setup in the VCA system and that should be used for this virtual card.The template setup in the VCA system defines which controls, custom data fields and MCC groupings can be used.
cumulativeSpendLimitdoubleOptional
Limits the overall amount spend on the virtual card account.
standInVcabooleanOptional

Indicates whether the VCA details returned are generated from the VCA platform, or a pre-generated VCA from Citi. If “true” is returned then the VCA returned is a pre-generated VCA from Citi. If the “false” is returned or if the field is not returned then the VCA returned is from the backend VCA platform.

warninglist of stringsOptional

Warning information regarding a non-fatal response condition that may be taken into account, but can be ignored

enableSpendVelocityControlbooleanOptional
Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period.
spendVelocitylist of objectsOptional
enableValidityPeriodControlbooleanOptional
Limits authorization activity to a specific time period.
validityStartDatestringOptional
Identifies the date from which the virtual card account can be used for transactions.
validityEndDatestringOptional
Identifies the date until which the virtual card account can be used for transactions.
enableAmountRangeControlbooleanOptional
Approves a transaction only if the requested amount for authorization is equal to or greater than the Minimum Amount and less than or equal to the Maximum Amount.
maxAmountdoubleOptional
Identifies the maximum allowed transaction amount.
minAmountdoubleOptional
Identifies the minimum allowed transaction amount.
enableTransactionLimitControlbooleanOptional
Limits individual transactions to a maximum amount.
amountLimitdoubleOptional
Identifies the maximum allowed transaction amount.
enableCurfewControlbooleanOptional
Limits authorization activity to a single time period for each day selected.
curfewTimeobjectOptional
enableTimeOfDayControlbooleanOptional
Limits authorization request to defined time periods each day.
timeOfDaylist of objectsOptional
enableAgingVelocityControlbooleanOptional
Sets a cumulative amount and keeps track of the current remaining balance. Allows the requester to age off approved authorization requests that have not been cleared by the merchant after a defined number of days.
authorizationHoldDaysdoubleOptional
Identifies the number of days after which an authorization gets aged off if no matching clearing record was received.
enableGeographyControlbooleanOptional
Limits authorization requests to a defined geographic location. This is an optional control. If this control is not used, pass False or leave this section out from the request. If value passed is True, all fields in this section are required.
countryCodeslist of stringsOptional
Defines the merchant country in which the VCA can or cannot be used.
allowedbooleanOptional

Indicate whether the values in countryCode are allowed or disallowed. True = values provided in countryCode are allowed False = values provided in countryCode are not allowed

enableMerchantIdControlbooleanOptional

Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa).

merchantInfolist of objectsOptional

Errors

400
Bad Request Error
401
Unauthorized Error
405
Method Not Allowed Error
500
Internal Server Error