openapi: 3.2.0
info:
  description: Returns identification parameters and controls sets on the virtual card account.
  version: 2.0.0
  title: get-vca-details Get Vca Details API
  contact:
    name: Global CitiConnect Support
    email: citiconnectsupport@citi.com
  x-ibm-name: get-vca-details
servers:
- url: https://tts.apib2b.citi.com/tts/cards/vca/v2/reports
security:
- clientCredentials:
  - /api
tags:
- name: GetVcaDetails
paths:
  /details:
    post:
      summary: Returns account balance, identification parameters, and controls sets on the…
      description: Returns account balance, identification parameters and controls sets on the virtual card account
      operationId: getVcaDetails
      tags:
      - GetVcaDetails
      parameters:
      - name: Content-Type
        in: header
        description: Supports application/json
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Oauth token included by the external client to APIm. APIm will external the client ID and pass it to GRACE
        required: true
        schema:
          type: string
      - name: Country
        in: header
        description: Three character length country code used during onboarding into GRACE
        required: true
        schema:
          type: string
      - name: Region
        in: header
        description: This value will be used by APIm to route to the respective GRACE backend instance
        required: true
        schema:
          type: string
      - name: Req-Sys-Id
        in: header
        description: Unique ID of the API message sent. This ID will be provided back in the corresponding response. The ID can be used for investigation and troubleshooting. The ID must be unique per request.
        required: false
        schema:
          type: string
      requestBody:
        description: GetVcaDetailsInboundRequest
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetVcaDetailsInboundRequest'
            examples:
              Mastercard:
                summary: Get VCA Details - Mastercard Sample Request
                value:
                  vcaId: '17896177'
                  programId: '431341'
                  messageId: CITI00000GetVCADetails20260521195320
              Visa:
                summary: Get VCA Details - Visa Sample Request
                value:
                  vcaId: '2026052114225155307'
                  programId: '918'
                  messageId: CITI00000GetVCADetails20260521195321
                  virtualCardAccountNumber: '4715380372289458'
              Idempotency:
                summary: Get VCA Details - Card Creation Status Check
                value:
                  programId: '918'
                  messageId: CITI00000GetVCADetails20260521195321
                  originalCreateMessageId: CITI00000CreateRequest20260521195310
      responses:
        '200':
          description: <table><tr><td>Code</td><td>Details</td></tr><tr><tr><td>GetVcaDetailsInboundResponse</td><td>success</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVcaDetailsInboundResponse'
              examples:
                Mastercard:
                  summary: Get VCA Details - Mastercard Sample Response
                  value:
                    vcaId: '7890123456789'
                    virtualCardAccountNumber: '5412345678901234'
                    messageId: 908c090d1995490eb3b431a1f37356df
                    programId: '431341'
                    securityCode: '123'
                    templateId: '23358'
                    requestStatus: Approved
                    expiryDate: '112026'
                    timeZone: UTC+10:00
                    currencyCode: 008
                    currencyType: B
                    paymentBeneficiaryId: '19180'
                    paymentBeneficiaryEmails:
                    - abcd@citi.com
                    cardImage: "<?xml version=\"1.0\" encoding=\"UTF-8\"?><html><head/> <body style=\"margin:0; padding:0; width:100%\"><div style=\"position: relative;\"><img src=\"data:image/png;base64/>\n   </div></body></html>"
                    mccGrouping:
                    - All MCCs
                    cumulativeSpendLimit: '2000'
                    authorizationHoldDays: '5'
                    availableBalance: '2000'
                    minAmount: '1000.01'
                    maxAmount: '2000.01'
                    validityStartDate: '2022-06-16'
                    validityEndDate: '2022-06-17'
                    curfewTime:
                      startTime: '12:30'
                      endTime: '13:30'
                      weekdaysEffective:
                      - MON
                    customReference:
                    - customReferenceLabel: Invoice No.
                      customReferenceValue: '1234'
                    - customReferenceLabel: Cost Center
                      customReferenceValue: NAM Hub
                    - customReferenceLabel: Department
                      customReferenceValue: Marketing
                Visa:
                  summary: Get VCA Details - Visa Sample Response
                  value:
                    vcaId: '5678901234567'
                    virtualCardAccountNumber: '4012345678901234'
                    messageId: KS08736V2Create20260226131411
                    programId: '918'
                    expiryDate: '122025'
                    timeZone: UTC+05:30
                    currencyCode: '752'
                    currencyType: M
                    mccRange:
                    - 4812-4814
                    - 4816-4817
                    - 5044-5045
                    mccgAllowed: 'true'
                    spendVelocity:
                    - cumulativeSpendLimit: '30000.01'
                      maxAuth: '1'
                      periodType: '3'
                      availableBalance: '30000.01'
                      consumedAmount: '0.00'
                      availableCountBalance: '30000'
                      consumedCount: '0'
                    minAmount: '1000.1'
                    maxAmount: '10000.1'
                    validityStartDate: '2026-12-10'
                    validityEndDate: '2026-12-25'
                    timeOfDay:
                    - startTime: '10:00'
                      endTime: '11:00'
                      weekdayEffective: MON
                    countryCodes:
                    - USA
                    - ZMB
                    - ZWE
                    - SWZ
                    allowed: 'false'
                    merchantInfo:
                      allowed: 'true'
                      merchantIds:
                      - acquirerId: '123450'
                        cardAcceptorId: '132412'
                      - acquirerId: '123451'
                        cardAcceptorId: '1324121'
                      - acquirerId: '123452'
                        cardAcceptorId: '1324112'
                    customReference:
                    - customReferenceLabel: Invoice No.
                      customReferenceValue: '1234'
                    - customReferenceLabel: Cost Center
                      customReferenceValue: NAM Hub
                    - customReferenceLabel: Department
                      customReferenceValue: Marketing
                Idempotency:
                  summary: Get VCA Details - Card Creation Status Check
                  value:
                    vcaId: '7890123456789'
                    virtualCardAccountNumber: '5412345678901234'
                    messageId: 908c090d1995490eb3b431a1f37356df
                    programId: '431341'
                    securityCode: '123'
                    templateId: '23358'
                    requestStatus: Approved
                    expiryDate: '112026'
                    timeZone: UTC+10:00
                    currencyCode: 008
                    currencyType: B
                    paymentBeneficiaryId: '19180'
                    paymentBeneficiaryEmails:
                    - abcd@citi.com
                    cardImage: "<?xml version=\"1.0\" encoding=\"UTF-8\"?><html><head/> <body style=\"margin:0; padding:0; width:100%\"><div style=\"position: relative;\"><img src=\"data:image/png;base64/>\n   </div></body></html>"
                    mccGrouping:
                    - All MCCs
                    cumulativeSpendLimit: '2000'
                    authorizationHoldDays: '5'
                    availableBalance: '2000'
                    minAmount: '1000.01'
                    maxAmount: '2000.01'
                    validityStartDate: '2022-06-16'
                    validityEndDate: '2022-06-17'
                    curfewTime:
                      startTime: '12:30'
                      endTime: '13:30'
                      weekdaysEffective:
                      - MON
                    customReference:
                    - customReferenceLabel: Invoice No.
                      customReferenceValue: '1234'
                    - customReferenceLabel: Cost Center
                      customReferenceValue: NAM Hub
                    - customReferenceLabel: Department
                      customReferenceValue: Marketing
        '400':
          description: "<table><tr><td>ResponseCodes400</td><td><table>\n<tr><th>Error Code</th><th>Error Description</th></tr></td></tr>\n<tr><td>ERS0001</td><td>Invalid Virtual Card Account Number format</td></tr>\n<tr><td>ERS0007</td><td>Invalid Message ID format</td></tr>\n<tr><td>ERS0060</td><td>Client ID and/or Program Id is missing in Client Onboard Configuration setup. Contact Citi support.</td></tr>\n<tr><td>ERS0061</td><td>VCA ID is not present in our system</td></tr>\n<tr><td>ERS0068</td><td>Program Id is Mandatory.</td></tr>\n<tr><td>ERS0069</td><td>Vca Id is Mandatory.</td></tr>\n<tr><td>ERS0070</td><td>Message Id is Mandatory.</td></tr><tr><td>ERS0071</td><td>Virtual Card Account Number is Mandatory.</td></tr>\n<tr><td>ERS0085</td><td>No VCA data was found for original create message id: {originalCreateMessageId}. Please send a new create VCA request.</td></tr>\n<tr><td>ERS0086</td><td>Card details not available. Please retry after 30 sec with original create message id: {originalCreateMessageId}.</td></tr>\n<tr><td>ERS0088</td><td>originalCreateMessageId size must be between 28 and 36 character</td></tr>\n<tr><td>ERS0089</td><td>originalCreateMessageId should be alphanumeric without special characters</td></tr>\n<tr><td>GRC0002</td><td>Client ID is missing in the request header </td></tr>\n<tr><td>GRC0003</td><td>Invalid JSON Input</td></tr>\n<tr><td>GRC0004</td><td>Region ID is not available in the request</td></tr>\n<tr><td>GRC0011</td><td>Client ID and/or Country and/or region id is missing in Client Onboard Configuration setup. Contact Citi support.</td></tr>\n<tr><td>GRC0016</td><td>Country code is not available in the request</td></tr>\n\n<tr><td>VSN0020</td><td>We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.</td></tr>\n<tr><td>VSN0021</td><td>messageId cannot be null</td></tr>\n<tr><td>VSN0022</td><td>Invalid Message ID format</td></tr>\n<tr><td>VSN0023</td><td>Message ID already exists.</td></tr>\n<tr><td>VSN0024</td><td>We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.</td></tr>\n<tr><td>VSN0025</td><td>We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.</td></tr>\n<tr><td>VSN0026</td><td>We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.</td></tr>\n<tr><td>VSN0027</td><td>Program ID is mandatory.</td></tr>\n<tr><td>VSN0028</td><td>Invalid Program ID format</td></tr>\n<tr><td>VSN0029</td><td>Invalid Program ID format</td></tr>\n<tr><td>VSN0030</td><td>Client ID and/or Program Id is missing in Client Onboard Configuration setup. Contact Citi support.</td></tr>\n<tr><td>VSN0031</td><td>The required Virtual Card Account Number Field was empty</td></tr>\n<tr><td>VSN0032</td><td>Invalid Virtual Card Account Number format</td></tr>\n<tr><td>VSN0033</td><td>Invalid Virtual Card Account Number format</td></tr>\n<tr><td>VSN0034</td><td>Invalid Virtual Card Account Number format</td></tr>\n<tr><td>VSN0035</td><td>VCA details could not be found for the given Virtual Card Account Number.</td></tr>\n<tr><td>VSN0036</td><td>VCA details could not be found for the given Virtual Card Account Number.</td></tr>\n<tr><td>VSN0037</td><td>We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.</td></tr>\n<tr><td>VSN0038</td><td>We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.</td></tr>\n<tr><td>VSN0039</td><td>We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.</td></tr>\n<tr><td>VSN0040</td><td>VCA details could not be found for the given Virtual Card Account Number.</td></tr>\n<tr><td>VSN0041</td><td>We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.</td></tr>\n \n<tr><td>VSN0042</td><td>VCA ID is not present with Master card</td></tr>\n<tr><td>VSN0043</td><td>VCA ID is not present with Master card </td></tr>\n\n</table></td></tr></table>"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCodes400'
        '500':
          description: '<table><tr><td>ResponseCode500</td><td><table>

            <tr><th>Error Code</th><th>Error Description</th></tr></td></tr>

            <tr><td>GRC0001</td><td>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</td></tr>

            <tr><td>GRC0006</td><td>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</td></tr>

            <tr><td>GRC0009</td><td>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</td></tr>

            <tr><td>GRC0014</td><td>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</td></tr>

            </table></td></tr></table>'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCode500'
