openapi: 3.2.0
info:
  description: The Clearing Exception Report API allows clients to review virtual cards transactions where the clearing amount is greater than the cumulative limit.
  version: ''
  title: VCA Clearing Exception Report API
servers:
- url: https://tts.apib2b.citi.com/tts/cards
  description: production gateway URL
- url: https://tts.sandbox.apib2b.citi.com/tts/cards
  description: sandbox URL
security:
- clientCredentials: []
tags:
- name: VCA Clearing Exception Report
paths:
  /vca/v1/reports/clearingexception:
    post:
      tags:
      - VCA Clearing Exception Report
      summary: Clearing Exceptions
      description: ''
      operationId: getClearingExceptionReport
      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 Citi.
        required: true
        schema:
          type: string
      - name: client_id
        in: query
        required: true
        description: This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for oauth token generation
        schema:
          type: string
      - name: Country
        in: header
        description: Three character length country code used during onboarding into Citi.
        required: true
        schema:
          type: string
      - name: Region
        in: header
        description: This value will be used by APIm to route to the respective Citi backend instance
        required: true
        schema:
          type: string
      - name: Req-Sys-Id
        in: header
        description: Unique ID of the API message sent. The messageId will be provided back in the corresponding response. The ID can be used for investigation and troubleshooting. The ID must be unique per integration.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: <table><tr><td>Code</td><td>Details</td></tr><tr><tr><td>ClearingExceptionReportInboundResponse</td><td>success</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClearingExceptionReportInboundResponse'
        '206':
          description: <table><tr><td>ClearingExceptionReportInboundResponse</td><td>Partial success</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClearingExceptionReportInboundResponse'
        '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>ERS0003</td><td>timeZone field is empty or has an invalid UTC offset time zone format</td></tr> <tr><td>ERS0010</td><td>Invalid Report ID format. Report ID must include numeric values</td></tr><tr><td>ERC0004</td><td>Transactions were unable to be returned for the requested data range. Please try again, or contact Citi support if you have any further questions or comments.</td></tr> <tr><td>ERS0051</td><td> startDate should not exceed today''s date</td></tr> <tr><td>ERS0052</td><td>endDate should not exceed today''s date</td></tr> <tr><td>ERS0053</td><td>Start Date is Mandatory.</td></tr><tr><td>ERS0054</td><td>End Date is Mandatory.</td></tr><tr><td>ERS0057</td><td>startDate value exceeds requested endDate value</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>ERS0063</td><td>Requested Time Zone is not supported</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>ERS0071</td><td>Virtual Card Account Number is Mandatory.</td></tr> <tr><td>ERS0072</td><td>Requested report date cannot exceed 36 months in the past from today''s date</td></tr><tr><td>ERS0079</td><td>The requested report ID(s) is for a VCA that is different than the VCA included in the request. Please include the VCA associated to the report ID(s).</td></tr> <tr><td>ERS0080</td><td>The requested report ID(s) is for a programId that is different than the programId included in the request. Please include the programId associated to the report ID(s).</td></tr><tr><td>ERS0081</td><td>The requested report ID(s) is for a timeZone that is different than the timeZone included in the request. Please include the timeZone associated to the report ID(s).</td></tr><tr><td>ERS0082</td><td>The requested report IDs are for different VCAs, Please include report IDs that belong to the same VCA.</td></tr><tr><td>ERS0083</td><td>The requested report IDs are for different program IDs, Please include report IDs that belong to the same program ID.</td></tr><tr><td>ERS0084</td><td>The requested report IDs are for different requested time zones, Please include report IDs that belong to the same requested time zone.</td></tr><tr><td>ERS0091</td><td>startDate value must have valid format: YYYY-MM-DD</td></tr><tr><td>ERS0092</td><td>endDate value must have valid format: YYYY-MM-DD</td></tr><tr><td>ERS0093</td><td>The date specified in startDate does not exist</td></tr><tr><td>ERS0094</td><td>The date specified in endDate does not exist</td></tr><tr><td>ERS0095</td><td>Report ID included in your request is not present for the given ClientID/program ID. Please generate a new report ID for this Reports request by calling the Reports API without a report ID</td></tr><tr><td>ERS0096</td><td>programId included in the request is unauthorized for the Clearing Exception Report API</td></tr><tr><td>MS0001</td><td>Invalid Virtual Card Account Number</td></tr><tr><td>MS0002</td><td>From date should be before to date.</td></tr><tr><td>MS0006</td><td>Invalid vcaId value</td></tr> <tr><td>MS0008</td><td>Invalid Report ID</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>GRC0005</td><td>Client Tracking ID is missing in the request header</td></tr><tr><td>GRC0010</td><td>Client Tracking ID length should contain a min of 1 character and a max of 36 characters</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>GRC0012</td><td>Necessary header value is missing</td></tr><tr><td>GRC0016</td><td>Country code is not available in the request</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><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></td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCode500'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClearingExceptionReportInboundRequest'
        description: ClearingExceptionReportInboundRequest
        required: true
