OpenAPI Specification
openapi: 3.0.0
info:
title: Hipay Payment Gateway balance identification 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: identification
description: Manage your identification documents
paths:
/identification.{_format}:
get:
consumes:
- multipart/form-data
description: '
### Information
Get the list of all identification documents for a user-space
For more information, please read the [HiPay Marketplace Account creation section.](/marketplace/api-integration/vendors#account-creation)'
operationId: get_Identification
parameters:
- in: path
name: _format
required: true
type: string
enum:
- json
- xml
default: json
- 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) 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: Success response
schema:
properties:
code:
description: Status code of the answer. 0 => Successful response 2 => Missing parameter 3 => Invalid parameter 7 => Not found 13 => An error occurred, please try again 400 => Bad request
format: int32
type: integer
message:
description: Description of the answer.
type: string
user_space:
description: integer
format: int32
type: integer
identification_status:
description: "### Identification status\n\n - `Unidentified`\n - `In progress`\n - `Identified`"
type: string
documents:
description: Array of objects (IdentificationDocumentResponse).
items:
description: Array of objects (IdentificationDocumentResponse).
properties:
type:
description: "### Type\n\n - `-1`: Missing document\n - `1`: Identity card\n - `2`: Proof of address\n - `4`: Company Registration\n - `5`: Distribution of power\n - `6`: Bank\n - `9`: Tax status\n - `11`: President of the association\n - `12`: Official journal\n - `13`: Association status\n - `14`: Licence"
format: int32
type: integer
label:
description: string
type: string
status_code:
description: "### Status\n\n - `0`: new\n - `1`: waiting\n - `2`: validated\n - `3`: refused\n - `4`: deleted"
format: int32
type: integer
status_label:
description: string
type: string
message:
description: string
type: string
type: array
'400':
description: Validation failed.
'401':
description: Authentication failed.
summary: Get the list of all identification documents for a user-space
tags:
- identification
security:
- basicAuth: []
post:
consumes:
- multipart/form-data
description: "\n### Information\n\nUpload identification documents. Uploaded documents can't exceed 15MB.\n\n__Type of document for a customer account__\n - `1`: Copy of a valid identification document\n\n\n__Type of document for a merchant account (corporation)__\n - `1`: Copy of a valid identification document of the legal representative. *Deprecated, please use type 1 for all ID documents*\n \n - `4`: Document certifying Company registration\n\n - `5`: Signed Articles of Association with the division of powers (featuring the address of the head office, the name of the company and the name of the legal representative)\n\n__Type of document for a merchant account (corporation) with a gambling licence__\n - `1`: Copy of a valid identification document of the legal representative. *Deprecated, please use type 1 for all ID documents*\n \n - `4`: Document certifying Company registration\n\n - `5`: Signed Articles of Association with the division of powers (featuring the address of the head office, the name of the company and the name of the legal representative)\n\n - `14`: Gambling licence document\n\n__Type of document for a merchant account (person)__\n - `1`: Copy of a valid identification document of the legal representative. *Deprecated, please use type 1 for all ID documents*\n\n - `8`: Document certifying registration\n\n - `9`: Document certifying tax status\n\n__In test environment__\n\nYou can choose if the document will be accepted or not by changing the 3 first characters of the uploaded file name.\n - Filename starts with `01_`: document will be refused because unrecognized\n\n - Filename starts with `02_`: document will be refused because falsified\n\n - Filename starts with `03_`: document will be refused because unreadable\n\n - Filename starts with `06_`: document will be refused because inconsistent\n\n - Filename starts with `07_`: document will be refused because expired\n\n - Any other name : document will be automatically accepted\n\n### Account creation step 3/3\nThe agent sends us the account number and the identification/KYC information with this API. HiPay validates the identification/KYC information within three days and sends the agent a notification confirming that the merchant is fully operational."
operationId: post_Identification
parameters:
- in: path
name: _format
required: true
type: string
enum:
- json
- xml
default: json
- description: Type of document.
format: int32
in: formData
required: true
name: type
type: integer
default: '1'
- description: File to upload (jpg, gif, png, pdf). For ID documents, if you have a single file regrouping the front and back sides, please use only this field.
format: byte
in: formData
required: true
name: file
type: file
- description: BBack of file to upload (jpg, gif, png, pdf). Only to be used in case the front and back sides of the ID document are in two separate files
in: formData
name: back
type: file
format: byte
- description: Expiration date of your document.
format: date
in: formData
name: validity_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: Success response.
schema:
properties:
code:
description: Status code of the answer. 0 => Document successfully uploaded 414 => User space already identified 415 => A document of this type is already waiting for validation
format: int32
type: integer
message:
description: Description of the answer.
type: string
user_space:
description: integer
format: int32
type: integer
type:
description: "### Type\n - `-1` : Missing document\n - `1` : Identity card\n - `2` : Proof of address\n - `4`: Company Registration\n - `5` : Distribution of power\n - `6` : Bank\n - `9` : Tax status\n - `11` : President of the association\n - `12` : Official journal\n - `13` : Association status\n - `14` : Licence"
format: int32
type: integer
validity_date:
description: DateTime
format: date-time
type: string
'400':
description: Validation failed.
'401':
description: Authentication failed.
summary: Upload identification documents
tags:
- identification
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/