openapi: 3.0.0 info: description: Virtual Card Create Notification request. version: 1.0.0 title: VCA Life Cycle Webhook Client Notification servers: - url: / description: Default server security: - OAuth2: - read - write components: securitySchemes: BasicAuth: type: http scheme: basic ApiKeyAuth: type: apiKey in: header name: X-API-Key OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://tts.apib2b.citi.com/tts/api/v1/oauth2/authorize tokenUrl: https://tts.apib2b.citi.com/tts/api/v1/oauth2/token scopes: read: Grants read access write: Grants write access admin: Grants read and write access to administrative information schemas: ErrorMessage: type: object properties: errorCode: type: string enum: - EVB0401 - EVB0404 - EVB0430 - EVB0431 - EVB0432 - EVB0435 - EVB0436 - EVB0437 - EVB0438 - EVB0406 - EVB0440 - EVB0441 - EVB0442 - EVB0443 - EVB0427 - EVB0445 - EVB0446 - EVB0447 - EVB0448 - EVB0449 - EVB0450 - EVB0452 - EVB0453 - EVB0454 - EVB0455 - EVB0456 - EVB0457 - EVB0426 - EVB0459 - EVB0460 - EVB0461 - EVB0462 - EVB0444 - EVB0465 - EVB0466 - EVB0468 - EVB0469 - EVB0470 - EVB0471 - EVB0472 - EVB0473 - EVB0474 - EVB0475 - EVB0476 - EVB0477 - EVB0478 - EVB0479 - EVB0032 - EVB0033 - EVB0041 - EVB0042 - EVB0053 - EVB0061 - EVB0062 - EVB0063 - EVB0065 - EVB0071 - EVB0099 - EVB0106 - EVB0107 - EVB0110 - EVB0112 - EVB0113 - EVB0114 - EVB0120 - EVB0121 - EVB0125 - EVB0126 - EVB0136 - EVB0137 - EVB0140 - EVB0163 - EVB0170 - EVB0215 - EVB0217 - EVB0218 - EVB0219 - EVB0222 - EVB0224 - EVB0231 - EVB0232 - EVB0233 - EVB0235 - EVB0236 - EVB0237 - EVB0238 - EVB0243 - EVB0244 - EVB0245 - EVB0246 - EVB0248 - EVB0252 - EVB0254 - EVB0255 - EVB0258 - EVB0259 - EVB0262 - EVB0265 - EVB0271 - EVB0272 - EVB0273 - EVB0352 - EVB0353 - EVB0354 - EVB0355 - EVB0356 - EVB0362 - EVB0364 - EVB0365 - EVB0367 - EVB0368 - EVB0369 - EVB0370 - EVB0371 - EVB0378 - EVB0381 - EVB0600 - EVB0610 - EVB0615 - EVB0621 - EVB0625 - EVB0903 - EVB0530 - EVB0607 - EVB0211 - EVB0212 - EVB0060 - PICM0001 - PICC0001 - PICA0001 - PICA0002 - PICA0003 errorDescription: type: string description: > The error description that corresponds to error code when there is any error occurred while retrieving the transaction. * `EVB0401` - The value is not present in the predefined list for custom field named field name * `EVB0404` - The value has non numeric characters for custom field named: [field] * `EVB0430` - The Amount must be greater than or equal to the Cumulative Limit * `EVB0431` - The Amount must be less than the max amount range * `EVB0432` - The Amount Range Control was missing from the request * `EVB0435` - There was a problem retrieving the RCN Data with rcnId : [rcnID] * `EVB0436` - There was a problem assigning rules to your VCN Request * `EVB0437` - Invalid date {date given}.[valid date format YYYY-MM-DD] * `EVB0438` - From date should be before to date. * `EVB0406` - The Validity Control was missing from the request * `EVB0440` - There was a problem retrieving the RCN Data with rcnId: * `EVB0441` - An invalid velocity control field exists in the request. field name: * `EVB0442` - There was a problem getting the Card Image Data * `EVB0443` - There was a problem retrieving the RCN Data with rcnId : * `EVB0427` - There was a problem getting the DataSources for the given issuer * `EVB0445` - There was a problem getting the issuer id for the company id provided. * `EVB0446` - There was a problem getting RCN details. * `EVB0447` - There was a problem getting the custom data fields for the given request id * `EVB0448` - There was a problem getting the supplier email address by a supplier id * `EVB0449` - There was a problem getting the suppliers for the company ID provided * `EVB0450` - The Merchant Amount Control was missing from the request * `EVB0452` - Negate is the only supported attribute; Merchant and Acquirer details should be specified in Supplier Setup * `EVB0453` - The purchase request rules must have unique rule names * `EVB0454` - Invalid or inactive supplier. * `EVB0455` - An invalid travel control field exists in the request. field name: * `EVB0456` - An invalid time of day control field exists in the request. field name: * `EVB0457` - An invalid transaction limit control field exists in the request. field name: * `EVB0426` - An invalid validity control field exists in the request. field name: * `EVB0459` - The specified supplier has not been configured to use the Merchant ID control * `EVB0460` - Cannot have multiple velocity controls in the request with the same period. * `EVB0461` - A request submitter is not valid user * `EVB0462` - There was not a Purchase Template with the given Id, Id: * `EVB0444` - The request's Purchase Template is not associated with the active auto approve purchase group * `EVB0465` - There was a problem getting the Travel Agency Detail for the request * `EVB0466` - There was a problem getting the Tolerances for the given corpId * `EVB0468` - There was a problem getting the Air Detail for the request * `EVB0469` - There was a problem getting the Vehicle Rental Detail for the request * `EVB0470` - There was a problem getting the Template CDF to get the order * `EVB0471` - There was a problem getting the supplier by a supplier name * `EVB0472` - There was a problem getting the companies for the given issuer id and corp number * `EVB0473` - There was a problem getting the VCN Request * `EVB0474` - There was a problem getting the Rail Detail for the request * `EVB0475` - There was a problem getting the CDF to get the order * `EVB0476` - There was a problem getting the real cards for the company entered * `EVB0477` - There was a problem getting the Lodging Summary for the request * `EVB0478` - There was a problem in deleting a vcn. * `EVB0479` - The maximum number of records has been exceeded. * `EVB0032` - fundingSourceId value must be a numeric * `EVB0033` - FundingSourceId is mandatory * `EVB0041` - FundingSourceName size must be between 1 and 100 characters * `EVB0042` - fundingSourceName is mandatory * `EVB0053` - paymentBeneficiaryEmails must be alphanumeric and have value with proper email format: '.' and '@' * `EVB0061` - expiryDate length exceeds max length allowed of: 6 characters * `EVB0062` - TimeZone is mandatory if any of the following controls are set to true: Validity Period, Aging Velocity (MasterCard only), Curfew Control, Time of Day Control * `EVB0063` - timeZone field has an invalid UTC offset time zone format * `EVB0065` - currencyCode is mandatory * `EVB0071` - templateId cannot be null * `EVB0099` - currencyCode length allowed is: 3 digits * `EVB0106` - minAmount is mandatory if enableAmountRangeControl is true * `EVB0107` - maxAmount is mandatory if enableAmountRangeControl is true * `EVB0110` - startTime value must have valid format: HH:MM - H (0,1,2) | H (0-9) : M (0-5) | M (0-9) * `EVB0112` - endTime value must have valid format: HH:MM - H (0,1,2) | H (0-9) : M (0-5) | M (0-9) * `EVB0113` - startTime is mandatory if CurfewControl is true * `EVB0114` - endTime is mandatory if CurfewControl is true * `EVB0120` - validityEndDate value must have valid format: YYYY-MM-DD * `EVB0121` - validityStartDate value must have valid format: YYYY-MM-DD * `EVB0125` - validityStartDate is mandatory if ValidityPeriodControl is true * `EVB0126` - validityEndDate is mandatory if ValidityPeriodControl is true * `EVB0136` - currencyType is mandatory * `EVB0137` - spendVelocityControl-cumulativeSpendLimit is mandatory * `EVB0140` - periodType length exceeds max length allowed of: 1 character * `EVB0163` - authorizationHoldDays is mandatory if agingVelocityControl is true * `EVB0170` - amountLimit is mandatory if TransactionLimitControl is true * `EVB0215` - Validity Period Control must be set to true and validityStartDate and validityEndDate are mandatory if periodType = C * `EVB0217` - validityStartDate cannot be a past date * `EVB0218` - validityEndDate cannot be a past date * `EVB0219` - expiryDate month and year cannot be a past or current date * `EVB0222` - messageId cannot be null * `EVB0224` - messageId size must be between 28 and 36 characters * `EVB0231` - maxAuth is mandatory if enableSpendVelocityControl is set to True * `EVB0232` - weekdayEffective is mandatory if Time Of Day Control is true * `EVB0233` - endTime is mandatory if Time Of Day Control is true * `EVB0235` - startTime value cannot exceed the requested endTime value * `EVB0236` - Invalid contryCode, countryCode doesn't exist * `EVB0237` - The date specified in validityStartDate does not exist * `EVB0238` - The date specified in validityEndDate does not exist * `EVB0243` - Program Id is not present * `EVB0244` - TemplateId Should be a Valid Long Value * `EVB0245` - currencyCode value must be numeric [0-9] * `EVB0246` - paymentBeneficiaryId is mandatory * `EVB0248` - paymentBeneficiaryId Should be a Valid Long Value * `EVB0252` - messageId should be alphanumeric without special characters * `EVB0254` - mccGrouping should not contain multiple values * `EVB0255` - customReference size should be between 1 and 29 * `EVB0258` - customReferenceLabel should be between 1 and 80 characters * `EVB0259` - expiryDate must have format: MMYYYY * `EVB0262` - weekdaysEffective is mandatory if enableCurfewControl is true * `EVB0265` - mccGrouping cannot be null or empty * `EVB0271` - ExpiryDate is mandatory * `EVB0272` - Both Aging and Spend Velocity Control cannot be enabled * `EVB0273` - Either Aging or Spend Velocity Control should be enabled * `EVB0352` - FundingSourceId is Invalid. FundingSourceId value should be alphanumeric and size must be between 1 and 19 digits * `EVB0353` - customReferenceValue should be between 1 and 80 characters * `EVB0354` - AmountRangeControl-minAmount length exceed max length allowed is: 14 characters * `EVB0355` - AmountRangeControl-maxAmount length exceed max length allowed is: 14 characters * `EVB0356` - minAmount & maxAmount values must be a numeric positive value with a maximum of 2 decimals digits * `EVB0362` - Invalid maxAuth format. maxAuth value cannot exceed 8 digits * `EVB0364` - transactionLimitControl-amount value must be a numeric positive value with a maximum of 2 decimals digits * `EVB0365` - periodType is mandatory if enableSpendVelocityControl is true * `EVB0367` - startTime is mandatory if Time Of Day Control is true * `EVB0368` - weekdayEffective must have value which matches regex: SUN|MON|TUE|WED|THU|FRI|SAT * `EVB0369` - cumulativeSpendLimit is mandatory if Aging Velocity Control is set to true * `EVB0370` - countryCodes is required if Geography Control is set to true * `EVB0371` - allowed field is required if Geography Control is set to true * `EVB0378` - allowed field is required if Merchant ID Control is set to true * `EVB0381` - AmountRangeControl-minAmount is greater than maxAmount * `EVB0600` - validityStartDate should be before validityEndDate * `EVB0610` - Invalid periodType value. periodType can contain a value of either D, M, W, Q, Y, or C * `EVB0615` - No time zone found for UTC value provided in timeZone field * `EVB0621` - authorizationHoldDays must be positive long value with a maximum of 4 digits * `EVB0625` - cumulativeSpendLimit max field length is 14 digits with 12 digits to the left of the decimal and 2 digits to the right of the decimal * `EVB0903` - Atleast one Spend velocity control is required, When enableSpendVelocityControl is true * `EVB0530` - Sequence number should contain only numbers. * `EVB0607` - At least one spend control is mandatory * `EVB0211` - validityStartDate invalid format. MM value must be less than or equal to 12 and DD value must be less than or equal to 31 * `EVB0212` - validityEndDate invalid format. MM value must be less than or equal to 12 and DD value must be less than or equal to 31 * `EVB0060` - We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments * `PICM0001` - We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments * `PICC0001` - We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments * `PICA0001` - We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments * `PICA0002` - We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments * `PICA0003` - We have encountered an error and couldn't receive your request. Please try again, or contact Citi support if you have any further questions or comments CustomReference: type: object properties: customReferenceValue: type: string description: >- Specifies the label of a custom reference field. Mastercard: All field labels included in the template used for this virtual card account request should be included. customReferenceLabel: type: string description: >- Specifies the value of a custom reference field. Mastercard: If the template used for this VCA request identifies a given custom reference field as required, then the value provided in this field cannot be blank. TimeOfDay: type: object properties: startTime: type: string description: >- Specifies the start time from which the virtual card account can be used on the particular day specified in weekDaysEffective. Format - 24-hour format.
Mastercard - Optional
Visa - Optional. The minutes digit must be populated with zero only. endTime: type: string description: >- Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective. Format - 24-hour format.
Mastercard - Optional
Visa - Optional. The minutes digit must be populated with zero only. weekdayEffective: type: string description: > Specifies the day applicable to the start and end times defined.
Mastercard - Optional
Visa - Optional