components:
  schemas:
    CurfewTime:
      properties:
        startTime:
          description: Specifies the start time from when the card can be used each of the specified days.<br><br>Mastercard - Optional<br>Visa - Not applicaable<br><br>`Format:` hh:mm
          type: string
          format: alphanumeric
          example: 01:00
          maxLength: 5
        endTime:
          description: Specifies the end time until which the card can be used each of the specified days.<br><br>Mastercard - Optional<br>Visa - Not applicaable<br><br>`Format:` hh:mm
          type: string
          format: alphanumeric
          example: '22:00'
          maxLength: 5
        weekdaysEffective:
          description: Listing of days to which the time curfew applies.<br><br>Mastercard - Optional<br>Visa - Not applicaable<br><br>Possible Values:<br><br>MON<br>TUE<br>WED<br>THU<br>FRI<br>SAT<br>SUN<br>
          type: array
          items:
            type: string
          format: alphanumeric
          example:
          - MON
          - TUE
    GetVcaDetailsInboundRequest:
      properties:
        messageId:
          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 request.
          type: string
          format: alphanumeric
          example: '123456789012345678901234567890123456'
          maxLength: 36
        vcaId:
          description: A reference number that uniquely identifies the virtual card account. Mandatory field if originalCreateMessageId is not included in the request.
          type: string
          format: long
          example: '17896177'
        programId:
          description: Unique ID of the company record defined in the virtual cards system.<br><br>Mastercard - This value is returned in the ID Provisioning API. This value is generated when the VCA program is onboarded to Mastercard's VCA platform. Data format - Long (Numeric). Max character length - 19<br><br>Visa - This value is generated when the VCA program is onboarded to Visa's VCA platform. Data format - Alphanumeric. Max character length - 25
          type: string
          format: long
          example: '233191'
        virtualCardAccountNumber:
          description: The virtual card account number to use for transactions. <br>virtualCardAccountNumber is mandatory only for Visa if originalCreateMessageId is not included in the request.<br><br>Mastercard - Not applicable<br>Visa - Required
          type: string
          format: alphanumeric
          example: '5555000075555000'
          maxLength: 19
        getCardImage:
          description: '* Specifies whether cardImage field needs to be included in the response.<br><br>Mastercard - Optional<br>Visa - Not applicable<br>          <br>          <br>          * True = cardImage field will be sent in the response<br>          <br>          * False = cardImage field will not be sent in the response.<br>          <br>          * `Optional field` if not included, cardImage will be sent in the response.'
          type: string
          format: boolean
          example: 'true'
        originalCreateMessageId:
          description: The API messageId sent in the Create VCA API request. It can be used to check card creation status of the original message ID for up to 4 days since the messageId was used in the VCA Create API request. If originalCreateMessageId is populated in the request, then vcaId and virtualCardAccountNumber are not required in the request
          type: string
          format: alphanumeric
          example: '123456789012345678901234567890123456'
          maxLength: 36
      required:
      - messageId
      - programId
    ResponseCode500:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseCode'
    CustomReference:
      properties:
        customReferenceLabel:
          description: Specifies the label of a custom reference field.
          type: string
          format: alphanumeric
          example: Purchase Type
          maxLength: 50
        customReferenceValue:
          description: Specifies the value of a custom reference field.<br><br>Mastercard - Max Length - 80 characters<br>Visa - Max Length - 100 characters'
          type: string
          format: alphanumeric
          example: Airlines
          maxLength: 100
    ResponseCode:
      properties:
        errorCode:
          description: which indicates the error code
          type: string
          example: GRC0014
        errorDescription:
          description: which indicates the error description
          type: string
          example: We have encountered an error and couldnot receive your request. Please try again, or contact Citi support if you have any further questions or comments
    SpendVelocity:
      properties:
        cumulativeSpendLimit:
          description: Limits the overall amount that can be spent on the virtual card account.<br>Mastercard - Allows a maximumm of 14 digits (12 digits to the left of the decimal and 2 digits to the right of the decimal)<br>Visa - Allows a maximumm of 12 digits (10 digits to the left of the decimal and 2 digits to the right of the decimal)
          type: string
          format: BigDecimal
          example: '10000.00'
          maxLength: 14
        maxAuth:
          description: 'Limits the number of authorizations that can be made with a VCA. Mastercard: If set to 0, unlimited authorizations are allowed on the VCA. (0 is not applicable for Visa)'
          type: string
          format: long
          example: '5'
          maxLength: 19
        periodType:
          description: 'Period for which the control values are valid before they reset.<br><br>Mastercard: <br>D = Daily <br>The balances of control parameters enabled for a VCA are reset with their original values every day at 00:00:00.<br><br>M = Monthly<br>The balances of control parameters enabled for a VCA are reset with their original values at the start of every month. <br><br>W = Weekly<br>The balances of control parameters enabled for a VCA are reset with their original values every Monday at 00:00:00.<br><br>Q = Quarterly<br>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.<br>  Quarter 1: January 01 - March 31.<br>  Quarter 2: April 01 - June 30.<br>  Quarter 3: July 01 - September 30.<br>  Quarter 4: October 01 - December 31.<br><br>Y = Annually<br>The balances of control parameters enabled for a VCA are reset with their original values every year on January 1st at 00:00:00.<br><br>C = Continuous<br>The balances of control parameters enabled for a VCA are retained continuously for the validity period defined. Balances do not reset with their original values throughout the validity period.<br><br>Visa: <br>1 = Recurring<br>The balances of control parameters enabled for a VCA are reset with their original values on a specified recurring day for every month. <br><br>If you select this periodType, you must also specify the resetDay field. <br><br>2 = Monthly<br>The balances of control parameters enabled for a VCA are reset with their original values at the start of every month. <br><br>3 = Date Range<br>The balances of control parameters enabled for a VCA are retained continuously for the validity period defined. Balances do not reset with their original values throughout the validity period.<br><br>If you select this periodType, you must also specify the validityStartDate and validityEndDate fields.'
          type: string
          format: alphanumeric
          example: D
          maxLength: 1
        periodEndDate:
          description: End date of the current period based on the periodType selected.<br><br>Mastercard - Optional<br>Visa - Not applicable
          type: string
          format: alphanumeric
          example: '2020-11-27'
          maxLength: 10
        availableBalance:
          description: Remaining available amount balance on the VCA
          type: string
          format: BigDecimal
          example: '5000.00'
        resetDay:
          description: The day of each month when the control parameter balances should reset to their original value.<br>Mastercard - Not applicable<br>Visa - Optional
          type: string
          format: long
          example: '5'
          maxLength: 19
        consumedAmount:
          description: The amount consumed on the VCA<br>Mastercard - Not applicable<br>Visa - Required
          type: string
          format: BigDecimal
          example: '1100.00'
        availableCountBalance:
          description: Remaining available authorization count balance on the VCA<br>Mastercard - Not applicable<br>Visa - Required
          type: string
          format: long
          example: '1235'
          maxLength: 19
        consumedCount:
          description: The number of authorizations consumed on the VCA<br>Mastercard - Not applicable<br>Visa - Required
          type: string
          format: long
          example: '1222'
          maxLength: 19
    MerchantId:
      properties:
        merchantId:
          description: Specifies the Merchant ID that should be allowed / disallowed when transacting with the virtual card.<br>Mastercard - Optional<br>Visa - Not applicable
          type: string
          format: alphanumeric
          example: 0009876
          maxLength: 15
        acquirerId:
          description: Specifies the Acquirer ID that should be allowed / disallowed when transacting with the virtual card. <br>Mastercard - Optional<br>Visa - Optional
          type: string
          format: long
          example: '123456'
          maxLength: 6
        cardAcceptorId:
          description: Specifies the Card Acceptor ID that should be allowed / disallowed when transacting with the virtual card. <br>Mastercard - Not applicable<br>Visa - Optional
          type: string
          format: alphanumeric
          example: '123456'
          maxLength: 15
    ResponseCodes:
      properties:
        errorCode:
          description: which indicates the error code
          type: string
          format: alphanumeric
          example: ERS0061
          maxLength: 30
        errorDescription:
          description: which indicates the error description
          type: string
          format: alphanumeric
          example: VCA ID is not present in our system
          maxLength: 300
      required:
      - errorCode
      - errorDescription
    ResponseCodes400:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseCodes'
        vcaId:
          description: A reference number that uniquely identifies the virtual card account.
          type: string
          format: long
          example: '900497'
          maxLength: 19
        virtualCardAccountNumber:
          description: The virtual card account number to use for transactions.
          type: string
          format: alphanumeric
          example: '5555000075555000'
          maxLength: 19
        messageId:
          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 request.
          type: string
          format: alphanumeric
          example: CITI00002022122818090320221228180903
          maxLength: 36
        programId:
          description: Returned based on what client passes in the request
          type: string
          format: long
          example: '233191'
          maxLength: 19
    GetVcaDetailsInboundResponse:
      properties:
        vcaId:
          description: A reference number that uniquely identifies the virtual card account.
          type: string
          format: long
          example: '900497'
          maxLength: 19
        virtualCardAccountNumber:
          description: The virtual card account number to use for transactions.
          type: string
          format: alphanumeric
          example: '5555000075555000'
          maxLength: 19
        messageId:
          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 request.
          type: string
          format: alphanumeric
          example: CITI00002022122818090320221228180903
          maxLength: 36
        programId:
          description: Unique ID of the company record defined in the virtual cards system.<br><br>Mastercard - This value is returned in the ID Provisioning API. This value is generated when the VCA program is onboarded to Mastercard's VCA platform. Data format - Long (Numeric). Max character length - 19<br><br>Visa - This value is generated when the VCA program is onboarded to Visa's VCA platform. Data format - Alphanumeric. Max character length - 25
          type: string
          format: long
          example: '233191'
          maxLength: 19
        securityCode:
          description: The security code (i.e. cvv) corresponding to the virtual card accunt.<br><br>Mastercard - Required<br>Visa - Not applicable
          type: string
          format: alphanumeric
          example: '035'
          maxLength: 3
        templateId:
          description: Identifies the template that was setup in the VCA system and that should be used for this virtual card.<br><br>The template setup in the VCA system defines which controls, custom data fields and MCC groupings can be used.<br><br>Mastercard - Required<br>Visa - Not applicable
          type: string
          format: long
          example: '36091'
          maxLength: 19
        requestStatus:
          description: The status of the VCA.<br><br>Mastercard - Required<br>Visa - Not applicable<br><br>Possible values:<br>          - Approved<br>          - Canceled<br>          - Pending Approval<br>          - Declined<br>          - Blocked
          type: string
          format: alphanumeric
          example: Approved
          maxLength: 16
        expiryDate:
          description: Expiry Date of the virtual card account. Represented in UTC time zone.<br>`Format:` YYYY-MM
          type: string
          format: alphanumeric
          example: 2023-12
          maxLength: 7
        timeZone:
          description: 'Defines the time zone applicable for any of the following date or time parameters within controls set for a VCA:

            * Validity Period Control

            * Aging Velocity Control (Mastercard only)

            * Curfew Control

            * Time of Day Control'
          type: string
          format: alphanumeric
          example: UTC+05:30
          maxLength: 9
        currencyCode:
          description: Currency Code in which VCA amounts are expressed.
          type: string
          format: alphanumeric
          example: 008
          maxLength: 3
        currencyType:
          description: 'Mastercard -  Defines the type of the VCA currency.<br>  <ul><li>Value "B" stands for Billing Currency which indicates that the VCA spend limit is expressed in the billing account currency of the underlying funding source. When currencyType = "B", then the VCA can be trasacted with a merchant in any currency.</li> <li>Value "M" stands for Merchant Currency which indicates that Merchant transactions are limited to the VCA currency provided in the currencyCode field.</li></ul>

            <br>Visa

            - The only valid value is "M", which stands for Merchant Currency and indicates that merchant transactions are limited to the VCA currency specified in the currencyCode field. If a currencyType is not provided, then the VCA can be used for any merchant transaction currency.'
          type: string
          format: alphanumeric
          example: B
          maxLength: 1
        paymentBeneficiaryId:
          description: Uniquely identifies the payment beneficiary for which the virtual card is created.<br>Mastercard - Required<br>Visa - Not applicable
          type: string
          format: long
          example: '1133'
          maxLength: 19
        paymentBeneficiaryEmails:
          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:<br>1. Allow VCN details to be emailed to this supplier<br>2. Allow VCN requestor to manually enter a new email address when requesting a VCN<br><br>Mastercard - Optopnal<br>Visa - Not applicable
          type: array
          items:
            type: string
          format: alphanumeric
          example:
          - abc@host.com
        cardImage:
          description: A visual representation of the virtual card account front and back.<br><br>Mastercard - Optional<br>Visa - Not applicable
          type: string
          format: alphanumeric
          example: string
        mccGrouping:
          description: Limits authorizations to defined Merchant Category Codes. Cannot be used in conjunction with the mccRange field<br/><br/>Mastercard - This the name of the Purchase Type that's been configured on the Purchase Template on Mastercard's VCA platform. The Purchase Type value is returned in the Purchase Template Details API<br/><br/>Visa - pass a list of MCCGs defined by Visa to allow or block VCA transactions for the specified MCCGs.<br/><br/>Visa Possible values:<br/><br/>"ATM" - Block ATM cash withdrawals.<br/><br/>"ECOM" - Block all Internet-based transactions.<br/><br/>"CNP" - Block all transactions made over the Internet, phone or mail order.<br/><br/>"NOC" - Block all other cash access. This includes non-ATM transactions such as cash advances and purchase with cashback.<br/><br/>"ADT" - Block purchases at adult-themed merchants.<br/><br/>"FUEL" - Block purchases conducted at fuel/driver merchants (including gas stations, car washes, parking lots and tolls).<br/><br/>"HOT" - All purchases made at hotel merchants will be declined.<br/><br/>"AUTO" - All purchases made at auto-rental merchants will be declined.<br/><br/>"AIR" - All purchases made at airline merchants will be declined.<br/><br/>"REST"- All purchases made at restaurants will be declined.<br/><br/>"JEWL"- All purchases made at jewelry store locations will be declined<br/><br/>"ELEC" - All purchases conducted at electronics themed-merchants will be declined.<br/><br/>"ALC" - All purchases conducted at alcohol and tobacco merchants will be declined.<br/><br/>"GTM" - All purchases conducted at ground transportation merchants will be declined (includes taxis, trains, and bridge tolls).<br/><br/>"OSS" - All purchases conducted at office supply merchants will be declined.<br/><br/>"GROC" - All purchases conducted at grocery store and pharmacy merchants will be declined.<br/><br/>"ENT" - All purchases conducted at entertainment and sports merchants will be declined (includes movie theaters, music stores and sporting goods stores).<br/><br/>"UTIL" - All purchases conducted at utilities will be declined (includes cable, phone and electric companies).<br/><br/>"CLOTH" - All purchases conducted at clothing and general retail merchants will be declined (includes department stores, shoe stores and book stores).<br/><br/>"MED" - All purchases made at medical merchants will be declined.
          type: array
          items:
            type: string
          format: alphanumeric
          example:
          - All MCCs
        mccgAllowed:
          description: Returned if the mccGrouping field is populated or if the mccRange field is populated.<br>Specifies whether the  mccGrouping are allowed or disallowed.<br>If true is passed, the mccGrouping or mccRange is allowed.<br>If false is passed, then the mccGrouping or mccRange is disallowed.<br>Mastercard - Not applicable<br>Visa - Optional
          type: string
          format: boolean
          example: 'true'
        mccRange:
          description: 'Limits authorizations to a defined range of Merchant Category Codes.(eg: [0001-9999, 2000-2999]). Cannot be used in conjunction with the mccGrouping field<br>Mastercard - Not Applicable<br>Visa - Optional'
          type: array
          items:
            type: string
          format: alphanumeric
          example:
          - 0000-9999
        cumulativeSpendLimit:
          description: Limits the overall amount that can be spent on the virtual card account. This field is associated to the Aging Velocity Control<br>Mastercard - Optional. Max character length - 14 digits (12 digits to the left of the decimal and 2 digits to the right of the decimal)<br>Visa - Not applicable
          type: string
          format: BigDecimal
          example: '10000.00'
          maxLength: 14
        authorizationHoldDays:
          description: Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. This field is associated to the Aging Velocity Control<br>Mastercard - Optional<br>Visa - Not applicable
          type: string
          format: long
          example: '21'
          maxLength: 19
        availableBalance:
          description: Specifies the remaining balance available to spend on the virtual card. In response to a VCA creation API request, this value will typically be equal to the cumulativeSpendLimit since no transactions were made on the card yet. This field is associated to the Aging Velocity Control<br>Mastercard - Optional<br>Visa - Not applicable
          type: string
          format: BigDecimal
          example: '10000.00'
        spendVelocity:
          type: array
          items:
            $ref: '#/components/schemas/SpendVelocity'
        amountLimit:
          description: Identifies the maximum allowed transaction amount, associated to the transaction limit control.
          type: string
          format: BigDecimal
          example: '100000.00'
          maxLength: 14
        minAmount:
          description: Identifies the minimum allowed transaction amount, associated to the amount range control.
          type: string
          format: BigDecimal
          example: '11000.00'
          maxLength: 14
        maxAmount:
          description: Identifies the maximum allowed transaction amount, associated to the amount range control.
          type: string
          format: BigDecimal
          example: '50000.00'
          maxLength: 14
        validityStartDate:
          description: Identifies the date from which the virtual card account can be used for transactions. <br>The Start Date must be prior to the End Date.<br>`Format:` YYYY-MM-DD
          type: string
          format: alphanumeric
          example: '2023-01-01'
          maxLength: 10
        validityEndDate:
          description: Identifies the date until which the virtual card account can be used for transactions. <br>The Start Date must be prior to the End Date.<br>`Format:` YYYY-MM-DD
          type: string
          format: alphanumeric
          example: '2024-01-01'
          maxLength: 10
        curfewTime:
          $ref: '#/components/schemas/CurfewTime'
        timeOfDay:
          type: array
          items:
            $ref: '#/components/schemas/TimeOfDay'
        countryCodes:
          description: Defines the merchant country in which the VCA can or cannot be used.
          type: array
          items:
            type: string
          format: alphanumeric
          example:
          - AFG
        allowed:
          description: Indicate whether the values in countryCode are allowed or disallowed.<br>True = values provided in countryCode are allowed<br>False = values provided in countryCode are not allowed
          type: string
          format: boolean
          example: 'true'
        merchantInfo:
          $ref: '#/components/schemas/MerchantInfo'
        customReference:
          description: Array of custom refernce lable & value pairs
          type: array
          items:
            $ref: '#/components/schemas/CustomReference'
      required:
      - vcaId
      - virtualCardAccountNumber
      - messageId
      - programId
      - expiryDate
      - timeZone
    MerchantInfo:
      properties:
        allowed:
          description: Indicate whether the values in merchantId and acquirerId are allowed or disallowed.<br> True = values provided in merchantId and acquirerId are allowed<br> False = values provided in merchantId and acquirerId are not allowed
          type: string
          format: boolean
          example: 'true'
        merchantIds:
          type: array
          items:
            $ref: '#/components/schemas/MerchantId'
    TimeOfDay:
      properties:
        startTime:
          description: Specifies the start time from when the card can be used each of the specified days.t<br><br>Mastercard - Optional<br>Visa - Optional. The minutes digit must be populated with zero only<br><br>`Format:` hh:mm
          type: string
          format: alphanumeric
          example: 01:00
          maxLength: 5
        endTime:
          description: Specifies the end time until which the card can be used each of the specified days.<br><br>Mastercard - Optional<br>Visa - Optional. The minutes digit must be populated with zero only<br><br>`Format:` hh:mm
          type: string
          format: alphanumeric
          example: '22:00'
          maxLength: 5
        weekdayEffective:
          description: Specifies the day applicable to the start and end times defined.<br>Mastercard - Optional<br>Visa - Optional<br><br>Possible Values:<br><br>MON<br>TUE<br>WED<br>THU<br>FRI<br>SAT<br>SUN<br>
          type: string
          format: alphanumeric
          example: WED
          maxLength: 3
  securitySchemes:
    clientCredentials:
      type: oauth2
      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 <a href="../../authentication/authentication-api-reference/" target="_blank">the Citi Authentication API reference</a> for information on requesting a token.<br><br>Sandbox Token URL: https://tts.sandbox.apib2b.citi.com/tts/api/oauth2/token<br>

        '
      flows:
        clientCredentials:
          scopes:
            /api: ''
          tokenUrl: https://tts.apib2b.citi.com/tts/cards/api/oauth2/token
