openapi: 3.0.0
info:
  title: Hipay Payment Gateway balance ubo 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: ubo
  description: Manage your Ultimate Beneficial Ownerships (UBO)
paths:
  /ubo.{_format}:
    post:
      consumes:
      - multipart/form-data
      description: '

        ### Information

        This is the second step of UBO statement submission.


        - 1 UBO = 1 shareholders with >25% of capital or voting rights)

        - The document uploaded can''t exceed 15MO.'
      operationId: post_Ubo
      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
      - description: 'Civility title of owner account : `1` : Mr, `2` : Mrs, `3` : Miss.'
        enum:
        - 1
        - 2
        - 3
        in: formData
        name: title
        type: integer
        required: true
        default: 1
      - description: First name of this UBO
        in: formData
        name: first_name
        required: true
        type: string
      - description: Last name of this UBO
        in: formData
        name: last_name
        required: true
        type: string
      - description: Street address
        in: formData
        name: address
        required: true
        type: string
      - description: The zip or postal code
        in: formData
        name: zip_code
        required: true
        type: string
      - description: City
        in: formData
        name: city
        required: true
        type: string
      - description: The country code. This two-letter country code complies with ISO 3166-1
        in: formData
        name: address_country
        required: true
        type: string
      - description: '`1` : CEO, `2` : COO, `3` : CFO, `4` : Shareholder, `5` : Administrator, `6` : Other, `7` : Company manager'
        enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        in: formData
        name: position
        required: true
        type: integer
        default: 1
      - description: If position is OTHER this parameter is needed
        in: formData
        name: position_detail
        required: false
        type: string
      - description: '`1` if this beneficial ower is a decision maker, `0` otherwise'
        enum:
        - 0
        - 1
        in: formData
        name: decision_maker
        type: integer
        required: true
        default: 0
      - description: '`1` if this beneficial ower is a politicaly exposed, `0` otherwise'
        enum:
        - 0
        - 1
        in: formData
        name: pep
        type: integer
        required: true
        default: 0
      - description: The identification number of the ID document (identification_file)
        in: formData
        name: id_number
        required: true
        type: string
      - description: Birth date of account owner. Ex. '1965-11-12' for November 12, 1965
        in: formData
        name: date_of_birth
        required: true
        type: string
        default: '1965-11-12'
      - description: Birth city of account owner.
        in: formData
        name: place_of_birth
        required: true
        type: string
      - description: Country of birth - This two-letter country code complies with ISO 3166-1
        in: formData
        name: country_of_birth
        required: true
        type: string
      - description: Nationality - This two-letter country code complies with ISO 3166-1
        in: formData
        name: nationality
        required: true
        type: string
      - description: Percentage of shares owned by this UBO (25% minimum)
        in: formData
        name: share
        required: true
        type: integer
        default: 25
      - description: Passport or ID card - File to upload (jpg, gif, png, pdf)
        in: formData
        name: id_document[file]
        required: true
        type: file
      - description: Back of file to upload (jpg, gif, png, pdf). Required for id cards in Belgium and Italy
        in: formData
        name: id_document_back[file]
        required: false
        type: file
      produces: []
      responses:
        '201':
          description: Success response
          schema:
            properties:
              code:
                description: Status code of the answer. 0 => Ubo successfully created
                format: int32
                type: integer
              message:
                description: Description of the answer.
                type: string
              ubo_statement_id:
                description: Id of the UBO statement.
                format: int32
                type: integer
              ubo_id:
                description: Id of this UBO.
                format: int32
                type: integer
        '400':
          description: Validation failed.
        '401':
          description: Authentication failed.
        '403':
          description: Forbidden.
        '500':
          description: Server Error.
      summary: Declare UBO
      tags:
      - ubo
      security:
      - basicAuth: []
  /ubo/{id}.{_format}:
    delete:
      consumes:
      - multipart/form-data
      description: '

        ### Information

        Delete an UBO'
      operationId: delete_ubo
      x-disableTryItOut: true
      parameters:
      - in: path
        name: _format
        required: true
        type: string
        enum:
        - json
        - xml
        default: json
      - in: path
        name: id
        description: Id of the UBO.
        required: true
        type: string
        default: 0
      - 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 : UBO has been deleted.'
          schema:
            properties:
              code:
                description: Status code of the answer. 0 => Ubo successfully deleted.
                format: int32
                type: integer
              message:
                description: Description of the answer.
                type: string
        '401':
          description: Authentication failed.
        '403':
          description: Forbidden.
      summary: Delete an UBO
      tags:
      - ubo
      security:
      - basicAuth: []
  /ubo/legal-representative.{_format}:
    post:
      consumes:
      - multipart/form-data
      description: "\n### Information\n  This is the second step of UBO statement submission, only in case the legal representative declared for the user space is also a UBO.\n\n- 1 UBO = 1 shareholders with >25% of capital or voting rights)\n- The document uploaded can't exceed 15MO.\n- Civility, address and position informations will be retrieved from the user space's professional informations.\n- ID Document (and its backside if it is needed) will be retrieved from the uploaded KYC (identification) documents for the user space. if they are already uploaded. Otherwise, they can be uploaded here and handled like a KYC, both identifying the user space and this UBO.\n- As there can only be one legal representive per user space, only one UBO/legal representative can be declared."
      operationId: post_Ubo-legal-representative
      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
      - description: '`1` if this beneficial ower is a decision maker, `0` otherwise'
        enum:
        - 0
        - 1
        in: formData
        name: decision_maker
        type: integer
        required: true
        default: 0
      - description: The identification number of the ID document (identification_file)
        in: formData
        name: id_number
        required: true
        type: string
      - description: '`1` if this beneficial ower is a politicaly exposed, `0` otherwise'
        enum:
        - 0
        - 1
        in: formData
        name: pep
        type: integer
        required: true
        default: 0
      - description: Birth date of account owner. Ex. '1965-11-12' for November 12, 1965
        in: formData
        name: date_of_birth
        required: true
        type: string
        default: '1965-11-12'
      - description: Birth city of account owner.
        in: formData
        name: place_of_birth
        required: true
        type: string
      - description: Country of birth - This two-letter country code complies with ISO 3166-1
        in: formData
        name: country_of_birth
        required: true
        type: string
      - description: Nationality - This two-letter country code complies with ISO 3166-1
        in: formData
        name: nationality
        required: true
        type: string
      - description: Percentage of shares owned by this UBO (25% minimum)
        in: formData
        name: share
        required: true
        type: integer
        default: 25
      - description: Passport or ID card - File to upload (jpg, gif, png, pdf)
        in: formData
        name: id_document[file]
        required: false
        type: file
      - description: Back of file to upload (jpg, gif, png, pdf). Required for id cards in Belgium and Italy
        in: formData
        name: id_document_back[file]
        required: false
        type: file
      produces: []
      responses:
        '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
              ubo_statement_id:
                description: Id of the UBO statement.
                format: int32
                type: integer
              ubo_id:
                description: Id of this UBO.
                format: int32
                type: integer
        '400':
          description: Validation failed.
        '401':
          description: Authentication failed.
        '403':
          description: Forbidden.
        '500':
          description: Server Error.
      summary: Declare UBO as legal representative
      tags:
      - ubo
      security:
      - basicAuth: []
  /ubo/ubo-statement.{_format}:
    delete:
      consumes:
      - multipart/form-data
      description: "\n### Information\n If you initiate an UBO statement with a wrong number of UBO, and if you don't send all the UBO, You can delete this UBO statement and start a new one. If an UBO statement has been submitted (status WAITING or UPDATED), you can't delete it."
      operationId: delete_ubo-statement
      x-disableTryItOut: true
      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 UBO statement has been deleted.
          schema:
            properties:
              code:
                description: Status code of the answer.
                format: int32
                type: integer
              message:
                description: Description of the answer.
                type: string
        '401':
          description: Authentication failed.
        '403':
          description: Forbidden.
      summary: Delete a UBO statement
      tags:
      - ubo
      security:
      - basicAuth: []
    get:
      consumes:
      - multipart/form-data
      description: "\n### Information\n  Get the list of all UBOs and documents for a user-space. If an UBO is refused, you should send us a new UBO with https://professional.hipay.com/api/ubo."
      operationId: get_ubo-statement
      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.
                format: int32
                type: integer
              message:
                description: Description of the answer.
                type: string
              user_space_id:
                description: User space id.
                type: integer
              ubo_statement_id:
                description: Id of the UBO statement.
                type: integer
              ubo_statement_status_code:
                description: '0: new, 1: waiting, 2: to check, 3: validated, 4: rejected, 5: updated.'
                type: integer
              ubo_statement_status:
                description: Text version of ubo_statement_status_code..
                type: string
              ubo:
                description: List of UBO.
                type: array
                items:
                  type: object
                  properties:
                    id:
                      description: ID of the UBO.
                      format: int32
                      type: integer
                    status_code:
                      description: '0: new, 1: waiting, 2: to check, 3: identified, 4: rejected, 5: deleted, 6: updated.'
                      type: integer
                    status_label:
                      description: Text version of ubo[status_code].
                      type: string
                    documents:
                      description: List of the UBO.
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            description: ID of the UBO Document
                            format: int32
                            type: integer
                          status_code:
                            description: '0: new, 1: waiting, 2: validated, 3: refused, 4: deleted, 11: to check.'
                            type: integer
                          status_label:
                            description: Text version of ubo[status_code].
                            type: string
                          type_code:
                            description: '1: Passport or ID card, 2: Proof of address.'
                            type: integer
                          type_label:
                            description: Text version of ubo[type_code].
                            type: string
                          status_refused_code:
                            description: "\tIf an UBO is refused (status_code = 3), this is the reason. -1: Without detail, 1: Invalid date, 2: Unreadable, 3: Missing information, 4: Other, 6: Invalid document type."
                            type: string
                          status_refused_label:
                            description: Text version of ubo[status_refused_code].
                            type: string
        '400':
          description: Validation failed.
        '401':
          description: Authentication failed.
      summary: Get a UBO statement. Get the list of all UBOs and documents for a user-space. If an UBO is refused, you should send us a new UBO with https://professional.hipay.com/api/ubo
      tags:
      - ubo
      security:
      - basicAuth: []
    post:
      consumes:
      - multipart/form-data
      description: "\n### Information\n  This is the first step of UBO statement submission. An UBO statement is a list of UBO (Ultimate Beneficial Owners).\n\n  - Be sure to have all the data before starting an UBO statement.\n  - 1 UBO = 1 shareholder with >25% of capital or voting rights)"
      operationId: post_ubo-statement
      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
      - description: 'How many UBO do you have to declare ? * `0` : no UBO to declare * maximum of `4` UBOs'
        in: formData
        name: nb_ubo
        required: true
        type: integer
        default: 0
      produces: []
      responses:
        '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
              ubo_statement_id:
                description: Id of the UBO statement.
                type: integer
        '400':
          description: Validation failed.
        '401':
          description: Authentication failed.
      summary: Create a UBO statement
      tags:
      - ubo
      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/