adyen-openapi/yaml/BalancePlatformBalanceNotification-v1.yaml

openapi: 3.1.0
info:
  title: Balance webhook
  description: 'Adyen sends webhooks to inform you of balance changes in your balance
    platform.


    You can use the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/(id)/webhooks/(id)/settings)
    to set the conditions that a balance change must meet for Adyen to send a balance
    webhook:


    - In your entire balance platform

    - In the balance accounts of specific account holders

    - In a specific balance account'
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
  version: '1'
  x-timestamp: '2025-05-15T18:31:46Z'
tags:
- name: Balances
webhooks:
  balanceAccount.balance.updated:
    post:
      tags:
      - Balances
      summary: Balance updated
      description: Adyen sends this webhook when the specified balance type reaches
        or drops below the threshold you configured.
      operationId: post-balanceAccount.balance.updated
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BalanceAccountBalanceNotificationRequest'
            examples:
              balance-updated:
                summary: Balance changed
                description: Balance changed
                value:
                  data:
                    settingIds:
                    - BWHS00000000000000000000000001
                    - BWHS00000000000000000000000002
                    creationDate: '2025-01-19T13:37:38+02:00'
                    balancePlatform: YOUR_BALANCE_PLATFORM
                    balanceAccountId: BA00000000000000000000000001
                    currency: USD
                    balances:
                      available: 499900
                      pending: 350000
                      reserved: 120000
                      balance: 470000
                  environment: test
                  type: balancePlatform.balanceAccount.balance.updated
      responses:
        '200':
          description: OK - the request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancePlatformNotificationResponse'
              examples:
                balance-updated:
                  summary: Acknowledge webhook
                  description: Acknowledge webhook
                  value:
                    notificationResponse: '[accepted]'
      x-sortIndex: 0
components:
  schemas:
    BalancePlatformNotificationResponse:
      type: object
      properties:
        notificationResponse:
          type: string
          description: Respond with any **2xx** HTTP status code to [accept the webhook](https://docs.adyen.com/development-resources/webhooks#accept-notifications).
    BalanceAccountBalanceNotificationRequest:
      required:
      - data
      - environment
      - type
      type: object
      properties:
        data:
          description: Contains event details.
          $ref: '#/components/schemas/BalanceNotificationData'
        environment:
          type: string
          description: 'The environment from which the webhook originated.


            Possible values: **test**, **live**.'
        timestamp:
          type: string
          description: When the event was queued.
          format: date-time
        type:
          type: string
          description: Type of webhook.
          enum:
          - balancePlatform.balanceAccount.balance.updated
    BalanceNotificationData:
      required:
      - balanceAccountId
      - balances
      - currency
      - settingIds
      type: object
      properties:
        balanceAccountId:
          type: string
          description: The unique identifier of the balance account.
        balancePlatform:
          type: string
          description: The unique identifier of the balance platform.
        balances:
          description: The list balance types.
          $ref: '#/components/schemas/Balances'
        creationDate:
          type: string
          description: The date and time when the event was triggered, in ISO 8601
            extended format. For example, **2020-12-18T10:15:30+01:00**.
          format: date-time
        currency:
          type: string
          description: TThe three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
        id:
          type: string
          description: The ID of the resource.
          readOnly: true
        settingIds:
          type: array
          description: The unique identifier of the balance webhook setting.
          items:
            type: string
    Balances:
      type: object
      properties:
        available:
          type: integer
          description: The balance that is available for use.
          format: int64
        balance:
          type: integer
          description: The sum of transactions that have already been settled.
          format: int64
        pending:
          type: integer
          description: The sum of transactions that will be settled in the future.
          format: int64
        reserved:
          type: integer
          description: The balance currently held in reserve.
          format: int64
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    BasicAuth:
      type: http
      scheme: basic
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base