adyen-openapi/json/BalancePlatformBalanceNotification-v1.json

{
  "openapi" : "3.1.0",
  "info" : {
    "title" : "Balance webhook",
    "description" : "Adyen sends webhooks to inform you of balance changes in your balance platform.\n\nYou 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:\n\n- In your entire balance platform\n- In the balance accounts of specific account holders\n- 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.\n\nPossible 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"
}