Configure balance webhooks

Adyen can send you webhooks to notify you of balance changes in your balance platform. This can help you avoid negative balances in your users' balance accounts.

To receive these webhooks, you must subscribe to the Balance webhook in your Customer Area. Use the Configuration API 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

Requirements

1. Subscribe to the balance webhook

To receive notifications about balance changes in you balance platform, you must subscribe to the Balance webhook in your Customer Area.

To subscribe to the balance webhook:

1. Log in to your company account in your Customer Area.

2. Go to Developers > Webhooks.

3. Select the Platforms tab.

4. Select Create new webhook.
   If you have multiple balance platforms, select the one where you want to configure the new webhook.

5. Next to Balance Webhook, select Add.

6. Under General, select the toggle to enable the webhook. You can also provide a description.

7. Under Server configuration, enter your webhook server's public URL and select an encryption protocol.

8. Under Security, configure the following:

   Setting	Description
   Basic authentication	Enter your server's username and password. We include these details in the header of the webhook to authenticate with your server.
   HMAC Key	Select Generate a new key to create a hex-encoded HMAC key. You need this key to receive HMAC signed webhooks. Copy and save the HMAC key securely in your system — you won't be able to copy it later.

9. Select Save configuration.

10. Take note of the ID of the webhook. You need it to configure the webhook settings with the Configuration API.

2. Configure the balance webhook

To set conditions when Adyen sends webhooks for balance changes in your balance platform, make a POST /balancePlatforms/{id}/webhooks/{id}/settings request, specifying the balance platform ID and the balance webhook ID as path parameters.

In the body of the request, include the following parameters:

Parameter	Required	Description
type		The type of the webhook that you want to configure. Set this to balance.
target		The type and ID of the resource about whose balance changes you want to get notified.
target.type		The resource for which you want to receive webhooks. Possible values: balancePlatform: receive webhooks for balance changes in your entire balance platform. accountHolder: receive webhooks for balance changes for all balance accounts of a specific user. balanceAccount: receive webhooks for balance changes in a specific balance account.
target.id		The unique identifier of the target.type. This can be the ID of your balance platform, your account holder, or a balance account.
currency		The currency of the balance for which you want to receive webhooks.
status		Specifies the status of the webhook setting. Possible values: active: You receive a balance webhook if any of the conditions in this setting are met. inactive: You do not receive a balance webhook even if the conditions in this settings are met.
conditions		The array of conditions a balance change must meet for Adyen to send the webhook. To trigger the webhook, the balance change must meet all the conditions you set. If you don't specify any conditions, you will receive updates for all balance changes in the specified balance account(s).
conditions.balanceType		The type of balance for which you want to receive webhooks. Possible values: available: the balance available for use. balance: the sum of transactions that have already been settled. pending: the sum of transactions that will be settled in the future. reserved: the balance currently held in reserve.
conditions.conditionType		Possible values: greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual.
conditions.value		The value limit you set for the specified balanceType and currency.

The following example shows how you can set a balance condition for the balance webhook to get notified when the available balance in your liable balance account drops below USD 5000.

curl https://balanceplatform-api-test.adyen.com/balancePlatforms/YourBalancePlatform/webhooks/WBHK00000000000000000000000001/settings \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
    "type": "balance",
    "target" : {
        "type": "balanceAccount",
        "id": "BA00000000000000000LIABLE"
    },
    "currency": "USD",
    "status": "active",
    "conditions": [
        {
            "balanceType": "available",
            "conditionType": "lessThan",
            "value": 500000
        }
    ]
}'

In the response, take note of the id of the balance webhook setting. You will need it later if you want to view, modify, or delete the webhook configuration settings, or want to match the webhook event you receive with the setting you're interested in.

{
    "id": "BWHS00000000000000000000000001",
    "type": "balance",
    "target": {
        "type": "balanceAccount",
        "id": "BA00000000000000000LIABLE"
    },
    "currency": "USD",
    "status": "active",
    "conditions": [
        {
            "balanceType": "available",
            "conditionType": "lessThan",
            "value": 500000
        }
    ]
}

When you start receiving webhooks, make sure you accept each one.

Troubleshooting

You may receive errors when setting balance webhook conditions. The following examples show some of the most common issues and how to resolve them.

{
    "type": "https://docs.adyen.com/errors/bad-request",
    "errorCode": "1047_002",
    "title": "Invalid request content error",
    "detail": "Duplicated conditions provided.",
    "requestId": "e23ba7fa86620e34a5f2643703450b96",
    "status": 400,
    "invalidFields": [
        {
            "name": "conditions",
            "value": "[Condition[balanceType=available, conditionType=lessThan, value=500000], Condition[balanceType=available, conditionType=lessThan, value=500000]]",
            "message": "The conditions of the setting."
        }
    ]
}

{
  "type": "https://docs.adyen.com/errors/not-found",
  "errorCode": "1047_404",
  "title": "Not found",
  "detail": "Account not found.",
  "requestId": "7830854fd16bac465dd2f06545455fa8",
  "status": 404,
  "invalidFields": [
    {
      "name": "type",
      "value": "BalancePlatform",
      "message": "The target account type."
    },
    {
      "name": "id",
      "value": "AdyenBan",
      "message": "The target account id."
    }
  ]
}

{
  "type": "https://docs.adyen.com/errors/validation",
  "errorCode": "1047_001",
  "title": "Validation error",
  "detail": "Invalid currency provided.",
  "requestId": "6f5f850c80706cf8e47f4094b80b6e48",
  "status": 400,
  "invalidFields": [
    {
      "name": "currency",
      "value": "EU",
      "message": "The currency of the webhook setting."
    }
  ]
}

See also