Possible Values:

MON
TUE
WED
THU
FRI
SAT
SUN MerchantIdResponse: type: object properties: allowed: type: boolean description: >- Indicate whether the values in merchantId and acquirerId are allowed or disallowed.
True = values provided in merchantId and acquirerId are allowed
False = values provided in merchantId and acquirerId are not allowed
Mastercard - Conditionally required if merchant ID control is enabled
Visa - Conditionally required if merchant ID control is enabled cardAcceptorId: type: string maxLength: 15 description: >- Specifies the Card Acceptor ID that should be allowed / disallowed when transacting with the virtual card.
Mastercard - Not applicable
Visa - Conditionally required if merchant ID control is enabled merchantIds: type: array items: $ref: '#/components/schemas/MerchantId' MerchantId: type: object properties: merchantId: type: string description: >- Specifies the Merchant ID that should be allowed / disallowed when transacting with the virtual card. Must always be provided in combination with a Acquirer ID. acquirerId: type: string maxLength: 15 description: >- Specifies the Acquirer ID that should be allowed / disallowed when transacting with the virtual card.
Mastercard - Not applicable
Visa - Optional MerchantIdRequest: type: object properties: allowed: type: boolean description: >- Indicate whether the values in merchantId and acquirerId are allowed or disallowed.
True = values provided in merchantId and acquirerId are allowed
False = values provided in merchantId and acquirerId are not allowed.
Mastercard - Conditionally required if merchant ID control is enabled
Visa - Conditionally required if merchant ID control is enabled cardAcceptorId: type: string description: >- Specifies the Card Acceptor ID that should be allowed / disallowed when transacting with the virtual card. SpendVelocityResponse: type: object properties: maxAuth: type: number description: >- 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) cumulativeSpendLimit: type: number description: >- Limits the overall amount that can be spent on the virtual card account.
Mastercard - Allows a maximum of 14 digits (12 digits to the left of the decimal and 2 digits to the right of the decimal)
Visa - Allows a maximum of 12 digits (10 digits to the left of the decimal and 2 digits to the right of the decimal) periodType: type: string description: > Period for which the control values are valid before they reset.

