openapi: 3.0.0 info: title: Hipay Payment Gateway balance settlement API description: '## Version 1.6.1 - June 11, 2025 The Gateway API allows you to get paid and manage orders and transactions. Please note: this documentation describes the Gateway API parameters and response fields and allows you to test the platform in real time. This page is to be used alongside the **[HiPay Enterprise Platform Overview documentation](https://developer.hipay.com/api-explorer/api-online-payments)**, which gives you more information and details on the HiPay Enterprise workflow. You may use both documents in parallel when integrating HiPay Enterprise. # Web service information ## Gateway API base URLs | Environment | Base URL | | --- | --- | | Stage | [https://stage-api-gateway.hipay.com](https://stage-api-gateway.hipay.com) | | Production | [https://api-gateway.hipay.com](https://api-gateway.hipay.com) | ## Authentication All requests to the HiPay Enterprise API require identification through *HTTP Basic Authentication*. Your API credentials can be found in the Integration section of your HiPay Enterprise back office. 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>:'')` ' version: 1.6.1 servers: - url: https://stage-api-gateway.hipay.com description: Stage - url: https://api-gateway.hipay.com description: Production tags: - name: settlement description: Everything you need to get all settlement details 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: [] components: securitySchemes: BasicAuth: type: http scheme: basic ApiKeyAuth: type: apiKey name: X-API-KEY in: header externalDocs: description: Find out more about HiPay url: https://developer.hipay.com/