swagger: '2.0' info: version: 1.0.0 title: Virtual Cards Life Cycle Management description: Create, modify or cancel a Virtual Card Account. x-ibm-name: vca-life-cycle-management servers: - url: https://tts.apib2b.citi.com/tts/cards/vca/v1/ description: production gateway URL - url: https://tts.sandbox.apib2b.citi.com/tts/cards/vca/v1/ description: sandbox URL security: - clientCredentials: [] schemes: - https paths: /create: post: summary: Create Virtual Card Accounts operationId: create consumes: - application/json produces: - application/json description: >- 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. parameters: - name: client_id in: query required: true description: >- This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for oauth token generation type: string - name: Content-Type in: header description: Supports \"application/xml\" and \"application/json\". required: true schema: null type: string - name: Authorization in: header description: The OAuth Token prefixed with "Bearer" and space in between. required: true type: string - name: country in: header required: true type: string description: country of the Client - name: region in: header required: true type: string description: region of the client(Apac/EMEA/NAM) - name: request-body in: body required: true schema: $ref: '#/definitions/CreateVirtualCardRequest' responses: '200': description: Create Virtual Card response schema: $ref: '#/definitions/CreateVirtualCardResponse' '400': description: Invalid Modify Virtual Card request schema: $ref: '#/definitions/CreateVirtualCardFailureResponse' '401': description: Unauthorized Modify Virtual Card request schema: $ref: '#/definitions/CreateVirtualCardFailureResponse' '405': description: Method Not Allowed schema: $ref: '#/definitions/CreateVirtualCardFailureResponse' '500': description: Internal Server Error schema: $ref: '#/definitions/CreateVirtualCardFailureResponse' /modify: post: summary: Update Virtual Card Accounts operationId: modify consumes: - application/json produces: - application/json description: >- Modify a virtual card and set its associated spending controls, custom reference data and payment beneficiaries. parameters: - name: client_id in: query required: true description: >- This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for oauth token generation type: string - name: Content-Type in: header description: Supports \"application/xml\" and \"application/json\". required: true type: string - name: Authorization in: header description: The OAuth Token prefixed with "Bearer" and space in between. required: true type: string - name: country in: header required: true type: string description: country of the Client - name: region in: header required: true type: string description: region of the client(Apac/EMEA/NAM) - name: request-body in: body required: true schema: $ref: '#/definitions/ModifyVirtualCardRequest' responses: '200': description: Modify Virtual Card response schema: $ref: '#/definitions/ModifyVirtualCardResponse' '400': description: Invalid Modify Virtual Card request schema: $ref: '#/definitions/ModifyVirtualCardFailureResponse' '401': description: Unauthorized Modify Virtual Card request schema: $ref: '#/definitions/ModifyVirtualCardFailureResponse' '405': description: Method Not Allowed schema: $ref: '#/definitions/ModifyVirtualCardFailureResponse' '500': description: Internal Server Error schema: $ref: '#/definitions/ModifyVirtualCardFailureResponse' /cancel: post: summary: Cancel Virtual Card Accounts operationId: cancel consumes: - application/json produces: - application/json description: Cancel a virtual card when it is no longer needed. parameters: - name: client_id in: query required: true description: >- This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for oauth token generation type: string - name: Content-Type in: header description: Supports \"application/xml\" and \"application/json\". required: true type: string - name: Authorization in: header description: The OAuth Token prefixed with "Bearer" and space in between. required: true type: string - name: country in: header required: true type: string description: country of the Client - name: region in: header required: true type: string description: region of the client(Apac/EMEA/NAM) - name: request-body in: body required: true schema: $ref: '#/definitions/CancelVirtualCardRequest' responses: '200': description: Cancel Virtual Card response schema: $ref: '#/definitions/CancelVirtualCardResponse' '400': description: Invalid Cancel Virtual Card request schema: $ref: '#/definitions/CancelVirtualCardFailureResponse' '401': description: Unauthorized Virtual Card request schema: $ref: '#/definitions/CancelVirtualCardFailureResponse' '405': description: Method Not Allowed schema: $ref: '#/definitions/CancelVirtualCardFailureResponse' '500': description: Internal Server Error schema: $ref: '#/definitions/CancelVirtualCardFailureResponse' definitions: CancelVirtualCardRequest: type: object properties: vcaIds: type: array description: Unique Identifier for each Virtual card request. items: type: number virtualCardAccountNumber: type: string description: >- The virtual card account number for which the modifications are requested. 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. ErrorMessage: type: object properties: errorCode: type: string enum: - EVB0014 - EVB0010 - EVB0017 - EVB0018 - EVB0020 - EVB0030 - EVB0033 - EVB0042 - EVB0044 - EVB0037 - EVB0032 - EVB0040 - EVB0045 - EVB0046 - EVB0050 - EVB0053 - EVB0060 - EVB0061 - EVB0062 - EVB0063 - EVB0065 - EVB0066 - EVB0070 - EVB0071 - EVB0099 - EVB0104 - EVB0106 - EVB0107 - EVB0110 - EVB0113 - EVB0114 - EVB0112 - EVB0120 - EVB0121 - EVB0124 - EVB0125 - EVB0126 - EVB0133 - EVB0136 - EVB0137 - EVB0138 - EVB0140 - EVB0141 - EVB0143 - EVB0151 - EVB0163 - EVB0170 - EVB0201 - EVB0202 - EVB0213 - EVB0214 - EVB0215 - EVB0216 - EVB0222 - EVB0224 - EVB0241 - EVB0243 - EVB0245 - EVB0251 - EVB0252 - EVB0244 - EVB0246 - EVB0247 - EVB0248 - EVB0250 - EVB0253 - EVB0254 - EVB0255 - EVB0256 - EVB0257 - EVB0258 - EVB0025 - EVB0260 - EVB0261 - EVB0262 - EVB0264 - EVB0265 - EVB0267 - EVB0270 - EVB0271 - EVB0272 - EVB0273 - EVB0290 - EVB0350 - EVB0351 - EVB0352 - EVB0353 - EVB0354 - EVB0355 - EVB0356 - EVB0357 - EVB0358 - EVB0359 - EVB0360 - EVB0361 - EVB0362 - EVB0363 - EVB0364 - EVB0365 - EVB0366 - EVB0367 - EVB0368 - EVB0369 - EVB0370 - EVB0371 - EVB0372 - EVB0373 - EVB0374 - EVB0375 - EVB0378 - EVB0381 - EVB0401 - EVB0404 - EVB0430 - EVB0431 - EVB0432 - EVB0435 - EVB0436 - EVB0437 - EVB0438 - EVB0406 - EVB0440 - EVB0441 - EVB0530 - EVB0607 - EVB0211 - EVB0212 - EVB0219 - EVB0230 - EVB0231 - EVB0281 - EVB1185 - EVB1300 - EVB1301 - EVB1302 - EVB1303 - EVB1304 - EVB1305 - EVB1306 - EVB1307 - EVB1308 - EVB1309 - ERS0087 - GRC0001 - GRC0002 - GRC0003 - GRC0004 - GRC0005 - GRC0006 - GRC0007 - GRC0009 - GRC0011 - GRC0012 - GRC0014 errorDescription: type: string description: > The error description that corresponds to error code when there is any error occurred while retrieving the trsansaction. * `EVB0010` - vcaId size must be between 1 and 19 digits * `EVB0014` - vcaId value must be a numeric * `EVB0017` - vcaID is empty or null * `EVB0018` - No previously approved vcaID is present * `EVB0020` - vcaID and programId combination is not present * `EVB0030` - FundingSourceId cannot be modified * `EVB0033` - FundingSourceId cannot be null * `EVB0042` - FundingSourceName cannot be null * `EVB0044` - Funding source Id|Funding source Name|Template Id is not required for cancel request * `EVB0037` - fundingSourceId is mandatory * `EVB0032` - fundingSourceId value must be a numeric * `EVB0040` - fundingSourceName is mandatory * `EVB0045` - Funding source Id|Funding source Name|Template Id|PaymentBeneficiaryId cannot be modified * `EVB0046` - FundingSourceName cannot be modified * `EVB0050` - paymentBeneficiaryId cannot be modified * `EVB0053` - paymentBeneficiaryEmails must be alphanumeric and have value with proper email format: \".\" and \"@\" * `EVB0060` - expiryDate is mandatory * `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 cannot be null * `EVB0066` - ClientId and programId combination is not valid * `EVB0070` - templateId cannot be modified * `EVB0071` - templateId cannot be null * `EVB0099` - currencyCode length allowed is: 3 digits * `EVB0104` - currencyType must have value which matches regex: M|B|m|b * `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-9) | M (0-9) * `EVB0113` - startTime is mandatory if CurfewControl is true * `EVB0114` - endTime is mandatory if CurfewControl is true * `EVB0112` - endTime value must have valid format: HH:MM - H (0,1,2) | H (0-9) : M (0-9) | M (0-9) * `EVB0120` - validityEndDate value must have valid format: YYYY-MM-DD * `EVB0121` - validityStartDate value must have valid format: YYYY-MM-DD * `EVB0124` - timeZone is mandatory if Validity Period control is set to true * `EVB0125` - validityStartDate is mandatory if ValidityPeriodControl is true * `EVB0126` - validityEndDate is mandatory if ValidityPeriodControl is true * `EVB0133` - VelocityControlType-periodType is mandatory. * `EVB0136` - currencyType is mandatory * `EVB0137` - spendVelocityControl-cumulativeSpendLimit is mandatory * `EVB0138` - spendVelocityControl-maxAuth is mandatory * `EVB0140` - periodType length exceeds max length allowed of: 1 character * `EVB0141` - periodType is mandatory if enablespendvelocity is true * `EVB0143` - periodType is mandatory * `EVB0151` - Cannot add any new controls to a previosuly created VCA * `EVB0163` - authorizationHoldDays is mandatory if agingVelocityControl is true * `EVB0170` - amountLimit is mandatory if TransactionLimitControl is true * `EVB0201` - We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments. * `EVB0202` - We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments * `EVB0213` - virtualCardAccountNumber is Invalid * `EVB0214` - Validity Period Control must be set to true and validityStartDate and validityEndDate are mandatory if periodType = 3 * `EVB0215` - Validity Period Control must be set to true and validityStartDate and validityEndDate are mandatory if periodType = C * `EVB0216` - VcaId Should be a Valid Long Value * `EVB0222` - messageId cannot be null * `EVB0224` - messageId size must be between 28 and 36 characters * `EVB0241` - Transaction Not Found for the respective client id and message id on grace. * `EVB0243` - Program Id is not present * `EVB0245` - currencyCode value must be numeric [0-9] * `EVB0251` - ExpiryDate is not required * `EVB0252` - messageId should be alphanumeric without special characters * `EVB0254` - FundingSourceName size must be between 1 and 100 characters * `EVB0244` - TemplateId Should be a Valid Long Value * `EVB0246` - paymentBeneficiaryId cannot be null * `EVB0247` - paymentBeneficiaryId size must be between 1 and 19 digits * `EVB0248` - paymentBeneficiaryId Should be a Valid Long Value * `EVB0250` - FundingSourceName is not required * `EVB0253` - mccGrouping should not contain multiple values * `EVB0255` - customReference size should be between 1 and 29 * `EVB0256` - customReferenceValue should be between 1 and 100 characters * `EVB0257` - vcaId should not be null or empty * `EVB0258` - customReferenceLabel should be between 1 and 50 characters * `EVB00259`- expiryDate must have format: MMYYYY * `EVB0260` - cardAcceptorId is mandatory if Merchant Control ID is true * `EVB0261` - cardAcceptorId length exceeds max length allowed of 15 character * `EVB0262` - weekdaysEffective is mandatory if enableCurfewControl is true * `EVB0264` - spendVelocityControl is Mandatory * `EVB0265` - mccGrouping cannot be null or empty * `EVB0267` - ProgramId should be alphanumeric without special characters * `EVB0270` - Not allowed to modify when control indicator is disabled * `EVB0271` - ExpiryDate field cannot be NULL * `EVB0272` - Both Aging and Spend Velocity Control cannot be enabled * `EVB0273` - Either Aging or Spend Velocity Control should be enabled * `EVB0290` - Bulk Cancellation is not Allowed for visa * `EVB0350` - virtualCardAccountNumber length should be 16 characters * `EVB0351` - virtualCardAccountNumber is Mandatory * `EVB0352` - FundingSourceId is Invalid. FundingSourceId value should be a valid long value and size must be between 1 and 19 digits * `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 * `EVB0357` - ProgramId must be numeric * `EVB0358` - programId value must be between 1 and 19 digits * `EVB0359` - programId value must be between 1 and 25 digits * `EVB0360` - Invalid JSON input * `EVB0361` - Invalid JSON input * `EVB0362` - Invalid maxAuth format. maxAuth value cannot exceed 8 digits * `EVB0363` - cumulativeSpendLimit max field length is 12 digits with 10 digits to the left of the decimal and 2 digits to the right of the decimal * `EVB0364` - transactionLimitControl-amount value must be a numeric positive value with a maximum of 2 decimals digits * `EVB0365` - periodType is mandatory if enableSpendVelocity is true * `EVB0366` - resetDay value must an integer between 1-28 * `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 * `EVB0372` - merchantId is mandatory if Merchant ID Control is true * `EVB0373` - merchantId length exceeds max length allowed of 15 characters * `EVB0374` - acquirerId is mandatory if Merchant ID Control is true * `EVB0375` - acquirerId length exceeds max length allowed of 15 characters * `EVB0378` - allowed field is required if Merchant ID Control is set to true * `EVB0381` - AmountRangeControl-minAmount is greater than maxAmount * `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 * `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 * `EVB0439` - An invalid geography control field exists in the request. field name: * `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: * `EVB0441` - An invalid velocity control field exists in the request. field name: * `EVB0458` - Only one Merchant Id control is allowed * `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 * `EVB0464` - There was a problem saving the custom data fields for the allocate vcn request * `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 * `EVB0470` - There was a problem getting the Template CDF to get the order * `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 * `EVB0472` - There was a problem getting the companies for the given issuer id and corp number * `EVB0471` - There was a problem getting the supplier by a supplier name * `EVB0477` - There was a problem getting the Lodging Summary for the request * `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 * `EVB0524` - Date range should be same month. * `EVB0478` - There was a problem in deleting a vcn. * `EVB0479` - The maximum number of records has been exceeded. * `EVB0480` - There was a problem TRYING TO Sync Card Currency * `EVB0481` - There was a problem saving the custom data fields for the update request * `EVB0482` - There was a problem saving the vcn request * `EVB0483` - There was a problem updating the vcn request * `EVB0484` - Invalid Expiry Date Requested * `EVB0485` - Unable to correctly analyze a purchase request which did not have required controls present: * `EVB0528` - There was a problem allocating the vcn * `EVB0486` - Purchase Request(s) could not be approved * `EVB0487` - Purchase Request(s) could not be canceled * `EVB0513` - Message ID is not unique. * `EVB0516` - Request could not be processed successfully. * `EVB0515` - Invalid Buyer * `EVB0516` - Request could not be processed successfully. * `EVB0517` - Invalid Web Service Method * `EVB0518` - Proxy number provided in the request is not active. * `EVB0519` - Invalid visa account number * `EVB0520` - Proxy number length should be between 1 and 19 * `EVB0521` - Proxy number contains invalid characters * `EVB0522` - Start Date should not be more than 10 characters * `EVB0523` - Start Date is invalid. Valid date format is YYYY-MM-DD * `EVB0525` - End Date is mandatory * `EVB0526` - End Date should not be more than 10 characters * `EVB0527` - End Date is invalid. Valid date format is YYYY-MM-DD * `EVB0528` - End Date cannot be a past date * `EVB0529` - Rule Code is not valid * `EVB516` - cumulativeSpendLimit value must be numeric * `EVB517` - cumulativeSpendLimit value must be numeric * `EVB0530` - Sequence number should contain only numbers. * `EVB0531` - OverrideCode contains invalid characters * `EVB0532` - OverrideCode should not be more than 33 characters. * `EVB0531` - OverrideValue contains invalid characters * `EVB0533` - OverrideValue should not be more than 10 characters * `EVB0559` - End Date should not be less than Start Date * `EVB0535` - Sequence number should be within 0 to 999 range. * `EVB0536` - Rule Code is mandatory. Please provide valid rule code * `EVB0537` - Rule Code cannot contain special characters. Please provide valid rule code * `EVB0538` - Override code is mandatory * `EVB0539` - Override Value is mandatory * `EVB0540` - Action is mandatory. Action code should be A/U/D. * `EVB0560` - Invalid Action. Action code should be A/U/D. * `EVB0542` - Request could not be processed successfully. Failed to generate Token. * `EVB0543` - Add payment control could not be processed successfully. * `EVB0544` - Account number should be blank. * `EVB0545` - Atlease one requisition rule is mandaotry. * `EVB0546` - Atlease one override rule is mandatory. * `EVB0547` - No Requisition card details found. * `EVB0548` - equence number is mandatory * `EVB0549` - Account Number is Mandatory * `EVB0550` - Number of cards count should be 1. * `EVB0551` - Start Date is Mandatory. * `EVB0552` - The number of accounts you have requested exceeds the maximum allowed limit * `EVB0553` - Overrides rule size exceeds maximum Limit * `EVB0554` - The pseudo account type set for the SUA proxy is not matching the pseudo account type set up for the buyer. * `EVB0555` - Currency code passed in the request is not configured as one of the allowed currency for the buyer. * `EVB0556` - The startRange and endRange overrides are mandatory for the Other MCG rule. * `EVB0557` - Rules can have a maximum of 25 override values * `EVB0558` - Atleast one RequisitionDetail is mandatory * `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 * `EVB0219` - expiryDate month and year cannot be a past or current date * `EVB0230` - Invalid contryCode format. countryCode value cannot exceed 3 characters * `EVB0231` - maxAuth is mandatory if enableSpendVelocityControl is set to True * `EVB0281` - maxAuth must be a valid long value with a maximum of 10 digits * `EVB1185` - max size supported for purchaseRequestIds is : 50 * `EVB1300` - Amount range control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1301` - Curfew control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1302` - Geography control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1303` - Merchant amount control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1304` - Merchant ID control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1305` - Time of day control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1306` - Transaction limit control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1307` - Validity period control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1308` - Aging velocity control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `EVB1309` - Velocity control is included in the request, but this control is not configured within the Virtual Card Purchase Template that is included in the request. Please configure this control in the Purchase Template * `ERS0087` - Duplicate message id provided for VCA creation. Please call getVCADetails with original create message id to get vca details. * `GRC0001` - 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 * `GRC0002` - Client ID is missing in the request header * `GRC0003` - Contry code is not available in the request * `GRC0004` - Region ID is not available in the request * `GRC0005` - 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 * `GRC0006` - 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 * `GRC0007` - Client requested MediaType is not supported. * `GRC0009` - 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 * `GRC0011` - Client ID and/or Country and/or region id is missing in Client Onboard Configuration setup. Contact Citi support. * `GRC0012` - Necessary header value is missing * `GRC0003` - Invalid JSON Input * `GRC0014` - 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 CancelVirtualCardResponse: type: object properties: 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. vcaResponse: type: array items: $ref: '#/definitions/VcaResponse' VcaResponse: type: object properties: programId: type: string description: Unique ID of the company record defined in the virtual cards system. vcaId: type: number description: A reference number that uniquely identifies the virtual card account. CancelVirtualCardFailureResponse: type: object properties: 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. vcaResponse: type: array items: $ref: '#/definitions/VcaFailureResponse' VcaFailureResponse: type: object properties: programId: type: string description: Unique ID of the company record defined in the virtual cards system. vcaId: type: number description: A reference number that uniquely identifies the virtual card account. errorMessage: type: array items: $ref: '#/definitions/ErrorMessage' 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. endTime: type: string description: >- Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective. weekdayEffective: type: string description: Specifies the day applicable to the start and end times defined. 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 cardAcceptorId: type: string description: >- Specifies the Card Acceptor ID that should be allowed / disallowed when transacting with the virtual card merchantIds: type: array items: $ref: '#/definitions/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: integer format: int64 description: >- Specifies the Acquirer ID that should be allowed / disallowed when transacting with the virtual card. Must always be provided in combination with a Merchant ID. 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 cardAcceptorId: type: string description: >- Specifies the Card Acceptor ID that should be allowed / disallowed when transacting with the virtual card 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: integer format: int64 description: >- Specifies the Acquirer ID that should be allowed / disallowed when transacting with the virtual card. Must always be provided in combination with a Merchant ID. SpendVelocityResponse: type: object properties: maxAuth: type: number format: long 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 format: bigdecimal description: Limits the overall amount spend on the virtual card account. periodType: type: string description: Period for which the control values are valid before they reset 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. SpendVelocityRequest: type: object properties: maxAuth: type: number format: long 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 format: bigdecimal description: Limits the overall amount spend on the virtual card account. periodType: type: string description: Period for which the control values are valid before they reset CurfewTime: type: object properties: startTime: type: string description: >- Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective. endTime: type: string description: >- Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective. weekdaysEffective: type: array description: Specifies the day applicable to the start and end times defined. items: type: string CreateVirtualCardRequest: type: object properties: vcaId: type: number description: 'A reference number that uniquely identifies the virtual card account. ' example: 1234, fundingSourceId: type: string description: >- Unique identifier of the funding source to which the virtual card rolls up example: 15510, fundingSourceName: type: string description: Descriptive name of the real card to which the virtual card rolls up example: APAC UAT GRACE TEST1 programId: type: string description: Unique ID of the company record defined in the virtual cards system example: 433161, 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 example: 1234567898765, mccGrouping: type: array description: Limits authorizations to defined Merchant Category Codes. items: type: string getCardImage: type: boolean description: >- * 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. currencyCode: type: string description: Currency Code in which VCA amounts are expressed currencyType: type: string description: >- 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. timeZone: type: string description: >- 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. paymentBeneficiaryId: type: number description: >- Uniquely identifies the payment beneficiary for which the virtual card is created example: 51501, paymentBeneficiaryEmails: type: array description: >- 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 items: type: string example: customer@customer_corp.com customReference: type: array items: $ref: '#/definitions/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. example: 24694, expiryDate: type: string description: 'Expiry Date of the virtual card account. ' example: '2025-03-02' cumulativeSpendLimit: type: number format: bigdecimal description: Limits the overall amount spend on the virtual card account. 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 Velcotiy Control is used. This control cannot be used in combination with the Aging Velocity Control.Visa: Spend Velocity Control is mandatory. example: true spendVelocity: type: array items: $ref: '#/definitions/SpendVelocityRequest' enableValidityPeriodControl: type: boolean description: 'Limits authorization activity to a specific time period. ' validityStartDate: type: string description: >- Identifies the date from which the virtual card account can be used for transactions. example: '2023-03-01' validityEndDate: type: string description: >- Identifies the date until which the virtual card account can be used for transactions. example: '2027-04-18' 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. maxAmount: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. minAmount: type: number format: bigdecimal description: Identifies the minimum allowed transaction amount. enableTransactionLimitControl: type: boolean description: Limits individual transactions to a maximum amount. amountLimit: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. enableCurfewControl: type: boolean description: >- Limits authorization activity to a single time period for each day selected. curfewTime: $ref: '#/definitions/CurfewTime' enableTimeOfDayControl: type: boolean description: Limits authorization request to defined time periods each day timeOfDay: type: array items: $ref: '#/definitions/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. authorizationHoldDays: type: number format: long description: >- Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. enableGeographyControl: type: boolean description: Limits authorization requests to a defined geographic location. countryCodes: type: array description: Defines the merchant country in which the VCA can be used. items: type: string allowed: type: boolean description: Indicate whether the values in countryCode are allowed or disallowed enableMerchantIdControl: type: boolean description: >- Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa). merchantId: $ref: '#/definitions/MerchantIdRequest' ModifyVirtualCardRequest: type: object properties: vcaId: type: number description: 'A reference number that uniquely identifies the virtual card account. ' fundingSourceId: type: string description: >- Unique identifier of the funding source to which the virtual card rolls up fundingSourceName: type: string description: Descriptive name of the real card to which the virtual card rolls up 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 getCardImage: type: boolean description: >- * 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. currencyCode: type: string description: Currency Code in which VCA amounts are expressed currencyType: type: string description: >- 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. timeZone: type: string description: >- 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. paymentBeneficiaryId: type: number description: >- Uniquely identifies the payment beneficiary for which the virtual card is created paymentBeneficiaryEmails: type: array description: >- 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 items: type: string customReference: type: array items: $ref: '#/definitions/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. expiryDate: type: string description: 'Expiry Date of the virtual card account. ' cumulativeSpendLimit: type: number format: bigdecimal description: Limits the overall amount spend on the virtual card account. maxAuth: type: number format: long 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) modifySpendVelocityControl: 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 Velcotiy 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: '#/definitions/SpendVelocityRequest' modifyValidityPeriodControl: type: boolean description: 'Limits authorization activity to a specific time period. ' validityStartDate: type: string description: >- Identifies the date from which the virtual card account can be used for transactions. validityEndDate: type: string description: >- Identifies the date until which the virtual card account can be used for transactions. modifyAmountRangeControl: 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. maxAmount: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. minAmount: type: number format: bigdecimal description: Identifies the minimum allowed transaction amount. modifyTransactionLimitControl: type: boolean description: Limits individual transactions to a maximum amount. amountLimit: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. modifyCurfewControl: type: boolean description: >- Limits authorization activity to a single time period for each day selected. curfewTime: $ref: '#/definitions/CurfewTime' modifyTimeOfDayControl: type: boolean description: Limits authorization request to defined time periods each day timeOfDay: type: array items: $ref: '#/definitions/TimeOfDay' modifyAgingVelocityControl: 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. authorizationHoldDays: type: number format: long description: >- Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. modifyGeographyControl: type: boolean description: Limits authorization requests to a defined geographic location. countryCodes: type: array description: Defines the merchant country in which the VCA can be used. items: type: string allowed: type: boolean description: Indicate whether the values in countryCode are allowed or disallowed modifyMerchantIdControl: type: boolean description: >- Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa). merchantId: $ref: '#/definitions/MerchantIdRequest' ModifyVirtualCardResponse: 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. 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. ' securityCode: type: string description: The security code (i.e. cvv) corresponding to the virtual card accunt. 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: >- 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. paymentBeneficiaryId: type: number description: >- Uniquely identifies the payment beneficiary for which the virtual card is created. paymentBeneficiaryEmails: type: array description: >- 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. items: type: string customReference: type: array items: $ref: '#/definitions/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 format: bigdecimal description: 'Limits the overall amount spend on the virtual card account. ' modifySpendVelocityControl: type: boolean description: >- Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period. spendVelocity: type: array items: $ref: '#/definitions/SpendVelocityResponse' modifyValidityPeriodControl: type: boolean description: 'Limits authorization activity to a specific time period. ' validityStartDate: type: string description: >- Identifies the date from which the virtual card account can be used for transactions. validityEndDate: type: string description: >- Identifies the date until which the virtual card account can be used for transactions. modifyAmountRangeControl: 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. maxAmount: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. minAmount: type: number format: bigdecimal description: Identifies the minimum allowed transaction amount. modifyTransactionLimitControl: type: boolean description: Limits individual transactions to a maximum amount. amountLimit: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. modifyCurfewControl: type: boolean description: >- Limits authorization activity to a single time period for each day selected. curfewTime: $ref: '#/definitions/CurfewTime' modifyTimeOfDayControl: type: boolean description: 'Limits authorization request to defined time periods each day. ' timeOfDay: type: array items: $ref: '#/definitions/TimeOfDay' modifyAgingVelocityControl: 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. authorizationHoldDays: type: number format: long description: >- Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. modifyGeographyControl: type: boolean description: 'Limits authorization requests to a defined geographic location. ' countryCodes: type: array description: Defines the merchant country in which the VCA can be used. items: type: string allowed: type: boolean description: Indicate whether the values in countryCode are allowed or disallowed modifyMerchantIdControl: type: boolean description: >- Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa). merchantInfo: type: array items: $ref: '#/definitions/MerchantIdResponse' ModifyVirtualCardFailureResponse: 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. 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. ' securityCode: type: string description: The security code (i.e. cvv) corresponding to the virtual card accunt. errors: type: array items: $ref: '#/definitions/ErrorMessage' 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: >- 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. paymentBeneficiaryId: type: number description: >- Uniquely identifies the payment beneficiary for which the virtual card is created. paymentBeneficiaryEmails: type: array description: >- 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. items: type: string customReference: type: array items: $ref: '#/definitions/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 format: bigdecimal description: 'Limits the overall amount spend on the virtual card account. ' modifySpendVelocityControl: type: boolean description: >- Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period. spendVelocity: type: array items: $ref: '#/definitions/SpendVelocityResponse' modifyValidityPeriodControl: type: boolean description: 'Limits authorization activity to a specific time period. ' validityStartDate: type: string description: >- Identifies the date from which the virtual card account can be used for transactions. validityEndDate: type: string description: >- Identifies the date until which the virtual card account can be used for transactions. modifyAmountRangeControl: 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. maxAmount: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. minAmount: type: number format: bigdecimal description: Identifies the minimum allowed transaction amount. modifyTransactionLimitControl: type: boolean description: Limits individual transactions to a maximum amount. amountLimit: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. modifyCurfewControl: type: boolean description: >- Limits authorization activity to a single time period for each day selected. curfewTime: $ref: '#/definitions/CurfewTime' modifyTimeOfDayControl: type: boolean description: 'Limits authorization request to defined time periods each day. ' timeOfDay: type: array items: $ref: '#/definitions/TimeOfDay' modifyAgingVelocityControl: 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. authorizationHoldDays: type: number format: long description: >- Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. modifyGeographyControl: type: boolean description: 'Limits authorization requests to a defined geographic location. ' countryCodes: type: array description: Defines the merchant country in which the VCA can be used. items: type: string allowed: type: boolean description: Indicate whether the values in countryCode are allowed or disallowed modifyMerchantIdControl: type: boolean description: >- Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa). merchantInfo: type: array items: $ref: '#/definitions/MerchantIdResponse' CreateVirtualCardResponse: 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. 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. ' securityCode: type: string description: The security code (i.e. cvv) corresponding to the virtual card accunt. 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: >- 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. paymentBeneficiaryId: type: number description: >- Uniquely identifies the payment beneficiary for which the virtual card is created. paymentBeneficiaryEmails: type: array description: >- 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. items: type: string customReference: type: array items: $ref: '#/definitions/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 format: bigdecimal description: 'Limits the overall amount spend on the virtual card account. ' 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 the “false” is returned or if the field is not returned then the VCA returned is from the backend VCA platform. 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 enableSpendVelocityControl: type: boolean description: >- Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period. spendVelocity: type: array items: $ref: '#/definitions/SpendVelocityResponse' enableValidityPeriodControl: type: boolean description: 'Limits authorization activity to a specific time period. ' validityStartDate: type: string description: >- Identifies the date from which the virtual card account can be used for transactions. validityEndDate: type: string description: >- Identifies the date until which the virtual card account can be used for transactions. 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. maxAmount: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. minAmount: type: number format: bigdecimal description: Identifies the minimum allowed transaction amount. enableTransactionLimitControl: type: boolean description: Limits individual transactions to a maximum amount. amountLimit: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. enableCurfewControl: type: boolean description: >- Limits authorization activity to a single time period for each day selected. curfewTime: $ref: '#/definitions/CurfewTime' enableTimeOfDayControl: type: boolean description: 'Limits authorization request to defined time periods each day. ' timeOfDay: type: array items: $ref: '#/definitions/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. authorizationHoldDays: type: number format: long description: >- Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. enableGeographyControl: type: boolean description: 'Limits authorization requests to a defined geographic location. ' countryCodes: type: array description: Defines the merchant country in which the VCA can be used. items: type: string allowed: type: boolean description: Indicate whether the values in countryCode are allowed or disallowed. enableMerchantIdControl: type: boolean description: >- Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa). merchantInfo: type: array items: $ref: '#/definitions/MerchantIdResponse' CreateVirtualCardFailureResponse: 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. 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. ' securityCode: type: string description: The security code (i.e. cvv) corresponding to the virtual card accunt. errors: type: array items: $ref: '#/definitions/ErrorMessage' 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: >- 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. paymentBeneficiaryId: type: number description: >- Uniquely identifies the payment beneficiary for which the virtual card is created. paymentBeneficiaryEmails: type: array description: >- 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. items: type: string customReference: type: array items: $ref: '#/definitions/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 format: bigdecimal description: 'Limits the overall amount spend on the virtual card account. ' enableSpendVelocityControl: type: boolean description: >- Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period. spendVelocity: type: array items: $ref: '#/definitions/SpendVelocityResponse' enableValidityPeriodControl: type: boolean description: 'Limits authorization activity to a specific time period. ' validityStartDate: type: string description: >- Identifies the date from which the virtual card account can be used for transactions. validityEndDate: type: string description: >- Identifies the date until which the virtual card account can be used for transactions. 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. maxAmount: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. minAmount: type: number format: bigdecimal description: Identifies the minimum allowed transaction amount. enableTransactionLimitControl: type: boolean description: Limits individual transactions to a maximum amount. amountLimit: type: number format: bigdecimal description: Identifies the maximum allowed transaction amount. enableCurfewControl: type: boolean description: >- Limits authorization activity to a single time period for each day selected. curfewTime: $ref: '#/definitions/CurfewTime' enableTimeOfDayControl: type: boolean description: 'Limits authorization request to defined time periods each day. ' timeOfDay: type: array items: $ref: '#/definitions/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. authorizationHoldDays: type: number format: long description: >- Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. enableGeographyControl: type: boolean description: 'Limits authorization requests to a defined geographic location. ' countryCodes: type: array description: Defines the merchant country in which the VCA can be used. items: type: string allowed: type: boolean description: Indicate whether the values in countryCode are allowed or disallowed. enableMerchantIdControl: type: boolean description: >- Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa). merchantInfo: type: array items: $ref: '#/definitions/MerchantIdResponse' x-ibm-configuration: enforced: true testable: true phase: realized cors: enabled: false assembly: execute: - gatewayscript: title: gatewayscript version: 1.0.0 source: "var hm = require('header-metadata');\r\nvar client_id = apim.getvariable('client.app.id');\r\napim.setvariable('message.headers.x-citiportal-apim-client-id',client_id);\r\nif(apim.getvariable('oauth.miscinfo') !=null){\r\nvar oauthmiscinfo = apim.getvariable('oauth.miscinfo');\r\napim.setvariable(\"message.headers.ssoId\",oauthmiscinfo.substring(2));\r\nconsole.error(\"vminfo API failed with return code=\" + oauthmiscinfo.substring(2) );\r\napim.setvariable('message.headers.x-citiportal-apim-client-id',client_id);\r\napim.setvariable(\"message.headers.x-citiportal-loginid\",oauthmiscinfo.substring(2)); \r\n}" - proxy: title: proxy timeout: 60 verb: keep cache-response: protocol cache-ttl: 900 version: 1.0.0 tls-profile: icg-tts-ic target-url: $(hostName)$(api.operation.path) - activity-log: title: activity-log content: header error-content: header version: 1.0.0 catch: [] properties: hostName: value: >- https://grace-engine-service.cloudgsl.nam.nsroot.net/api/tts/cards/vca/v1 description: '' encoded: false categories: - ICG_COMMERCIAL_CARDS catalogs: UAT2: properties: hostName: >- https://grace-engine-service-uat2-icg-tts-grace-173707.apps.namicgswd22u.ecs.dyn.nsroot.net/api/tts/cards/vca/v1 External: properties: hostName: >- https://grace-engine-service.cloudgsl.nam.nsroot.net/api/tts/cards/vca/v1 Internal: properties: hostName: https://grace-engine-nam.cloudgsl.nam.nsroot.net/api/tts/cards/vca/v1 Sandbox: properties: hostName: >- https://grace-engine-service-uat-sb-icg-tts-grace-173707.namicgswd13u.nam.nsroot.net/api/tts/cards/vca/v1 PTE: properties: hostName: >- https://grace-engine-service-uat2-icg-tts-grace-173707.apps.namicgswd22u.ecs.dyn.nsroot.net/api/tts/cards/vca/v1 securityDefinitions: clientCredentials: description: >+ All CitiConnect APIs use the oAuth2 authentication scheme, which requires a bearer token to authenticate your API call. The Token URL includes the version of authentication used by this API. See the Citi Authentication API reference for information on requesting a token. type: oauth2 tokenUrl: https://tts.apib2b.citi.com/tts/api/v1/oauth2/token flow: application scopes: null