openapi: 3.1.0
servers:
- url: https://pal-test.adyen.com/pal/servlet/BalanceControl/v1
info:
  version: '1'
  x-publicVersion: true
  title: Adyen Balance Control API
  description: 'The Balance Control API lets you transfer funds between merchant accounts
    that belong to the same legal entity and are under the same company account.


    ## Authentication

    To connect to the Balance Control API, you must authenticate your requests with
    an [API key or basic auth username and password](https://docs.adyen.com/development-resources/api-authentication).
    To learn how you can generate these, see [API credentials](https://docs.adyen.com/development-resources/api-credentials).Here
    is an example of authenticating a request with an API key:


    ```

    curl

    -H "X-API-Key: Your_API_key" \

    -H "Content-Type: application/json" \

    ...

    ```

    Note that when going live, you need to generate API credentials to access the
    [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).


    ## Versioning

    The Balance Control API supports [versioning](https://docs.adyen.com/development-resources/versioning)
    using a version suffix in the endpoint URL. This suffix has the following format:
    "vXX", where XX is the version number.


    For example:


    ```

    https://pal-test.adyen.com/pal/servlet/BalanceControl/v1/balanceTransfer

    ```

    '
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
tags:
- name: General
paths:
  /balanceTransfer:
    post:
      tags:
      - General
      summary: Start a balance transfer
      description: 'Starts a balance transfer request between merchant accounts. The
        following conditions must be met before you can successfully transfer balances:


        * The source and destination merchant accounts must be under the same company
        account and legal entity.


        * The source merchant account must have sufficient funds.


        * The source and destination merchant accounts must have at least one common
        processing currency.


        When sending multiple API requests with the same source and destination merchant
        accounts, send the requests sequentially and *not* in parallel. Some requests
        may not be processed if the requests are sent in parallel.

        '
      operationId: post-balanceTransfer
      x-sortIndex: 0
      x-methodName: balanceTransfer
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              post-balance-transfer:
                $ref: '#/components/examples/post-balanceTransfer-post-balance-transfer'
            schema:
              $ref: '#/components/schemas/BalanceTransferRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                post-balance-transfer:
                  $ref: '#/components/examples/post-balanceTransfer-post-balance-transfer-200'
              schema:
                $ref: '#/components/schemas/BalanceTransferResponse'
          description: OK - the request has succeeded.
components:
  schemas:
    Amount:
      additionalProperties: false
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          format: int64
          type: integer
      required:
      - value
      - currency
      type: object
    BalanceTransferRequest:
      additionalProperties: false
      properties:
        amount:
          description: The amount of the transfer in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          $ref: '#/components/schemas/Amount'
        description:
          description: A human-readable description for the transfer. You can use
            alphanumeric characters and hyphens. We recommend sending a maximum of
            140 characters, otherwise the description may be truncated.
          maxLength: 140
          type: string
        fromMerchant:
          description: The unique identifier of the source merchant account from which
            funds are deducted.
          type: string
        reference:
          description: 'A reference for the balance transfer. If you don''t provide
            this in the request, Adyen generates a unique reference.

            Maximum length: 80 characters.'
          maxLength: 80
          type: string
        toMerchant:
          description: The unique identifier of the destination merchant account from
            which funds are transferred.
          type: string
        type:
          description: 'The type of balance transfer. Possible values: **tax**, **fee**,
            **terminalSale**, **credit**, **debit**, and **adjustment**.'
          enum:
          - tax
          - fee
          - terminalSale
          - credit
          - debit
          - adjustment
          type: string
      required:
      - amount
      - fromMerchant
      - toMerchant
      - type
      type: object
    BalanceTransferResponse:
      additionalProperties: false
      properties:
        amount:
          description: The amount of the transfer in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          $ref: '#/components/schemas/Amount'
        createdAt:
          description: The date when the balance transfer was requested.
          format: date-time
          type: string
        description:
          description: A human-readable description for the transfer. You can use
            alphanumeric characters and hyphens. We recommend sending a maximum of
            140 characters, otherwise the description may be truncated.
          maxLength: 140
          type: string
        fromMerchant:
          description: The unique identifier of the source merchant account from which
            funds are deducted.
          type: string
        pspReference:
          description: Adyen's 16-character string reference associated with the balance
            transfer.
          type: string
        reference:
          description: 'A reference for the balance transfer. If you don''t provide
            this in the request, Adyen generates a unique reference.

            Maximum length: 80 characters.'
          maxLength: 80
          type: string
        status:
          description: 'The status of the balance transfer. Possible values: **transferred**,
            **failed**, **error**, and **notEnoughBalance**.'
          enum:
          - error
          - failed
          - notEnoughBalance
          - transferred
          type: string
        toMerchant:
          description: The unique identifier of the destination merchant account from
            which funds are transferred.
          type: string
        type:
          description: 'The type of balance transfer. Possible values: **tax**, **fee**,
            **terminalSale**, **credit**, **debit**, and **adjustment**.'
          enum:
          - tax
          - fee
          - terminalSale
          - credit
          - debit
          - adjustment
          type: string
      required:
      - amount
      - fromMerchant
      - toMerchant
      - type
      - pspReference
      - status
      - createdAt
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
  examples:
    post-balanceTransfer-post-balance-transfer:
      summary: Transfer balances between merchant accounts
      description: Example request for transferring balance between merchant accounts
      value:
        amount:
          value: 50000
          currency: EUR
        description: Your description for the transfer
        fromMerchant: MerchantAccount_NL
        toMerchant: MerchantAccount_DE
        type: debit
    post-balanceTransfer-post-balance-transfer-200:
      summary: Transfer balances between merchant accounts
      description: Example response for transferring balance between merchant accounts
      value:
        amount:
          value: 50000
          currency: EUR
        createdAt: '2022-01-24T14:59:11+01:00'
        description: Your description for the transfer
        fromMerchant: MerchantAccount_NL
        toMerchant: MerchantAccount_DE
        type: debit
        reference: Unique reference for the transfer
        pspReference: '8816080397613514'
        status: transferred