spec release

json/BalancePlatformBalanceNotification-v1.json

@@ -0,0 +1,195 @@
+{
+  "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-03-20T15:36:19Z"
+  },
+  "tags" : [ {
+    "name" : "balancePlatform.balanceAccount.balance.updated"
+  }, {
+    "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",
+                      "creationDate" : "2025-01-19T13:37:38+02:00",
+                      "balancePlatform" : "YOUR_BALANCE_PLATFORM",
+                      "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"
+}

json/BalancePlatformConfigurationNotification-v1.json

@@ -1906,6 +1906,7 @@
                      "directDebitNotSupported",
                      "error",
                      "notEnoughBalance",
+                     "pending",
                      "pendingApproval",
                      "pendingExecution",
                      "refusedByCounterpartyBank",

json/BalancePlatformConfigurationNotification-v2.json

@@ -1972,6 +1972,7 @@
                      "directDebitNotSupported",
                      "error",
                      "notEnoughBalance",
+                     "pending",
                      "pendingApproval",
                      "pendingExecution",
                      "refusedByCounterpartyBank",

yaml/BalancePlatformBalanceNotification-v1.yaml

@@ -0,0 +1,166 @@
+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-03-20T15:36:19Z'
+tags:
+- name: balancePlatform.balanceAccount.balance.updated
+- 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
+                    creationDate: '2025-01-19T13:37:38+02:00'
+                    balancePlatform: YOUR_BALANCE_PLATFORM
+                    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

yaml/BalancePlatformConfigurationNotification-v1.yaml

@@ -1696,6 +1696,7 @@ components:
           - directDebitNotSupported
           - error
           - notEnoughBalance
+          - pending
           - pendingApproval
           - pendingExecution
           - refusedByCounterpartyBank

yaml/BalancePlatformConfigurationNotification-v2.yaml

@@ -1804,6 +1804,7 @@ components:
           - directDebitNotSupported
           - error
           - notEnoughBalance
+          - pending
           - pendingApproval
           - pendingExecution
           - refusedByCounterpartyBank