Citi API | Virtual Cards › Controllers

Create VCA for secure purchasing. It allows you to place a VCA creation request, with increased Transaction-Level Controls, limit card number use by MCC, amounts, dates and even specific suppliers

Security

Parameters

country: string

region: string

req-sys-id: string

Body parameters

allowed?: boolean

Indicate whether the values in countryCode are allowed or disallowed

amountLimit?: number

Identifies the maximum allowed transaction amount.

authorizationHoldDays?: number

Identifies the number of days after which an authorization gets aged off if no matching clearing record was received.

countryCodes?: Array<string>

Defines the merchant country in which the VCA can be used.

cumulativeSpendLimit?: number

Limits the overall amount spend on the virtual card account.

curfewTime?: { endTime, startTime, weekdaysEffective }

currencyCode?: string

Currency Code in which VCA amounts are expressed

currencyType?: string

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 the VCA currency is expressed in merchant currency and not in billing currency.

customReference?: Array<{ customReferenceLabel, customReferenceValue }>

enableAgingVelocityControl?: boolean

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.

enableAmountRangeControl?: boolean

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.

enableCurfewControl?: boolean

Limits authorization activity to a single time period for each day selected.

enableGeographyControl?: boolean

Limits authorization requests to a defined geographic location.

enableMerchantIdControl?: boolean

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

enableSpendVelocityControl?: boolean

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.

enableTimeOfDayControl?: boolean

Limits authorization request to defined time periods each day

enableTransactionLimitControl?: boolean

Limits individual transactions to a maximum amount.

enableValidityPeriodControl?: boolean

Limits authorization activity to a specific time period.

expiryDate?: string

Expiry Date of the virtual card account.

fundingSourceId?: string

Unique identifier of the funding source to which the virtual card rolls up

fundingSourceName?: string

Descriptive name of the real card to which the virtual card rolls up

getCardImage?: boolean

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.

maxAmount?: number

Identifies the maximum allowed transaction amount.

mccGrouping?: Array<string>

Limits authorizations to defined Merchant Category Codes.

merchantId?: { acquirerId, allowed, cardAcceptorId, 1 more... }

messageId?: string

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

minAmount?: number

Identifies the minimum allowed transaction amount.

paymentBeneficiaryEmails?: Array<string>

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

paymentBeneficiaryId?: number

Uniquely identifies the payment beneficiary for which the virtual card is created

programId?: string

Unique ID of the company record defined in the virtual cards system

spendVelocity?: Array<{ cumulativeSpendLimit, maxAuth, periodType }>

templateId?: number

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.

timeOfDay?: Array<{ endTime, startTime, weekdayEffective }>

timeZone?: string

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.

validityEndDate?: string

Identifies the date until which the virtual card account can be used for transactions.

validityStartDate?: string

Identifies the date from which the virtual card account can be used for transactions.

vcaId?: number

A reference number that uniquely identifies the virtual card account.

Response fields

allowed?: boolean

Indicate whether the values in countryCode are allowed or disallowed.

amountLimit?: number

Identifies the maximum allowed transaction amount.

authorizationHoldDays?: number

Identifies the number of days after which an authorization gets aged off if no matching clearing record was received.

cardImage?: string

A visual representation of the virtual card account front and back.

countryCodes?: Array<string>

Defines the merchant country in which the VCA can be used.

cumulativeSpendLimit?: number

Limits the overall amount spend on the virtual card account.

curfewTime?: { endTime, startTime, weekdaysEffective }

currencyCode?: string

Currency Code in which VCA amounts are expressed.

currencyType?: string

customReference?: Array<{ customReferenceLabel, customReferenceValue }>

enableAgingVelocityControl?: boolean

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.

enableAmountRangeControl?: boolean

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.

enableCurfewControl?: boolean

Limits authorization activity to a single time period for each day selected.

enableGeographyControl?: boolean

Limits authorization requests to a defined geographic location.

enableMerchantIdControl?: boolean

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

enableSpendVelocityControl?: boolean

Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period.

enableTimeOfDayControl?: boolean

Limits authorization request to defined time periods each day.

