swagger: '2.0'
info:
  description: This is the API server supplied by Equens.
  version: '2.0'
  title: Merchant payments - InterchangeFee API
  contact:
    name: equensWorldline API team. See developer portal
host: developer.equensworldline.com
basePath: /MerchantApiInterchangeFee/api
schemes:
  - https
paths:
  /acquiring/interchangefees/v2.0/acquirers/{acquirerId}/transactions/{transactionId}:
    get:
      tags:
      - Interchange fee
      summary: Based on TransactionID
      description: |
        This API call will retrieve the interchange fee for a single transaction. 
      operationId: getInterchangeFee
      consumes:
      - application/json
      - '*/*'
      produces:
      - application/json
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        type: string
        example: "671234567"
      - name: transactionId
        in: path
        description: The Transaction ID identifies a presentment
        required: true
        type: string
        example: "TDS17133017774902264"
      - name: transactionDate
        in: query
        description: Transaction Date (yyyy-mm-dd), known as transaction posting date
        required: true
        type: string
        format: date
        example: "2017-05-01"
      responses:
        '200':
          description: Successful
          schema:
              $ref: '#/definitions/InterchangeFee'
        '400':
          description: Invalid input provided
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: No results found
        '500':
          description: Unexpected error
        '502':
          description: Backend service problem
  /acquiring/interchangefees/v2.0/acquirers/{acquirerId}/payments:
    get:
      tags:
      - Interchange fee
      summary: Based on a Payment Id
      description: |
        Use this operation to retrieve the interchange fees for a Payment
        
        - The result of this operation is a list of interchange fees that belongs to a payment
        - If there is a previous and/or next page the http response header will have a link (url) to this data 
      operationId: getInterchangeFeeListForPayment
      consumes:
      - application/json
      - '*/*'
      produces:
      - application/json
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        type: string
        example: "671234567"
      - name: paymentId
        in: query
        description: Unique identification of the payment in which this transaction has been paid out
        required: true
        type: string
        example: "SO-000000017036619028"
      - name: paymentDate
        in: query
        description: Payment Date (yyyy-mm-dd)
        required: true
        type: string
        format: date
        example: "2017-05-01"
      - name: sortField
        in: query
        description: Sort field
        required: false
        type: string
        enum:
        - InterchangeFeeId
        - TransactionId
        - TransactionDateTime
        - InterchangeFeeType
        - InterchangeRateDesignator
        - Amount
      - name: sortOrder
        in: query
        description: Sort order
        required: false
        type: string
        enum:
        - Ascending
        - Descending
      - name: pageSize
        in: query
        description: Page size
        required: false
        type: string
      - name: pageNumber
        in: query
        description: Page number
        required: false
        type: string
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              $ref: '#/definitions/InterchangeFee'
        '400':
          description: Invalid input provided
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: No results found
        '500':
          description: Unexpected error
        '502':
          description: Backend service problem
  /acquiring/interchangefees/v2.0/acquirers/{acquirerId}/holdings/{holdingId}:
    get:
      tags:
      - Interchange fee
      summary: holding level
      description: |
        This operation retrieves all interchange fees on merchant hierarchy (for example holding) level
        
        - The result of this operation is a list of interchange fees that belongs to a contract level.
        - If there is a previous and/or next page the http response header will have a link (url) to this data 
      operationId: getInterchangeFeeOnMerchantHierarchyLevel
      consumes:
      - application/json
      - '*/*'
      produces:
      - application/json
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        type: string
        example: "671234567"
      - name: holdingId
        in: path
        description: Unique identification of the holdingId, determined by equensWorldline
        required: true
        type: integer
        format: int32
        example: 200
      - name: startDateTime
        in: query
        description: Start DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (greater or equals to this value)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 12:30:00"
      - name: endDateTime
        in: query
        description: End DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (until this value, so not incuded)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 13:30:00"
      - name: sortField
        in: query
        description: Sort field
        required: false
        type: string
        enum:
        - InterchangeFeeId
        - TransactionId
        - TransactionDateTime
        - InterchangeFeeType
        - InterchangeRateDesignator
        - Amount
      - name: sortOrder
        in: query
        description: Sort order
        required: false
        type: string
        enum:
        - Ascending
        - Descending
      - name: pageSize
        in: query
        description: Page size
        required: false
        type: string
      - name: pageNumber
        in: query
        description: Page number
        required: false
        type: string
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              $ref: '#/definitions/InterchangeFee'
        '400':
          description: Invalid input provided
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: No results found
        '500':
          description: Unexpected error
        '502':
          description: Backend service problem
  /acquiring/interchangefees/v2.0/acquirers/{acquirerId}/merchants/{merchantId}:
    get:
      tags:
      - Interchange fee
      summary: Merchant level
      description: |
        This operation retrieves all interchange fees on merchant level
        
        - The result of this operation is a list of interchange fees that belongs to a contract level.
        - If there is a previous and/or next page the http response header will have a link (url) to this data 
      operationId: getInterchangeFeeOnMerchantLevel
      consumes:
      - application/json
      - '*/*'
      produces:
      - application/json
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        type: string
        example: "671234567"
      - name: merchantId
        in: path
        description: Unique identification of the merchant, determined by equensWorldline
        required: true
        type: string
        example: "1280300"
      - name: startDateTime
        in: query
        description: Start DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (greater or equals to this value)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 12:30:00"
      - name: endDateTime
        in: query
        description: End DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (until this value, so not incuded)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 13:30:00"
      - name: sortField
        in: query
        description: Sort field
        required: false
        type: string
        enum:
        - InterchangeFeeId
        - TransactionId
        - TransactionDateTime
        - InterchangeFeeType
        - InterchangeRateDesignator
        - Amount
      - name: sortOrder
        in: query
        description: Sort order
        required: false
        type: string
        enum:
        - Ascending
        - Descending
      - name: pageSize
        in: query
        description: Page size
        required: false
        type: string
      - name: pageNumber
        in: query
        description: Page number
        required: false
        type: string
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              $ref: '#/definitions/InterchangeFee'
        '400':
          description: Invalid input provided
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: No results found
        '500':
          description: Unexpected error
        '502':
          description: Backend service problem
  /acquiring/interchangefees/v2.0/acquirers/{acquirerId}/contracts/{contractId}:
    get:
      tags:
      - Interchange fee
      summary: Contract level
      description: |
        This operation retrieves all interchange fees on contract level
        
        - The result of this operation is a list of interchange fees that belongs to a contract level.
        - If there is a previous and/or next page the http response header will have a link (url) to this data 
      operationId: getInterchangeFeeOnContractLevel
      consumes:
      - application/json
      - '*/*'
      produces:
      - application/json
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        type: string
        example: "671234567"
      - name: contractId
        in: path
        description: Unique identification of the contract, determined by the acquirer
        required: true
        type: string
        example: "12872"
      - name: startDateTime
        in: query
        description: Start DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (greater or equals to this value)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 12:30:00"
      - name: endDateTime
        in: query
        description: End DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (until this value, so not incuded)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 13:30:00"
      - name: sortField
        in: query
        description: Sort field
        required: false
        type: string
        enum:
        - InterchangeFeeId
        - TransactionId
        - TransactionDateTime
        - InterchangeFeeType
        - InterchangeRateDesignator
        - Amount
      - name: sortOrder
        in: query
        description: Sort order
        required: false
        type: string
        enum:
        - Ascending
        - Descending
      - name: pageSize
        in: query
        description: Page size
        required: false
        type: string
      - name: pageNumber
        in: query
        description: Page number
        required: false
        type: string
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              $ref: '#/definitions/InterchangeFee'
        '400':
          description: Invalid input provided
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: No results found
        '500':
          description: Unexpected error
        '502':
          description: Backend service problem
  /acquiring/interchangefees/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites/{siteId}:
    get:
      tags:
      - Interchange fee
      summary: Site level
      description: |
        This operation retrieves all interchange fees on site level
        
        - The result of this operation is a list of interchange fees that belongs to a contract level.
        - If there is a previous and/or next page the http response header will have a link (url) to this data 
      operationId: getInterchangeFeeOnSiteLevel
      consumes:
      - application/json
      - '*/*'
      produces:
      - application/json
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        type: string
        example: "671234567"
      - name: contractId
        in: path
        description: Unique identification of the contract, determined by the acquirer
        required: true
        type: string
        example: "12872"
      - name: siteId
        in: path
        description: Unique identification of the site within the contract
        required: true
        type: integer
        format: int32
        example: 30010
      - name: startDateTime
        in: query
        description: Start DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (greater or equals to this value)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 12:30:00"
      - name: endDateTime
        in: query
        description: End DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (until this value, so not incuded)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 13:30:00"
      - name: sortField
        in: query
        description: Sort field
        required: false
        type: string
        enum:
        - InterchangeFeeId
        - TransactionId
        - TransactionDateTime
        - InterchangeFeeType
        - InterchangeRateDesignator
        - Amount
      - name: sortOrder
        in: query
        description: Sort order
        required: false
        type: string
        enum:
        - Ascending
        - Descending
      - name: pageSize
        in: query
        description: Page size
        required: false
        type: string
      - name: pageNumber
        in: query
        description: Page number
        required: false
        type: string
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              $ref: '#/definitions/InterchangeFee'
        '400':
          description: Invalid input provided
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: No results found
        '500':
          description: Unexpected error
        '502':
          description: Backend service problem
  /acquiring/interchangefees/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites/{siteId}/terminals/{terminalId}:
    get:
      tags:
      - Interchange fee
      summary: Terminal level
      description: |
        This operation retrieves all interchange fees on terminal level
        
        - The result of this operation is a list of interchange fees that belongs to a contract level.
        - If there is a previous and/or next page the http response header will have a link (url) to this data 
      operationId: getInterchangeFeeOnTerminalLevel
      consumes:
      - application/json
      - '*/*'
      produces:
      - application/json
      parameters:
      - name: acquirerId
        in: path
        description: Unique identification of the acquirer, determined by equensWorldline
        required: true
        type: string
        example: "671234567"
      - name: contractId
        in: path
        description: Unique identification of the contract, determined by the acquirer
        required: true
        type: string
        example: "12872"
      - name: siteId
        in: path
        description: Unique identification of the site within the contract
        required: true
        type: integer
        format: int32
        example: 30010
      - name: terminalId
        in: path
        description: Unique code identifying the terminal at the Card acceptor location
        required: true
        type: string
        example: "20YT45"
      - name: startDateTime
        in: query
        description: Start DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (greater or equals to this value)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 12:30:00"
      - name: endDateTime
        in: query
        description: End DateTime the transaction was created (yyyy-mm-dd hh:mm:ss) (until this value, so not incuded)
        required: true
        type: string
        format: date-time
        example: "2019-03-01 13:30:00"
      - name: sortField
        in: query
        description: Sort field
        required: false
        type: string
        enum:
        - InterchangeFeeId
        - TransactionId
        - TransactionDateTime
        - InterchangeFeeType
        - InterchangeRateDesignator
        - Amount
      - name: sortOrder
        in: query
        description: Sort order
        required: false
        type: string
        enum:
        - Ascending
        - Descending
      - name: pageSize
        in: query
        description: Page size
        required: false
        type: string
      - name: pageNumber
        in: query
        description: Page number
        required: false
        type: string
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              $ref: '#/definitions/InterchangeFee'
        '400':
          description: Invalid input provided
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: No results found
        '500':
          description: Unexpected error
        '502':
          description: Backend service problem

