OpenAPI Specification
openapi: 3.0.0
info:
title: Hipay Payment Gateway balance transfer 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: transfer
description: Transfer funds between HiPay accounts
paths:
/transfer.{_format}:
post:
consumes:
- multipart/form-data
description: '
### Information
Allows you to transfer funds from a HiPay account to another HiPay account. HiPay suggests performing fund allocation and withdrawal all at once.
All the funds are held in escrow before being deposited on the technical account. The Transfer API is then used to allocate funds from the technical account to the merchants'' accounts. The Transfer API allows transfer requests to be made on the agent’s behalf or on the behalf of a third party.
The technical account is therefore a monitoring tool that provides a clear view of fund allocation (fund remittance, refunds, chargebacks).
For more information, please read the [HiPay Marketplace Fund allocation section](/marketplace/api-integration/cash-out#fund-allocation)'
operationId: post_transfer
x-disableTryItOut: true
parameters:
- in: path
name: _format
required: true
type: string
enum:
- json
- xml
default: json
- description: Account ID of the recipient account.
format: int32
in: formData
name: recipient_account_id
type: integer
default: '592734'
- description: Login of the recipient account (email).
in: formData
name: recipient_account_login
type: string
default: developer@hipay.com
- description: Amount of the transfer in the account currency.
format: float
in: formData
name: amount
type: number
default: '19.90'
- description: Label of the transfer known by you and the recipient user.
in: formData
name: public_label
type: string
default: Custom public label
- description: Label of the transfer only known by you.
in: formData
name: private_label
type: string
default: Custom private label
- description: Unique ID of the transfer sent by the merchant. HiPay will process only 1 transfer with this ID.
in: formData
name: merchant_unique_id
type: string
default: ORDER_1973645854
- description: Periodicity type of the transfer.
enum:
- direct
- deferred
- periodic
default: direct
in: formData
name: periodicity_type
type: string
- description: 'Periodicity (required for a periodic transfer).
If you select a date which does not exist every month (29, 30 or 31), the transfer will take place on the last day of the month.
If you select a date before today''s date, the first transfer will take place next month.'
format: int32
in: formData
name: periodicity
type: integer
default: '15'
- description: Execution date of the transfer (required for a deferred transfer).
format: date
in: formData
name: date
type: string
default: '2020-11-20'
- description: Account ID if operations must be made on an account other than yours (you must have specific rights on this account).
in: header
name: php-auth-subaccount-id
type: integer
- description: Account login (email address) if operations must be made on an account other than yours (you must have specific rights on this account).
in: header
name: php-auth-subaccount-login
type: string
produces: []
responses:
'200':
description: Error response
schema:
properties:
code:
description: Status code of the answer. 4 => Action not allowed 26 => Transfer in progress
format: int32
type: integer
default: 4
message:
description: Description of the answer.
type: string
default: Action not allowed
'201':
description: Success response
schema:
properties:
code:
description: Status code of the answer.
format: int32
type: integer
message:
description: Description of the answer.
type: string
transaction_id:
description: HiPay’s transaction ID.
type: string
amount:
description: Transferred amount.
format: float
type: number
currency:
description: Currency of the transfer.
type: string
recipient_username:
description: Login of the recipient account (email).
type: string
public_label:
description: Label of the transfer known by you and the recipient user.
type: string
private_label:
description: Label of the transfer only known by you.
type: string
merchant_unique_id:
description: Unique ID of the transfer sent by the merchant.
type: string
periodicity_type:
description: Periodicity type of the transfer.
type: string
periodicity:
description: Periodicity of the transfer.
type: string
date:
description: Execution date of the transfer.
type: string
'400':
description: Validation failed.
'401':
description: Authentication failed.
summary: Transfer funds between HiPay accounts
tags:
- transfer
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/