swagger: '2.0'
info:
  version: 1.0.0
  title: HiPay Enterprise Finance API
  description: |

    When using HiPay Enterprise, all your sales are consolidated and settled (transferred to your bank account).
    The Finance API allows you to get all the details about settlements executed for your merchant account.

    # Integration
    The `settlement` endpoint allows you to either consult the whole list of settlements or search for particular settlements by amount or date.
    You can get the total amount which has been transferred to your bank account as well as the total sales amount, refunds, fees and chargebacks for each settlement by using the `/settlement/{id}` endpoint.
    You may also download settlement files in spreadsheet formats (xls, csv) or plain text by leveraging the `/settlement/{id}/raw{ext}` endpoint.

    Note: this documentation describes the Finance API parameters and response fields and allows you to test the platform in real time.

    # Web service information

    ## Finance API base URLs

    | Environment | Base URL |
    | --- | --- |
    | Stage | https://stage-api.hipay-tpp.com/v1 |
    | Production | https://api.hipay-tpp.com/v1 |

    ## Authentication

    All requests to HiPay Enterprise API require you to authenticate using the HTTP *Basic Authentication* to convey your identity. Your API credentials can be found in your HiPay Enterprise back office in the Integration section. Most HTTP clients (including web-browsers) have built-in support for HTTP Basic Authentication. If not, the following header must be included in all HTTP requests.

    `Authorization: Basic base64("<API login>:<API password>")`
host: stage-api.hipay-tpp.com
basePath: /v1
securityDefinitions:
  basicAuth:
    type: basic
tags:
  - name: settlement
    description: Everything you need to get all settlement details
schemes:
  - https
consumes:
  - multipart/form-data
produces:
  - application/json