enableTransactionLimitControl?: boolean

Limits individual transactions to a maximum amount.

enableValidityPeriodControl?: boolean

Limits authorization activity to a specific time period.

expiryDate?: string

Expiry Date of the virtual card account.

maxAmount?: number

Identifies the maximum allowed transaction amount.

mccGrouping?: Array<string>

Limits authorizations to defined Merchant Category Codes.

merchantInfo?: Array<{ allowed, cardAcceptorId, merchantIds }>

messageId?: string

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.

minAmount?: number

Identifies the minimum allowed transaction amount.

paymentBeneficiaryEmails?: Array<string>

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.

paymentBeneficiaryId?: number

Uniquely identifies the payment beneficiary for which the virtual card is created.

programId?: string

Unique ID of the company record defined in the virtual cards system.

securityCode?: string

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

spendVelocity?: Array<{ availableBalance, cumulativeSpendLimit, maxAuth, 2 more... }>

standInVca?: boolean

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.

templateId?: number

timeOfDay?: Array<{ endTime, startTime, weekdayEffective }>

timeZone?: string

Defines the time zone applicable for any date or time parameters within controls set for a VCA.

validityEndDate?: string

Identifies the date until which the virtual card account can be used for transactions.

validityStartDate?: string

Identifies the date from which the virtual card account can be used for transactions.

vcaId?: string

A reference number that uniquely identifies the virtual card account.

virtualCardAccountNumber?: string

The virtual card account number to use for transactions.

warning?: Array<string>

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

Request example

curl https://$(catalog.host)/cards/vca/v2/create \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d '{}'

200Example

{
  "allowed": true,
  "amountLimit": 0,
  "authorizationHoldDays": 0,
  "cardImage": "cardImage",
  "countryCodes": [
    "string"
  ],
  "cumulativeSpendLimit": 0,
  "curfewTime": {
    "endTime": "endTime",
    "startTime": "startTime",
    "weekdaysEffective": [
      "string"
    ]
  },
  "currencyCode": "currencyCode",
  "currencyType": "currencyType",
  "customReference": [
    {
      "customReferenceLabel": "customReferenceLabel",
      "customReferenceValue": "customReferenceValue"
    }
  ],
  "enableAgingVelocityControl": true,
  "enableAmountRangeControl": true,
  "enableCurfewControl": true,
  "enableGeographyControl": true,
  "enableMerchantIdControl": true,
  "enableSpendVelocityControl": true,
  "enableTimeOfDayControl": true,
  "enableTransactionLimitControl": true,
  "enableValidityPeriodControl": true,
  "expiryDate": "expiryDate",
  "maxAmount": 0,
  "mccGrouping": [
    "string"
  ],
  "merchantInfo": [
    {
      "allowed": true,
      "cardAcceptorId": "cardAcceptorId",
      "merchantIds": [
        {
          "acquirerId": 0,
          "merchantId": "merchantId"
        }
      ]
    }
  ],
  "messageId": "messageId",
  "minAmount": 0,
  "paymentBeneficiaryEmails": [
    "string"
  ],
  "paymentBeneficiaryId": 0,
  "programId": "programId",
  "securityCode": "securityCode",
  "spendVelocity": [
    {
      "availableBalance": 0,
      "cumulativeSpendLimit": 0,
      "maxAuth": 0,
      "periodEndDate": "periodEndDate",
      "periodType": "periodType"
    }
  ],
  "standInVca": true,
  "templateId": 0,
  "timeOfDay": [
    {
      "endTime": "endTime",
      "startTime": "startTime",
      "weekdayEffective": "weekdayEffective"
    }
  ],
  "timeZone": "timeZone",
  "validityEndDate": "validityEndDate",
  "validityStartDate": "validityStartDate",
  "vcaId": "vcaId",
  "virtualCardAccountNumber": "virtualCardAccountNumber",
  "warning": [
    "string"
  ]
}

Modify -> { allowed, amountLimit, authorizationHoldDays, 34 more... }

post/modify

Modify VCA allows to update VCA request, to alter the Transaction-Level control data elements for flexible payments