################################################################################
#                                 Definitions                                  #
################################################################################
definitions:
  InterchangeFee:
    type: object
    properties:
      transactionIdentification:
        $ref: '#/definitions/TransactionIdentification'
      contractIdentification:
        $ref: '#/definitions/ContractIdentification'
      postingDate:
        type: string
        format: date
        description: Date when this transaction is posted on the merchant balance (yyyy-mm-dd)
        example: 2016-08-21
      transactionFeeType:
        type: string
        description: Type of transaction fee.
        example: "02"
      transactionDateTime:
        type: string
        format: date-time
        description: transaction posting datetime (yyyy-mm-dd hh:mm:ss)
        example: 2016-08-21 09:30:47
      interchangeFeeAmount:
        $ref: '#/definitions/Amount'
      interchangeRateDesignatorCode:
        type: string
        description: Interchange Rate Designator Code
        example: "85"
      issuerRegion:
        type: string
        description: Region of the issuer
        example: "Europe"
      issuerRegionCode:
        type: string
        description: Region of the issuer code
        example: "EU"
      paymentProductCode:
        type: string
        description: Payment product code
        example: "Maes"
      creditDebitIndicator:
        type: string
        description: Credit or Debit indicator. i.e. C = Credit. D = Debit
        example: "D"
      paymentProductTypeCode:
        type: string
        description: Card product type code
        example: "2"
      region:
        type: string
        description: Region of the payment scheme. Regional classification used by the schemes which indicates the location of the acquirer compared to the issuer. i.e. VPAY Netherland, Intra-European, VISA Germany
        example: "VISA Netherland"
      regionCode:
        type: string
        description: Region of the payment scheme code
        example: "A"
      channel:
        type: string
        description: Processing channel for transactions
        example: "Point of Sail"
      transactionConditionCode:
        type: string
        description: Code for Condition in which the transaction took place
        example: "23"
      brand:
        type: string
        description: Brand
        example: "MAES"
  TransactionIdentification:
    type: object
    properties:
      transactionId:
        type: string
        description: Unique identification for a Cardholder Initiated Transaction
        example: "TDS16172008721825920"
  ContractIdentification:
    type: object
    properties:
      acquirerId:
        type: string
        description: Unique identification of the acquirer, determined by equensWorldline
        example: "671234567"
      holdingId:
        type: integer
        format: int32
        description: Unique identification of the holding, determined by equensWorldline
        example: 200
      merchantId:
        type: string
        description: Unique identification of the merchant, determined by the acquirer
        example: "1280300"
      contractId:
        type: string
        description: Unique identification of the contract, determined by the acquirer
        example: "12872"
      cardAcceptorId:
        type: string
        description: Unique identification of the cardAcceptor within the contract
        example: "30010"
      siteId:
        type: integer
        format: int32
        description: Unique identification of the site within the contract
        example: 30010
      terminalId:
        type: string
        description: Unique code identifying the terminal at the Card acceptor location
        example: "20YT45"        
  Amount:
    type: object
    properties:
      amount:
        type: string
        format: unlimited size decimal
        description: |
          Amount in the major units of the currency according to ISO 4217.
          
          In case of euro, "3.10" (is 3.10 euro)
        example: "3.00"
      currency:
        type: string
        description: Currency of the amount
        example: "EUR"