Mastercard:
* `D` - Daily. The balances of control parameters enabled for a VCA are reset with their original values every day at 00:00:00. * `M` - Monthly. The balances of control parameters enabled for a VCA are reset with their original values at the start of every month. * `W` - Weekly. The balances of control parameters enabled for a VCA are reset with their original values every Monday at 00:00:00. * `Q` - Quarterly. The balances of control parameters enabled for a VCA are reset with their original values on the first day of every quarter at 00:00:00. * `Y` - Annually. The balances of control parameters enabled for a VCA are reset with their original values every year on January 1st at 00:00:00. * `C` - Continuous. The balances of control parameters enabled for a VCA are retained continuously for the validity period defined.

Visa:
* `1` - Recurring. Balances reset on a specified recurring day each month. If you select this periodType, you must also populate the resetDay field. * `2` - Monthly. Balances reset with their original values on a specified recurring day every month. * `3` - Date Range. Balances are retained continuously for the validity period defined. If you select this periodType, then validityStartDate and validityEndDate fields are required. availableBalance: type: number description: The remaining balance available to spend on the virtual card. periodEndDate: type: string description: End date of the current period based on the periodType selected. resetDay: type: number description: >- Select a number between 1-28 to identify the day each month when the control parameter balances should reset to their original value. This field is only applicable if periodType was defined as "1". CurfewTime: type: object properties: startTime: type: string description: >- Specifies the start time until which the virtual card account can be used on the particular day specified in weekDaysEffective. Format - 24-hour format
Mastercard - Optional
Visa - Not applicable endTime: type: string description: >- Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective. Format - 24-hour format
Mastercard - Optional
Visa - Not applicable weekdaysEffective: type: array description: > Specifies the day applied to start and end times.
Mastercard - Optional
Visa - Not applicable

