HiPay settlement API
Everything you need to get all settlement details
OpenAPI Specification
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>:<API password>'')`
'
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/