Request
Request body description
vcaIddoubleRequired
A reference number that uniquely identifies the virtual card account.
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
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.
timeZonestringOptional
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.
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.
maxAuthdoubleOptional
Limits the number of authorizations that can be made with a VCA. Should be set to 1, if a single-use VCA is created.Specify any value larger than one for a multi-use VCA. Mastercard: Set to 0, if unlimited authorizations should be allowed. (0 is not applicable for Visa)
modifySpendVelocityControlbooleanOptional
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
modifyValidityPeriodControlbooleanOptional
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.
modifyAmountRangeControlbooleanOptional
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.
modifyTransactionLimitControlbooleanOptional
Limits individual transactions to a maximum amount.
amountLimitdoubleOptional
Identifies the maximum allowed transaction amount.
modifyCurfewControlbooleanOptional
Limits authorization activity to a single time period for each day selected.
modifyTimeOfDayControlbooleanOptional
Limits authorization request to defined time periods each day
timeOfDaylist of objectsOptional
modifyAgingVelocityControlbooleanOptional
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.
modifyGeographyControlbooleanOptional
Limits authorization requests to a defined geographic location.
countryCodeslist of stringsOptional
Defines the merchant country in which the VCA can 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
modifyMerchantIdControlbooleanOptional
Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa).
Response
Modify 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.
modifySpendVelocityControlbooleanOptional
Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period.
spendVelocitylist of objectsOptional
modifyValidityPeriodControlbooleanOptional
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.
modifyAmountRangeControlbooleanOptional
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.
modifyTransactionLimitControlbooleanOptional
Limits individual transactions to a maximum amount.
amountLimitdoubleOptional
Identifies the maximum allowed transaction amount.
modifyCurfewControlbooleanOptional
Limits authorization activity to a single time period for each day selected.
modifyTimeOfDayControlbooleanOptional
Limits authorization request to defined time periods each day.
timeOfDaylist of objectsOptional
modifyAgingVelocityControlbooleanOptional
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.
modifyGeographyControlbooleanOptional
Limits authorization requests to a defined geographic location.
countryCodeslist of stringsOptional
Defines the merchant country in which the VCA can 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
modifyMerchantIdControlbooleanOptional
Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa).
merchantInfolist of objectsOptional
