Adyen Balance Control API

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.
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
x-groups:
- General
tags:
- name: balanceTransfer
paths:
  /balanceTransfer:
    post:
      tags:
      - balanceTransfer
      summary: Adyen 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-groupName: General
      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.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Amount:
      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:
      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:
      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