Possible Values:

MON
TUE
WED
THU
FRI
SAT
SUN items: type: string WebhookRequest: type: object properties: eventType: type: string enum: - VCA CREATE description: Client Requested API Name. eventStatus: type: string enum: - CREATED - PENDING - FAILED description: >- CREATED - Virtual card is created and the details are available.
PENDING - Required Additional document to create the virtual card.
FAILED - Unable to process your request. Please try again, or contact Citi support if you have any further questions or comments. alertMessage: type: string description: >- CREATED - VCA Issuance for {Third Party Entity/Individual name} is completed successfully.
FAILED - We are unable to issue a VCA for {Third Party Entity/Individual name} at this time. Please try your request again. If this issue persists, please contact Citi support for assistance.
PENDING - VCA Issuance for {Third Party Entity/Individual name} is pending review. Citi Cards Clients Services will get in touch with you to process further. payload: $ref: '#/components/schemas/VcaCreateResponse' VcaCreateResponse: type: object properties: vcaId: type: string description: >- A reference number that uniquely identifies the virtual card account. cardImage: type: string description: A visual representation of the virtual card account front and back. currencyCode: type: string description: >- 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. timeZone: type: string description: >- Defines the time zone applicable for any date or time parameters within controls set for a VCA. virtualCardAccountNumber: type: string description: The virtual card account number to use for transactions. expiryDate: type: string description: >- Expiry Date of the virtual card account. Represented in UTC time zone. Format - MMYYYY securityCode: type: string description: >- The security code (i.e. cvv) corresponding to the virtual card account. programId: type: string description: Unique ID of the company record defined in the virtual cards system. messageId: type: string description: >- 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. mccGrouping: type: array description: Limits authorizations to defined Merchant Category Codes. items: type: string currencyType: type: string description: >- 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 - The only valid value is "M". paymentBeneficiaryId: type: number description: >- Uniquely identifies the payment beneficiary for which the virtual card is created. paymentBeneficiaryEmails: type: array description: >- Lists of up to 5 email addresses separated by semicolon 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 supplier
2. Allow VCN requestor to manually enter a new email address when requesting a VCN items: type: string customReference: type: array items: $ref: '#/components/schemas/CustomReference' templateId: type: number description: >- 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. cumulativeSpendLimit: type: number description: >- Limits the overall amount that can be spent on the virtual card account.
Mastercard - Allows a maximum of 14 digits (12 digits to the left of the decimal and 2 digits to the right of the decimal)
Visa - Allows a maximum of 12 digits (10 digits to the left of the decimal and 2 digits to the right of the decimal) enableSpendVelocityControl: type: boolean description: >- Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period.
Mastercard: The control is mandatory unless Aging Velocity Control is used. This control cannot be used in combination with the Aging Velocity Control.
Visa: Spend Velocity Control is mandatory. spendVelocity: type: array items: $ref: '#/components/schemas/SpendVelocityResponse' enableValidityPeriodControl: type: boolean description: >- Limits authorization activity to a specific time period.
Mastercard - Optional
Visa - Required validityStartDate: type: string description: >- Identifies the date from which the virtual card account can be used for transactions. Format - YYYY-MM-DD
Mastercard - Optional
Visa - Optional. If not provided, then will be defaulted to today's date validityEndDate: type: string description: >- Identifies the date until which the virtual card account can be used for transactions. Format - YYYY-MM-DD
Mastercard - Optional
Visa - Required enableAmountRangeControl: type: boolean description: >- 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. This control cannot be used in combination with Transaction Limit Control.
Mastercard - Optional
Visa - Optional maxAmount: type: number description: >- Identifies the maximum allowed transaction amount.