components:
  schemas:
    Info:
      required:
      - status
      properties:
        fromDate:
          type: string
          format: alphanumeric
          example: '2020-07-23'
          description: 'These are fields returned by Citi to breakup the total requested date range of 30 days for Mastercard.<br>Format: `YYYY-MM-DD`'
          maxLength: 10
        toDate:
          type: string
          format: alphanumeric
          example: '2020-07-29'
          description: 'These are fields returned by Citi to breakup the total requested date range of 30 days for Mastercard.<br>Format: `YYYY-MM-DD`'
          maxLength: 10
        status:
          type: string
          format: alphanumeric
          example: Completed
          description: Defines the status of the data that was requested whether the request has been processed or not.<br>Possible values:<br>Completed<br>Pending<br>Failed
          maxLength: 10
        reportId:
          type: string
          format: alphanumeric
          example: '1234567'
          description: Specifies the report Id generated from Master Card for given 30 day range
          maxLength: 19
        errorCode:
          type: string
          format: alphanumeric
          example: ERS0001
          description: The error code if there is any error occurred while retrieving the transaction
        errorMessage:
          type: string
          format: alphanumeric
          example: Unable to connect master card network at this request, please try again after some time.
          description: The error description that corresponds to error code when there is any error occurred while retrieving the transaction
          maxLength: 200
    ResponseCodes:
      required:
      - errorCode
      - errorDescription
      properties:
        errorCode:
          type: string
          format: alphanumeric
          example: ERS0072
          description: which indicates the error code
          maxLength: 30
        errorDescription:
          type: string
          format: alphanumeric
          example: Requested report date cannot exceed 36 months in the past from today s date
          description: which indicates the error description
          maxLength: 300
    CustomReference:
      properties:
        customReferenceLabel:
          type: string
          format: alphanumeric
          example: Purchase Type
          description: Specifies the label of a custom reference field.
          maxLength: 50
        customReferenceValue:
          type: string
          format: alphanumeric
          example: Airlines
          description: Specifies the value of a custom reference field.
          maxLength: 80
    ResponseCode500:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseCode'
    ResponseCode:
      properties:
        errorCode:
          type: string
          example: GRC0014
          description: which indicates the error code
        errorDescription:
          type: string
          example: We have encountered an error and could not receive your request. Please try again, or contact Citi support if you have any further questions or comments
          description: which indicates the error description
    ClearingRecords:
      required:
      - authorizationAmount
      - cumulativeSpendLimit
      - settlementAmount
      - settlementCurrencyCode
      - settlementCurrencyDescription
      - spendVelocityLimit
      - transactionPostDate
      properties:
        transactionPostDate:
          type: string
          format: alphanumeric
          example: '2020-12-23'
          description: Specifies card transaction once its posted / settled from network
          maxLength: 10
        settlementAmount:
          type: string
          format: double
          example: '100.02'
          description: Specifies card transaction amount where actual settlement was done
          maxLength: 12
        settlementCurrencyCode:
          type: string
          format: alphanumeric
          example: USD
          description: Specifies the currency code on which actual settlement of transaction was done
          maxLength: 3
        settlementCurrencyDescription:
          type: string
          format: alphanumeric
          example: U.S. Dollar
          description: Specifies the currency code description on which actual settlement of transaction was done
          maxLength: 70
        authorizationAmount:
          type: string
          format: double
          example: '95.02'
          description: Specifies the value of transaction amount part of the authorization request
          maxLength: 12
        cumulativeSpendLimit:
          type: string
          format: double
          example: '100.02'
          maxLength: 14
        periodType:
          type: string
          format: alphanumeric
          example: C
          description: 'Period for which the control values are valid before they reset.<br><br>Possible Values: <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.'
          maxLength: 1
        spendVelocityLimit:
          type: string
          format: double
          example: '200.9'
          description: Difference between cumulativeSpendLimit and settlementAmount
          maxLength: 14
        customReference:
          type: array
          description: Array of custom refernce lable & value pairs
          items:
            $ref: '#/components/schemas/CustomReference'
    ResponseCodes400:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseCodes'
    ClearingExceptionReportInboundRequest:
      required:
      - endDate
      - programId
      - startDate
      - timeZone
      - vcaId
      - virtualCardAccountNumber
      properties:
        startDate:
          type: string
          format: alphanumeric
          example: '2020-07-23'
          description: 'Specifies the start date from when the reports can be retrieved.<br>Format: `YYYY-MM-DD`'
          maxLength: 10
        endDate:
          type: string
          format: alphanumeric
          example: '2020-07-29'
          description: 'Specifies the end date upto when the reports can be retrieved.<br>Format: `YYYY-MM-DD`'
          maxLength: 10
        programId:
          type: string
          format: long
          example: '233191'
          description: Unique ID of the company record defined in the virtual cards system.
        vcaId:
          type: string
          format: long
          example: '900497'
          description: A reference number that uniquely identifies the virtual card account.
        virtualCardAccountNumber:
          type: string
          format: alphanumeric
          example: '5555000075555000'
          description: The virtual card account number to use for transactions.
          maxLength: 19
        timeZone:
          type: string
          format: alphanumeric
          example: UTC+05:30
          description: Defines the time zone applicable for any date or time
          maxLength: 9
        reportIds:
          type: array
          example: '[39824281, 2309853]'
          description: Report ID associated to 30-day date range report request
          items:
            type: string
    ClearingExceptionReportInboundResponse:
      required:
      - endDate
      - messageId
      - programId
      - reportStatus
      - startDate
      - timeZone
      - vcaId
      - virtualCardAccountNumber
      properties:
        vcaId:
          type: string
          format: long
          example: '900497'
          description: A reference number that uniquely identifies the virtual card account.
        messageId:
          type: string
          format: alphanumeric
          example: CITI00002022122818090320221228180903
          description: Unique ID of the API message sent. The `messageId` will be provided back in the corresponding response. The ID can be used for investigation and troubleshooting. The ID must be unique per integration.
          minLength: 28
          maxLength: 36
        programId:
          type: string
          format: long
          example: '233191'
          description: Returned based on what client passes in the request
        startDate:
          type: string
          format: alphanumeric
          example: '2020-07-23'
          description: 'Specifies the start date from when the report is retrieved.<br>Format: `YYYY-MM-DD`'
          maxLength: 10
        endDate:
          type: string
          format: alphanumeric
          example: '2020-07-29'
          description: 'Specifies the end date up to when the report is retrieved.<br>Format: `YYYY-MM-DD`'
          maxLength: 10
        reportStatus:
          type: string
          format: alphanumeric
          example: Completed
          description: Defines the status of the data that was requested whether the request has been processed or not.
          maxLength: 16
        warning:
          type: string
          format: alphanumeric
          example: string
          description: Warning information regarding a non-fatal response condition that may be taken into account, but can be ignored
          maxLength: 200
        timeZone:
          type: string
          format: alphanumeric
          example: UTC+05:30
          description: Defines the time zone applicable for any date or time
          maxLength: 9
        virtualCardAccountNumber:
          type: string
          format: alphanumeric
          example: '5555000075555000'
          description: The virtual card account number to use for transactions.
          maxLength: 19
        info:
          type: array
          items:
            $ref: '#/components/schemas/Info'
        clearingRecords:
          type: array
          items:
            $ref: '#/components/schemas/ClearingRecords'
  securitySchemes:
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://tts.apib2b.citi.com/tts/cards/api/v1/oauth2/token
      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.


        '