x-ibm-configuration:
  enforced: true
  testable: true
  phase: realized
  cors:
    enabled: false
  properties:
    hostName:
      value: https://base-b-grace-engine-dev-icg-tts-grace-173707.apps.namicggtd29d.ecs.dyn.nsroot.net/api/tts/cards
      description: ''
      encoded: false
  catalogs:
    External:
      properties:
        hostName: https://base-b-grace-engine-dev-icg-tts-grace-173707.apps.namicggtd29d.ecs.dyn.nsroot.net/api/tts/cards
    UAT:
      properties:
        hostName: https://base-b-grace-engine-uat-icg-tts-grace-173707.apps.namicgswd40u.ecs.dyn.nsroot.net/api/tts/cards
  assembly:
    execute:
    - gatewayscript:
        title: gatewayscript
        version: 1.0.0
        source: "var hm = require('header-metadata');\nvar client_id = apim.getvariable('client.app.id');\napim.setvariable('message.headers.x-citiportal-apim-client-id',client_id);\nif(apim.getvariable('oauth.miscinfo') !=null){\nvar oauthmiscinfo = apim.getvariable('oauth.miscinfo');\napim.setvariable(\"message.headers.ssoId\",oauthmiscinfo.substring(2));\nconsole.error(\"vminfo API failed with return code=\" + oauthmiscinfo.substring(2) );\napim.setvariable('message.headers.x-citiportal-apim-client-id',client_id);\napim.setvariable(\"message.headers.x-citiportal-loginid\",oauthmiscinfo.substring(2));  \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)$(request.path)
    - activity-log:
        title: activity-log
        content: header
        error-content: header
        version: 1.0.0
    catch: []
x-apigee-configuration:
  lob: tts
  basepath: /tts/cards/vca/v2/reports
  org: external
  eSSL: mtls
  tlsprofile: smb-ext-egress-tls
  ingressSecurity: oauth
  egressSecurityJWT: 'false'
  jwtHeader: ''
  jwtSubject: ''
  spikeEnabled: 'true'
  quotaEnabled: 'true'
  oauthProduct: oauth2-tts-api-authentication_1-0-0_ttsapiauthentication30mins
  tokenURL: /tts/api/v1/oauth2/token
  scope: /api
  targethost: base-b-grace-engine-uat-cte-icg-tts-grace-173707.apps.namicgswd43u.ecs.dyn.nsroot.net
  targetpath: /api/tts/cards/vca/v2/reports
  setPortalHeaders: ''
  csiId: 173707
  apiproxyname: get-vca-details_2-0-0
  email: pk85409@citi.com