openapi: 3.0.0
info:
  description: >-
    Returns identification parameters and controls sets on the virtual card
    account.<br><br>Note: For Visa, the authorization controls that were set on
    the virtual card will only be returned in the Get VCA Details API response
    when today's date is within the validity period. If today's date is before
    the validity period start date, or if today's date is after the validity
    period end date, then the authorization controls that were set on the
    virtual card will not be returned in the Get VCA Details API response
  version: 2.0.0
  title: get-vca-details
  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
paths:
  /details:
    post:
      summary: >-
        Returns account balance, identification parameters, and controls sets on
        the virtual card account
      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/>
                         </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/>
                         </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>

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

            <tr><td>ERS0001</td><td>Invalid Virtual Card Account Number
            format</td></tr>

            <tr><td>ERS0007</td><td>Invalid Message ID format</td></tr>

            <tr><td>ERS0060</td><td>Client ID and/or Program Id is missing in
            Client Onboard Configuration setup. Contact Citi support.</td></tr>

            <tr><td>ERS0061</td><td>VCA ID is not present in our
            system</td></tr>

            <tr><td>ERS0068</td><td>Program Id is Mandatory.</td></tr>

            <tr><td>ERS0069</td><td>Vca Id is Mandatory.</td></tr>

            <tr><td>ERS0070</td><td>Message Id is
            Mandatory.</td></tr><tr><td>ERS0071</td><td>Virtual Card Account
            Number is Mandatory.</td></tr>

            <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>

            <tr><td>ERS0086</td><td>Card details not available. Please retry
            after 30 sec with original create message id:
            {originalCreateMessageId}.</td></tr>

            <tr><td>ERS0088</td><td>originalCreateMessageId size must be between
            28 and 36 character</td></tr>

            <tr><td>ERS0089</td><td>originalCreateMessageId should be
            alphanumeric without special characters</td></tr>

            <tr><td>GRC0002</td><td>Client ID is missing in the request header
            </td></tr>

            <tr><td>GRC0003</td><td>Invalid JSON Input</td></tr>

            <tr><td>GRC0004</td><td>Region ID is not available in the
            request</td></tr>

            <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>

            <tr><td>GRC0016</td><td>Country code is not available in the
            request</td></tr>


            <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>

            <tr><td>VSN0021</td><td>messageId cannot be null</td></tr>

            <tr><td>VSN0022</td><td>Invalid Message ID format</td></tr>

            <tr><td>VSN0023</td><td>Message ID already exists.</td></tr>

            <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>

            <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>

            <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>

            <tr><td>VSN0027</td><td>Program ID is mandatory.</td></tr>

            <tr><td>VSN0028</td><td>Invalid Program ID format</td></tr>

            <tr><td>VSN0029</td><td>Invalid Program ID format</td></tr>

            <tr><td>VSN0030</td><td>Client ID and/or Program Id is missing in
            Client Onboard Configuration setup. Contact Citi support.</td></tr>

            <tr><td>VSN0031</td><td>The required Virtual Card Account Number
            Field was empty</td></tr>

            <tr><td>VSN0032</td><td>Invalid Virtual Card Account Number
            format</td></tr>

            <tr><td>VSN0033</td><td>Invalid Virtual Card Account Number
            format</td></tr>

            <tr><td>VSN0034</td><td>Invalid Virtual Card Account Number
            format</td></tr>

            <tr><td>VSN0035</td><td>VCA details could not be found for the given
            Virtual Card Account Number.</td></tr>

            <tr><td>VSN0036</td><td>VCA details could not be found for the given
            Virtual Card Account Number.</td></tr>

            <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>

            <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>

            <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>

            <tr><td>VSN0040</td><td>VCA details could not be found for the given
            Virtual Card Account Number.</td></tr>

            <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>
             
            <tr><td>VSN0042</td><td>VCA ID is not present with Master
            card</td></tr>

            <tr><td>VSN0043</td><td>VCA ID is not present with Master card
            </td></tr>


            </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:
    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
    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
    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
    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
    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
    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'
    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
    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
    GetVcaDetailsInboundErrorResponse:
      properties:
        errorMessage:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseCode'
    ErrorResponseCode:
      properties:
        code:
          description: which indicates the error code
          type: string
          format: alphanumeric
          enum:
            - ERS0001
            - ERS0007
            - ERS0060
            - ERS0061
            - ERS0068
            - ERS0069
            - ERS0070
            - ERS0071
            - ERS0085
            - ERS0086
            - ERS0088
            - ERS0089
            - GRC0002
            - GRC0003
            - GRC0004
            - GRC0011
            - GRC0016
            - VSN0020
            - VSN0021
            - VSN0022
            - VSN0023
            - VSN0024
            - VSN0025
            - VSN0026
            - VSN0027
            - VSN0028
            - VSN0029
            - VSN0030
            - VSN0031
            - VSN0032
            - VSN0033
            - VSN0034
            - VSN0035
            - VSN0036
            - VSN0037
            - VSN0038
            - VSN0039
            - VSN0040
            - VSN0041
            - VSN0042
            - VSN0043
            - GRC0001
            - GRC0006
            - GRC0009
            - GRC0014
        description:
          description: >-
            " The error description that corresponds to error code when there is
            any<br>    error occurred while retrieving the trsansaction.<br>*
            `ERS0001` - Invalid Virtual Card Account Number format<br>*
            `ERS0007` - Invalid Message ID format<br>* `ERS0060` - Client ID
            and/or Program Id is missing in Client Onboard Configuration setup.
            Contact Citi support.<br>* `ERS0061` - VCA ID is not present in our
            system<br>* `ERS0068` - Program Id is Mandatory.<br>* `ERS0069` -
            Vca Id is Mandatory.<br>* `ERS0070` - Message Id is Mandatory.<br>*
            `ERS0071` - Virtual Card Account Number is Mandatory.<br>* `ERS0085`
            - No VCA data was found for original create message id:
            {originalCreateMessageId}. Please send a new create VCA
            request.<br>* `ERS0086` - Card details not available. Please retry
            after 30 sec with original create message id:
            {originalCreateMessageId}.<br>* `ERS0088` - originalCreateMessageId
            size must be between 28 and 36 character<br>* `ERS0089` -
            originalCreateMessageId should be alphanumeric without special
            characters<br>* `GRC0002` - Client ID is missing in the request
            header <br>* `GRC0003` - Invalid JSON Input<br>* `GRC0004` - Region
            ID is not available in the request<br>* `GRC0011` - Client ID and/or
            Country and/or region id is missing in Client Onboard Configuration
            setup. Contact Citi support.<br>* `GRC0016` - Country code is not
            available in the request<br><br>* `VSN0020` - We were unable to
            process your request. Please try again, or contact Citi support if
            you have any further questions or comments.<br>* `VSN0021` -
            messageId cannot be null<br>* `VSN0022` - Invalid Message ID
            format<br>* `VSN0023` - Message ID already exists.<br>* `VSN0024` -
            We were unable to process your request. Please try again, or contact
            Citi support if you have any further questions or comments.<br>*
            `VSN0025` - We were unable to process your request. Please try
            again, or contact Citi support if you have any further questions or
            comments.<br>* `VSN0026` - We were unable to process your request.
            Please try again, or contact Citi support if you have any further
            questions or comments.<br>* `VSN0027` - Program ID is
            mandatory.<br>* `VSN0028` - Invalid Program ID format<br>* `VSN0029`
            - Invalid Program ID format<br>* `VSN0030` - Client ID and/or
            Program Id is missing in Client Onboard Configuration setup. Contact
            Citi support.<br>* `VSN0031` - The required Virtual Card Account
            Number Field was empty<br>* `VSN0032` - Invalid Virtual Card Account
            Number format<br>* `VSN0033` - Invalid Virtual Card Account Number
            format<br>* `VSN0034` - Invalid Virtual Card Account Number
            format<br>* `VSN0035` - VCA details could not be found for the given
            Virtual Card Account Number.<br>* `VSN0036` - VCA details could not
            be found for the given Virtual Card Account Number.<br>* `VSN0037` -
            We were unable to process your request. Please try again, or contact
            Citi support if you have any further questions or comments.<br>*
            `VSN0038` - We were unable to process your request. Please try
            again, or contact Citi support if you have any further questions or
            comments.<br>* `VSN0039` - We were unable to process your request.
            Please try again, or contact Citi support if you have any further
            questions or comments.<br>* `VSN0040` - VCA details could not be
            found for the given Virtual Card Account Number.<br>* `VSN0041` - We
            were unable to process your request. Please try again, or contact
            Citi support if you have any further questions or comments.<br>
            <br>* `VSN0042` - VCA ID is not present with Master card<br>*
            `VSN0043` - VCA ID is not present with Master card <br> <br>*
            `GRC0001`  - We have encountered an error and couldnt receive your
            request. Please try again, or contact Citi support if you have any
            further questions or comments<br>* `GRC0006`  - We have encountered
            an error and couldnt receive your request. Please try again, or
            contact Citi support if you have any further questions or
            comments<br>* `GRC0009`  - We have encountered an error and couldnt
            receive your request. Please try again, or contact Citi support if
            you have any further questions or comments<br>* `GRC0014`  - We have
            encountered an error and couldnt receive your request. Please try
            again, or contact Citi support if you have any further questions or
            comments
          type: string
          format: alphanumeric
    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
    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
    ResponseCode500:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseCode'
    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
  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
security:
  - clientCredentials:
      - /api
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');\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)$(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