Mastercard - Optional. Max character length - 14 digits (12 digits to the left of the decimal and 2 digits to the right of the decimal)

Visa - Optional. Max character length - 12 digits (10 digits to the left of the decimal and 2 digits to the right of the decimal) minAmount: type: number description: >- Identifies the minimum allowed transaction amount.

Mastercard - Max character length - 14 digits (12 digits to the left of the decimal and 2 digits to the right of the decimal)

Visa - Optional. Max character length - 12 digits (10 digits to the left of the decimal and 2 digits to the right of the decimal) enableTransactionLimitControl: type: boolean description: >- Limits individual transactions to a maximum amount. This control cannot be used in combination with Amount Range Control.
Mastercard - Optional
Visa - Optional amountLimit: type: number description: >- Identifies the maximum allowed transaction amount.

Mastercard - Optional. Max character length - 17

Visa - Optional. Only integer value allowed. Max character length - 7 enableCurfewControl: type: boolean description: >- Limits authorization activity to a single time period for each day selected. This control cannot be used in combination with Time Of Day Control.
Mastercard - Optional
Visa - Not applicable curfewTime: $ref: '#/components/schemas/CurfewTime' enableTimeOfDayControl: type: boolean description: >- Limits authorization request to defined time periods each day.
Mastercard - Optional
Visa - Optional timeOfDay: type: array items: $ref: '#/components/schemas/TimeOfDay' enableAgingVelocityControl: type: boolean description: >- 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.
Mastercard - Optional
Visa - Not applicable authorizationHoldDays: type: number description: >- Identifies the number of days after which an authorization gets aged off if no matching clearing record was received.
Mastercard - Optional
Visa - Not applicable enableGeographyControl: type: boolean description: >- 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.
Mastercard - Optional
Visa - Optional countryCodes: type: array description: >- Comma delimited list defining the merchant country in which the VCA can or cannot be used.
Mastercard - Optional
Visa - Optional items: type: string allowed: type: boolean description: >- 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
Mastercard - Optional
Visa - Optional enableMerchantIdControl: type: boolean description: >- Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa).
Mastercard - Optional
Visa - Optional merchantInfo: type: array items: $ref: '#/components/schemas/MerchantIdResponse' warning: type: array description: >- Warning information regarding a non-fatal response condition that may be taken into account, but can be ignored. example: - >- The VCA Details returned are for a pre-generated VCA from Citi, as the backend VCA platform is currently unavailable items: type: string standInVca: type: boolean description: >- 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 "false" is returned or if the field is not returned then the VCA returned is from the backend VCA platform. NotificationResponseMessage: type: object properties: httpResponse: type: integer format: int64 description: Notification response status code. responseMessage: type: string description: Notification response message. paths: /webhooks/v2/vca/create: post: tags: - vca-create-notification-service summary: Create VCA Notification description: >- Create a virtual card and set its associated spending controls, custom reference data and payment beneficiaries. It allows you to place a VCA creation request for secure purchasing, with increased Transaction-Level Controls, limit card number use by MCC, amounts, dates and even specific suppliers. operationId: create security: - OAuth2: - write - ApiKeyAuth: [] - BasicAuth: [] parameters: - name: messageId in: header description: Tracking id which was sent by client on VCA create request. required: true schema: type: string - name: client-id in: header description: Unique identifier of the client application making the request. required: true schema: type: string - name: api-gateway-id in: header description: >- Unique identifier assigned by the API transaction for the incoming request. This is the x-global-transaction-id value returned in the VCA Create for PI API instant acknowledgementresponse header. required: true schema: type: string - name: correlation_id in: header description: >- Unique identifier used to correlate and trace the request end-to-end across services. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequest' examples: Mastercard: summary: VCA Create Notification - Mastercard Sample Request value: eventType: VCA CREATE eventStatus: CREATED alertMessage: VCA Issuance for ABC Corporation is completed successfully. payload: vcaId: '7890123456789' cardImage: base64encodedImageString== currencyCode: '008' timeZone: UTC+10:00 virtualCardAccountNumber: '5412345678901234' expiryDate: '112026' securityCode: '123' programId: '431341' messageId: 908c090d1995490eb3b431a1f37356df mccGrouping: - All MCCs currencyType: B paymentBeneficiaryId: 19180 paymentBeneficiaryEmails: - abcd.emp@citi.com customReference: - customReferenceLabel: Invoice No. customReferenceValue: '1234' - customReferenceLabel: Cost Center customReferenceValue: NAM Hub - customReferenceLabel: Department customReferenceValue: Marketing templateId: 23358 cumulativeSpendLimit: 2000 enableSpendVelocityControl: false spendVelocity: - maxAuth: 5 cumulativeSpendLimit: 2000 periodType: D availableBalance: 2000 periodEndDate: '2026-06-30' enableValidityPeriodControl: true validityStartDate: '2022-06-16' validityEndDate: '2022-06-17' enableAmountRangeControl: true maxAmount: 2000.01 minAmount: 1000.01 enableTransactionLimitControl: false enableCurfewControl: true curfewTime: startTime: '12:30' endTime: '13:30' weekdaysEffective: - MON enableTimeOfDayControl: false enableAgingVelocityControl: true authorizationHoldDays: 5 enableGeographyControl: false enableMerchantIdControl: false standInVca: false Visa: summary: VCA Create Notification - Visa Sample Request value: eventType: VCA CREATE eventStatus: CREATED alertMessage: VCA Issuance for XYZ Corporation is completed successfully. payload: vcaId: '5678901234567' currencyCode: '752' timeZone: UTC+05:30 virtualCardAccountNumber: '4012345678901234' expiryDate: '122025' securityCode: '456' programId: '918' messageId: KS08736V2Create20260226131411 mccRange: - 4812-4814 - 4816-4817 - 5044-5045 mccgAllowed: true currencyType: M customReference: - customReferenceLabel: Invoice No. customReferenceValue: '1234' - customReferenceLabel: Cost Center customReferenceValue: NAM Hub - customReferenceLabel: Department customReferenceValue: Marketing enableSpendVelocityControl: true spendVelocity: - maxAuth: 1 cumulativeSpendLimit: 300000 periodType: '3' resetDay: 15 availableBalance: 300000 periodEndDate: '2026-12-25' enableValidityPeriodControl: true validityStartDate: '2026-12-10' validityEndDate: '2026-12-25' enableAmountRangeControl: true maxAmount: 10000.1 minAmount: 1000.1 enableTransactionLimitControl: false enableCurfewControl: false enableTimeOfDayControl: true timeOfDay: - startTime: '10:00' endTime: '11:00' weekdayEffective: MON enableGeographyControl: true countryCodes: - USA - ZMB - ZWE - SWZ allowed: false enableMerchantIdControl: true merchantInfo: - allowed: true merchantIds: - cardAcceptorId: '1234560' acquirerId: '132412' - cardAcceptorId: '1234561' acquirerId: '1324121' standInVca: false responses: '201': description: Create Virtual Card Notification response content: application/json: schema: $ref: '#/components/schemas/NotificationResponseMessage' example: httpResponse: 201 responseMessage: Notification received successfully. '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/NotificationResponseMessage' example: httpResponse: 500 responseMessage: >- Internal Server Error. Please try again or contact Citi support.