HiPay withdrawal API

openapi: 3.2.0
info:
  version: '0.3'
  title: HiPay Marketplace Withdrawal API
  description: "\nThe implementation of HiPay Marketplace involves establishing connections between your marketplace platform and HiPay based on a simple integration through a set of APIs.\n\n## Account creation:\n\n  1) The agent checks the e-mail availability with the [Is-available API](#/user-account/post_user-account_is-available).\n\n  2) The agent creates a HiPay account for merchants using the [User-account API](#/user-account/post_user-account).\n\n  3) The agent sends us the account number and the identification/KYC information using the [Identification API](#/identification/post_Identification). HiPay validates the identification/KYC information within three days and sends the agent a notification confirming that the merchant is fully operational.\n\n## Bank account information submission:\n\nPlease note that it is possible to submit bank account information any time between account creation and withdrawal requests.\nTo register a HiPay account bank information, use the [Bank-info API.](#/bank-info/post_user-account)\n\n## Fund allocation:\n\nFund allocation is only possible if the merchant's account is validated by HiPay.\n\nAll the funds are held in escrow before being deposited on the technical account.\n\nThe [Transfer API](#/transfer/post_transfer]) is then used to allocate funds from the technical account to the merchant's account.\nThe [Transfer API](#/transfer/post_transfer]) allows transfer requests to be made on the agent’s behalf or on the behalf of a third party.\n\nThe technical account is therefore a monitoring tool that provides a clear view of fund allocation (fund remittance, refunds, chargebacks).\n\n## Withdrawal requests:\n\nWithdrawal is only possible if the merchant's account AND banking informations are validated by HiPay.\n\nOnce funds are allocated, there are two withdrawal possibilities:\n\n  - Whenever a transaction is made – please note that this option is not recommended by HiPay,\n  - Whenever a withdrawal request is made by the merchant – for example, every ten days, depending on the agent.\n\nWhen agents want to do a withdrawal, they need to check the merchant’s account balance with the [Balance API.](#/balance/get_user-account)\n\n  - In case of a zero balance, funds must be allocated with the [Transfer API](#/transfer/post_transfer]).\n  - If the balance equals the amount of the allocated funds, a fund withdrawal request can be made with the [Withdrawal API](#/withdrawal/post_withdrawal). (The Withdrawal API allows for a withdrawal request to transfer money to the merchant’s bank account and also to the partner’s bank account.)\n  - There must be a zero balance in the end.\n\n## Marketplace live testing:\n\nThis documentation describes the Marketplace API parameters and response fields and allows you to test the platform in real time.\n\n## Marketplace API base URLs:\n\n| Environment | Base URL |\n| --- | --- |\n| Test | https://test-professional.hipay.com/api/ |\n| Production | https://professional.hipay.com/api/ |\n\n## Authentication:\n\nAll requests to the HiPay Marketplace API require you to authenticate yourself using the HTTP *Basic Authentication* to convey your identity. Your API credentials can be found in [your Test HiPay Professional back office](https://test-merchant.hipaywallet.com/login). 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.\n\n`Authorization: Basic base64(\"<API login>:<API password>\")`\n"
servers:
- url: https://test-professional.hipay.com/api
tags:
- name: withdrawal
  description: Request a withdrawal from a HiPay account
paths:
  /withdrawal.{_format}:
    post:
      description: "\n### Information\nAllows you to request a withdrawal from a HiPay account and transfer the funds to the bank account linked to the account.\nOnce funds are allocated, there are two withdrawal possibilities.\n\n  - Whenever a transaction is made – please note that this option is not recommended by HiPay.\n\n  - Whenever a withdrawal request is made – for example, every ten days, depending on the agent.\n\nWhen agents want to do a withdrawal, they need to check the merchant’s account balance with the getBalance API.\n\n  - In case of a zero balance, funds can be allocated with the Transfer API.\n\n  - If the balance equals the amount of the allocated funds, a fund withdrawal request can be made with the Withdrawal API. (The Withdrawal API allows for withdrawal requests to transfer money to the merchant’s bank account and also to the partner’s bank account.)\n\n  - There must be a zero balance in the end.\n\nFor more information, please read the [HiPay Marketplace Withdrawal requests section](/marketplace/api-integration/cash-out#withdrawal-requests)"
      operationId: post_withdrawal
      x-disableTryItOut: true
      parameters:
      - in: path
        name: _format
        required: true
        schema:
          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
        schema:
          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
        schema:
          type: string
      responses:
        '200':
          description: Error response
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Status code of the answer. 13 => Withdrawal not created 26 => Withdrawal in progress
                    format: int32
                    type: integer
                    default: 13
                  message:
                    description: Description of the answer.
                    type: string
                    default: Withdrawal not created
        '201':
          description: Success response
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Status code of the answer. 0 => Withdrawal successfully created
                    format: int32
                    type: integer
                  message:
                    description: Description of the answer.
                    type: string
                  transaction_public_id:
                    description: Unique transaction ID.
                    type: string
                  label:
                    description: Label of the withdrawal.
                    type: string
                  amount:
                    description: Amount of the withdrawal in the account currency.
                    format: double
                    type: number
                  currency:
                    description: Currency of the withdrawal.
                    type: string
                  issuer_account:
                    description: Issuer's account ID.
                    type: string
        '400':
          description: Validation failed.
        '401':
          description: Authentication failed.
        40xx - Error code detail:
          description: 'See standard HTTP status code reason for 400x - Error code detail :


            | HTTP status code | Error code detail |

            | --- | --- |

            | `4002` | The userSpace is not activated. |

            | `4003` | The userSpace is being switched to pro or professionals info are not valid. |

            | `4004` | The user Space is not identified. |

            | `4005` | Bank info are not valid. |

            | `4006` | The userSpace state not normal. |

            | `4007` | The account is not activated. |

            | `4008` | The account is disabled. |

            | `4009` | The account is deleted. |

            | `4010` | The account is not main. |

            | `4012` | Bank country is blacklisted. |

            | `4013` | Withdrawal maximal limit reached. |

            | `4014` | Balance after the withdrawal will be inferior to minimal amount. |

            | `4015` | The declaration of your ultimate beneficial owners for your HiPay account has not been completed or has not been duly completed. |

            '
          content:
            application/json:
              schema:
                properties:
                  error_code_detail:
                    format: int32
                    type: integer
      summary: Request a withdrawal from a HiPay account
      tags:
      - withdrawal
      security:
      - basicAuth: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  format: float
                  default: '19.90'
                  description: Amount of the withdrawal in the account currency.
                label:
                  type: string
                  default: Custom label here
                  description: Label of the withdrawal in the account currency.
                merchant_unique_id:
                  type: string
                  default: ORDER_1973645854
                  description: Unique ID of the withdrawal sent by the merchant. HiPay will process only 1 withdrawal with this ID.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic