swagger: '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
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
schemes:
  - https
produces:
  - application/json
security:
  - clientCredentials: []
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
          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
          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
          type: string
        - name: Country
          in: header
          description: >-
            Three character length country code used during onboarding into
            Citi.
          required: true
          type: string
        - name: Region
          in: header
          description: >-
            This value will be used by APIm to route to the respective Citi
            backend instance
          required: true
          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
          type: string
        - in: body
          name: ClearingExceptionReportInboundRequest
          description: ClearingExceptionReportInboundRequest
          required: true
          schema:
            $ref: '#/definitions/ClearingExceptionReportInboundRequest'
      responses:
        '200':
          description: >-
            <table><tr><td>Code</td><td>Details</td></tr><tr><tr><td>ClearingExceptionReportInboundResponse</td><td>success</td></tr></table>
          schema:
            $ref: '#/definitions/ClearingExceptionReportInboundResponse'
        '206':
          description: >-
            <table><tr><td>ClearingExceptionReportInboundResponse</td><td>Partial
            success</td></tr></table>
          schema:
            $ref: '#/definitions/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>
          schema:
            $ref: '#/definitions/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>
          schema:
            $ref: '#/definitions/ResponseCode500'
securityDefinitions:
  clientCredentials:
    description: >+
      All CitiConnect APIs use the oAuth2 authentication scheme, which requires
      a bearer token to authenticate your API call. The Token URL includes the
      version of authentication used by this API. See <a
      href="../../authentication/authentication-api-reference/"
      target="_blank">the Citi Authentication API reference</a> for information
      on requesting a token.

    type: oauth2
    tokenUrl: https://tts.apib2b.citi.com/tts/cards/api/v1/oauth2/token
    flow: application
    scopes: null
definitions:
  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: '#/definitions/Info'
      clearingRecords:
        type: array
        items:
          $ref: '#/definitions/ClearingRecords'
  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
  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: '#/definitions/CustomReference'
  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
  ClearingExceptionReportErrorResponse:
    properties:
      errorMessage:
        type: array
        items:
          $ref: '#/definitions/ErrorResponseCode'
  ErrorResponseCode:
    properties:
      code:
        type: string
        format: alphanumeric
        description: which indicates the error code
        enum:
          - ERS0060
          - ERS0052
          - ERS0054
          - ERS0051
          - ERS0053
          - ERS0057
          - MS0002
          - ERS0072
          - ERS0003
          - ERS0063
          - ERS0004
          - ERS0061
          - MS0006
          - ERS0001
          - GRC0001
          - GRC0002
          - GRC0003
          - GRC0004
          - GRC0007
          - GRC0011
          - GRC0012
          - GRC0014
          - ERS0067
          - ERS0068
          - ERS0069
          - ERS0070
          - ERS0071
          - ERC0004
      description:
        type: string
        format: alphanumeric
        description: >-
          The error description that corresponds to error code when there is
          any<br> error occurred while retrieving the transaction.<br>*
          `ERS0001`-Invalid Virtual Card Account Number format<br>*
          `ERS0003`-timeZone field is empty or has an invalid UTC offset time
          zone format<br>* `ERS0010`-Invalid Report ID format. Report ID must
          include numeric values<br>* `ERC0004`-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.<br>*
          `ERS0051`- startDate should not exceed todays date<br>*
          `ERS0052`-endDate should not exceed todays date<br>* `ERS0053`-Start
          Date is Mandatory.<br>* `ERS0054`-End Date is Mandatory.<br>*
          `ERS0057`-startDate value exceeds requested endDate value<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\t<br>* `ERS0063`-Requested Time Zone is not
          supported<br>* `ERS0068`-Program Id is Mandatory.\t<br>* `ERS0069`-Vca
          Id is Mandatory.<br>* `ERS0071`-Virtual Card Account Number is
          Mandatory.<br>* `ERS0072`-Requested report date cannot exceed 36
          months in the past from todays date<br>* `ERS0079`-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).<br>* `ERS0080`-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).<br>*
          `ERS0081`-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).<br>* `ERS0082`-The
          requested report IDs are for different VCAs, Please include report IDs
          that belong to the same VCA.<br>* `ERS0083`-The requested report IDs
          are for different program IDs, Please include report IDs that belong
          to the same program ID.<br>* `ERS0084`-The requested report IDs are
          for different requested time zones, Please include report IDs that
          belong to the same requested time zone.<br>* `ERS0091`-startDate value
          must have valid format: YYYY-MM-DD<br>* `ERS0092`-endDate value must
          have valid format: YYYY-MM-DD<br>* `ERS0093`-The date specified in
          startDate does not exist<br>* `ERS0094`-The date specified in endDate
          does not exist<br>* `ERS0095`-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<br>* `ERS0096`-programId included in the request is
          unauthorized for the Clearing Exception Report API<br>*
          `MS0001`-Invalid Virtual Card Account Number<br>* `MS0002`-From date
          should be before to date.<br>* `MS0006`-Invalid vcaId value<br>*
          `MS0008`-Invalid Report ID<br>* `GRC0001`-We have encountered an error
          and couldn't receive your request. Please try again, or contact Citi
          support if you have any further questions or comments<br>*
          `GRC0002`-Client ID is missing in the request header\t<br>*
          `GRC0003`-Invalid JSON Input<br>* `GRC0004`-Region ID is not available
          in the request<br>* `GRC0005`-Client Tracking ID is missing in the
          request header<br>* `GRC0010`-Client Tracking ID length should contain
          a min of 1 character and a max of 36 characters<br>* `GRC0011`- Client
          ID and/or Country and/or region id is missing in Client Onboard
          Configuration setup. Contact Citi support.<br>* `GRC0012`-Necessary
          header value is missing<br>* `GRC0014`-We have encountered an error
          and couldn't receive your request. Please try again, or contact Citi
          support if you have any further questions or comments\t<br>*
          `GRC0016`-Country code is not available in the request
  ResponseCodes400:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ResponseCodes'
  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
  ResponseCode500:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/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