paths:
  /settlement:
    get:
      description: |
        This endpoint allows you to get the whole list of settlements for the merchant account you're authenticated with.
        The results are paginated, which means that not all the settlements are returned in one API call. Check the `page` and `per_page` parameters for more information about pagination.

        You may need to search for particular settlements. To this end, this endpoint also offers filtering parameters which allow you to get settlements for a specific amount and currency or in a specific date range.
        Check out the `amount`, `currency`, `date_from` and `date_to` parameters for more information about filtering capabilities.
      summary: Lists settlements for your merchant account
      tags:
        - settlement
      operationId: getSettlements
      parameters:
        - in: query
          schema:
            example: 19.99
          required: false
          name: amount
          type: number
          description: Parameter which filters settlements equal to this amount.
        - in: query
          required: false
          name: currency
          description: Parameter which filters settlements in this currency. This three-character currency code complies with ISO 4217.
          type: string
          enum:
            - AED
            - AFN
            - ALL
            - AMD
            - ANG
            - AOA
            - ARS
            - AUD
            - AWG
            - AZN
            - BAM
            - BBD
            - BDT
            - BGN
            - BHD
            - BIF
            - BMD
            - BND
            - BOB
            - BRL
            - BSD
            - BTN
            - BWP
            - BYR
            - BZD
            - CAD
            - CDF
            - CHF
            - CLP
            - CNY
            - COP
            - CRC
            - CUC
            - CUP
            - CVE
            - CZK
            - DJF
            - DKK
            - DOP
            - DZD
            - EGP
            - ERN
            - ETB
            - EUR
            - FJD
            - FKP
            - GBP
            - GEL
            - GGP
            - GHS
            - GIP
            - GMD
            - GNF
            - GTQ
            - GYD
            - HKD
            - HNL
            - HRK
            - HTG
            - HUF
            - IDR
            - ILS
            - IMP
            - INR
            - IQD
            - IRR
            - ISK
            - JEP
            - JMD
            - JOD
            - JPY
            - KES
            - KGS
            - KHR
            - KMF
            - KPW
            - KRW
            - KWD
            - KYD
            - KZT
            - LAK
            - LBP
            - LKR
            - LRD
            - LSL
            - LYD
            - MAD
            - MDL
            - MGA
            - MKD
            - MMK
            - MNT
            - MOP
            - MRO
            - MUR
            - MVR
            - MWK
            - MXN
            - MYR
            - MZN
            - NAD
            - NGN
            - NIO
            - NOK
            - NPR
            - NZD
            - OMR
            - PAB
            - PEN
            - PGK
            - PHP
            - PKR
            - PLN
            - PYG
            - QAR
            - RON
            - RSD
            - RUB
            - RWF
            - SAR
            - SBD
            - SCR
            - SDG
            - SEK
            - SGD
            - SHP
            - SLL
            - SOS
            - SPL
            - SRD
            - STD
            - SVC
            - SYP
            - SZL
            - THB
            - TJS
            - TMT
            - TND
            - TOP
            - TRY
            - TTD
            - TVD
            - TWD
            - TZS
            - UAH
            - UGX
            - USD
            - UYU
            - UZS
            - VEF
            - VND
            - VUV
            - WST
            - XAF
            - XCD
            - XDR
            - XOF
            - XPF
            - YER
            - ZAR
            - ZMW
            - ZWD
          schema:
            example: EUR
            default: EUR
        - in: query
          required: false
          name: date_from
          type: string
          schema:
            example: '2016-11-22'
          description: Parameter which filters settlements after this date (format YYYY-MM-DD).
        - in: query
          required: false
          name: date_to
          type: string
          schema:
            example: '2017-01-05'
          description: Parameter which filters settlements before this date (format YYYY-MM-DD).
        - in: query
          required: false
          schema:
            example: settlementid
            default: settlementid
          name: sort
          type: string
          description: Parameter which sorts settlements by this parameter.
          enum:
            - settlementid
            - amount
            - currency
            - date_value
        - in: query
          required: false
          schema:
            example: 1
          name: page
          type: integer
          minimum: 1
          description: Range of settlements to return.
        - in: query
          required: false
          schema:
            example: 10
          name: per_page
          type: integer
          minimum: 1
          description: Number of settlements to be returned.
      responses:
        '200':
          description: The settlements were properly returned.
          schema:
            type: object
            required:
              - settlements
            description: List of settlements
            properties:
              settlements:
                type: array
                items:
                  type: object
                  description: Settlement item information
                  required:
                    - settlementid
                    - amount
                    - currency
                    - date_value
                  properties:
                    recipient_name:
                      type: string
                      description: Recipient name
                    recipient_iban:
                      type: string
                      description: Recipient IBAN
                    recipient_bic:
                      type: string
                      description: Recipient BIC
                    recipient_bank_country:
                      type: string
                      description: Recipient bank country
                    amount:
                      type: number
                      description: Settlement amount
                    currency:
                      type: string
                      description: Settlement currency
                    date_value:
                      type: string
                      description: Settlement date
                    merchant_name:
                      type: string
                      description: Merchant name
                    merchant_id:
                      type: integer
                      description: Merchant id
                      format: int32
                    settlementid:
                      type: integer
                      description: Setllement ID
                    sales:
                      type: number
                      description: Sales amount
                    refunds:
                      type: number
                      description: Refunds amount
                    fees:
                      type: number
                      description: Fees amount
                    chargeback:
                      type: number
                      description: Chargebacks amount
                    deferred:
                      type: number
                      description: Deferred amount
                    rolling:
                      type: number
                      description: Rollings amount
                    other:
                      type: number
                      description: Other amount
                description: ''
        '400':
          description: The request was rejected due to a validation error.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
        '401':
          description: An authentication error occurred/invalid credentials.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
        '403':
          description: Access to this resource is fordidden.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
      security:
        - basicAuth: []
  '/settlement/{id}':
    get:
      summary: Retrieves details on a specific settlement
      description: |
        This endpoint allows you to get all details for a specific settlement based on its settlement ID. Details include:

        - Bank transfer info (bank name, recipient IBAN, etc.)

        - Total amount transferred to the bank account

        - Detailed amounts (sales, refunds, chargebacks, fees, etc.)
      tags:
        - settlement
      operationId: getSettlementItem
      parameters:
        - in: path
          name: id
          type: integer
          required: true
          schema:
            example: 123456
          description: The settlement ID.
      responses:
        '200':
          description: The settlement item was properly returned.
          schema:
            type: object
            description: Settlement item information
            required:
              - settlementid
              - amount
              - currency
              - date_value
            properties:
              recipient_name:
                type: string
                description: Recipient name
              recipient_iban:
                type: string
                description: Recipient IBAN
              recipient_bic:
                type: string
                description: Recipient BIC
              recipient_bank_country:
                type: string
                description: Recipient bank country
              amount:
                type: number
                description: Settlement amount
              currency:
                type: string
                description: Settlement currency
              date_value:
                type: string
                description: Settlement date
              merchant_name:
                type: string
                description: Merchant name
              merchant_id:
                type: integer
                description: Merchant id
                format: int32
              settlementid:
                type: integer
                description: Setllement ID
              sales:
                type: number
                description: Sales amount
              refunds:
                type: number
                description: Refunds amount
              fees:
                type: number
                description: Fees amount
              chargeback:
                type: number
                description: Chargebacks amount
              deferred:
                type: number
                description: Deferred amount
              rolling:
                type: number
                description: Rollings amount
              other:
                type: number
                description: Other amount
        '400':
          description: The request was rejected due to a validation error.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
        '401':
          description: An authentication error occurred/invalid credentials.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
        '403':
          description: Access to this resource is fordidden.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
        '404':
          description: Settlement item was not found.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
      security:
        - basicAuth: []
  '/settlement/{id}/raw{ext}':
    get:
      summary: Returns the content of a settlement file in a given format
      description: |
        This endpoint allows you to download a settlement file in raw format given a specific settlement ID.
        Available formats for download are: `.txt`, `.xls` and `.csv`.
      tags:
        - settlement
      operationId: getSettlementRaw
      parameters:
        - in: path
          name: id
          type: integer
          schema:
            example: 123456
          required: true
          description: The settlement ID.
        - in: path
          name: ext
          type: string
          required: true
          enum:
            - .csv
            - .xls
            - .txt
          description: The format of the settlement raw file you want to download.
          schema:
            example: .csv
            default: .csv
      responses:
        '200':
          description: The settlement item was properly returned.
        '400':
          description: The request was rejected due to a validation error.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
        '401':
          description: An authentication error occurred/invalid credentials.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
        '403':
          description: Access to this resource is fordidden.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
        '404':
          description: Settlement item was not found.
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - description
                properties:
                  code:
                    type: integer
                    description: Error code
                  message:
                    type: string
                    description: Error message
                  description:
                    type: string
                    description: Error description
      security:
        - basicAuth: []