{"title":"Configure balance webhooks","category":"default","creationDate":1776961628,"content":"<p><span style=\"color: #0ABF53;\"><span style=\"font-size: 20px;\"><strong>Limited availability<\/strong><\/span><\/span><br \/>\nBalance webhooks are in pilot phase. Some of the processes and documentation may change as the feature evolves.<\/p>\n<hr \/>\n<p>Adyen can send you webhooks to notify you of balance changes in your balance platform. This can help you avoid <a href=\"\/pt\/platforms\/reconciliation-use-cases\/verify-balances\/#negative-balances\">negative balances<\/a> in your users' balance accounts.<\/p>\n<p>To receive these webhooks, you must subscribe to the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balance-webhooks\/latest\/overview\" class=\" external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Balance webhook<\/a> in your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>. Use the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/overview\" class=\" external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Configuration API<\/a> to set the conditions that a balance change must meet for Adyen to send a balance webhook:<\/p>\n<ul>\n<li>In your entire balance platform<\/li>\n<li>In the balance accounts of specific account holders<\/li>\n<li>In a specific balance account<\/li>\n<\/ul>\n<h2>Requirements<\/h2>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Requirement<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><strong><a href=\"\/pt\/development-resources\/api-credentials\/roles\/\">API credential roles<\/a><\/strong><\/td>\n<td style=\"text-align: left;\">Make sure that your  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/overview\" class=\" external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Configuration API<\/a> credential has the following role: <ul><li markdown=\"1\"><strong>Balance Platform BCL role<\/strong><\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong><a href=\"\/pt\/account\/user-roles\">Customer Area roles<\/a><\/strong><\/td>\n<td style=\"text-align: left;\">Make sure that you have at least one of the following roles: <ul><li markdown=\"1\"><strong>Merchant technical integrator<\/strong><\/li> <li markdown=\"1\"><strong>Merchant admin<\/strong><\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>Limitations<\/strong><\/td>\n<td style=\"text-align: left;\">You can create maximum 20 webhook settings per balance webhook.<br>In each webhook setting, you can configure maximum 20 sets of conditions in the <code>conditions<\/code> array.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>1. Subscribe to the balance webhook<\/h2>\n<p>To receive notifications about balance changes in you balance platform, you must subscribe to the <strong>Balance webhook<\/strong> in your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/p>\n<p>To subscribe to the balance webhook:<\/p>\n<ol>\n<li>\n<p>Log in to your company account in your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/p>\n<\/li>\n<li>\n<p>Go to <strong>Developers<\/strong> &gt; <strong>Webhooks<\/strong>.<\/p>\n<\/li>\n<li>\n<p>Select the <strong>Platforms<\/strong> tab.<\/p>\n<\/li>\n<li>\n<p>Select <i class=\"adl-icon-add\" role=\"img\" aria-label=\"add icon\"><\/i> <strong>Create new webhook<\/strong>.<br \/>\nIf you have multiple balance platforms, select the one where you want to configure the new webhook.<\/p>\n<\/li>\n<li>\n<p>Next to <strong>Balance Webhook<\/strong>, select <strong>Add<\/strong>.<\/p>\n<\/li>\n<li>\n<p>Under <strong>General<\/strong>, select the toggle to enable the webhook. You can also provide a description.<\/p>\n<\/li>\n<li>\n<p>Under <strong>Server configuration<\/strong>, enter your webhook server's public URL and select an encryption protocol.<\/p>\n<\/li>\n<li>\n<p>Under <strong>Security<\/strong>, configure the following:<\/p>\n<table>\n<thead>\n<tr>\n<th>Setting<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><strong>Basic authentication<\/strong><\/td>\n<td>Enter your server's username and password. We include these details in the header of the webhook to authenticate with your server.<\/td>\n<\/tr>\n<tr>\n<td><strong>HMAC Key<\/strong><\/td>\n<td>Select <strong>Generate a new key<\/strong> to create a hex-encoded HMAC key. You need this key to receive <a href=\"\/pt\/development-resources\/webhooks\/configure-and-manage\/#validate-hmac\">HMAC signed webhooks<\/a>. Copy and save the HMAC key securely in your system \u2014 you won't be able to copy it later.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/li>\n<li>\n<p>Select <strong>Save configuration<\/strong>.<\/p>\n<\/li>\n<li>\n<p>Take note of the ID of the webhook. You need it to configure the webhook settings with the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/overview\" class=\" external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Configuration API<\/a>.<\/p>\n<\/li>\n<\/ol>\n<h2>2. Configure the balance webhook<\/h2>\n<p>To set conditions when Adyen sends webhooks for balance changes in your balance platform, make a POST  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/balancePlatforms\/{id}\/webhooks\/{id}\/settings<\/a> request, specifying the balance platform ID and the balance webhook ID as path parameters.<\/p>\n<p>In the body of the request, include the following parameters:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-type\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">type<\/a><\/td>\n<td style=\"text-align: left;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The type of the webhook that you want to configure. Set this to <strong>balance<\/strong>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-target\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">target<\/a><\/td>\n<td style=\"text-align: left;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The type and ID of the resource about whose balance changes you want to get notified.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-target-type\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">target.type<\/a><\/td>\n<td style=\"text-align: left;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The resource for which you want to receive webhooks. Possible values:<ul><li markdown=\"1\"><strong>balancePlatform<\/strong>: receive webhooks for balance changes in your entire balance platform.<\/li><li markdown=\"1\"><strong>accountHolder<\/strong>: receive webhooks for balance changes for all balance accounts of a specific user.<\/li><li markdown=\"1\"><strong>balanceAccount<\/strong>: receive webhooks for balance changes in a specific balance account.<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-target-id\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">target.id<\/a><\/td>\n<td style=\"text-align: left;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The unique identifier of the <code>target.type<\/code>. This can be the ID of your balance platform, your account holder, or a balance account.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-currency\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">currency<\/a><\/td>\n<td style=\"text-align: left;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The currency of the balance for which you want to receive webhooks.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-status\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">status<\/a><\/td>\n<td style=\"text-align: left;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">Specifies the status of the webhook setting.<br>Possible values:<ul><li markdown=\"1\"><strong>active<\/strong>: You receive a balance webhook if any of the conditions in this setting are met.<\/li><li markdown=\"1\"><strong>inactive<\/strong>: You do not receive a balance webhook even if the conditions in this settings are met.<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-conditions\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">conditions<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The array of conditions a balance change must meet for Adyen to send the webhook. To trigger the webhook, the balance change must meet <em>all<\/em> the conditions you set.<br>If you don't specify any conditions, you will receive updates for <em>all<\/em> balance changes in the specified balance account(s).<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-conditions-balanceType\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">conditions.balanceType<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The type of balance for which you want to receive webhooks. Possible values:<ul><li markdown=\"1\"><strong>available<\/strong>: the balance available for use.<\/li><li markdown=\"1\"><strong>balance<\/strong>: the sum of transactions that have already been settled.<\/li><li markdown=\"1\"><strong>pending<\/strong>: the sum of transactions that will be settled in the future.<\/li><li markdown=\"1\"><strong>reserved<\/strong>: the balance currently held in reserve.<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-conditions-conditionType\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">conditions.conditionType<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">Possible values: <strong>greaterThan<\/strong>, <strong>greaterThanOrEqual<\/strong>, <strong>lessThan<\/strong>, <strong>lessThanOrEqual<\/strong>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"> <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/post\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings#request-conditions-value\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">conditions.value<\/a><\/td>\n<td style=\"text-align: left;\"><\/td>\n<td style=\"text-align: left;\">The value limit you set for the specified <code>balanceType<\/code> and <code>currency<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>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.<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Configure balance webhook setting'\" :id=\"'configure-balance-webhook'\" :code-data=\"[{&quot;language&quot;:&quot;bash&quot;,&quot;tabTitle&quot;:&quot;&quot;,&quot;content&quot;:&quot;curl https:\\\/\\\/balanceplatform-api-test.adyen.com\\\/bcl\\\/v2\\\/balancePlatforms \\\\\\n-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \\\\\\n-H 'content-type: application\\\/json' \\\\\\n-X POST \\\\\\n-d '{\\n    \\&quot;type\\&quot;: \\&quot;balance\\&quot;,\\n    \\&quot;target\\&quot; : {\\n        \\&quot;type\\&quot;: \\&quot;balanceAccount\\&quot;,\\n        \\&quot;id\\&quot;: \\&quot;BA00000000000000000LIABLE\\&quot;\\n    },\\n    \\&quot;currency\\&quot;: \\&quot;USD\\&quot;,\\n    \\&quot;status\\&quot;: \\&quot;active\\&quot;,\\n    \\&quot;conditions\\&quot;: [\\n        {\\n            \\&quot;balanceType\\&quot;: \\&quot;available\\&quot;,\\n            \\&quot;conditionType\\&quot;: \\&quot;lessThan\\&quot;,\\n            \\&quot;value\\&quot;: 500000\\n        }\\n    ]\\n}'&quot;}]\" :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>In the response, take note of the <code>id<\/code> 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.<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Balance webhook setting successfully configured'\" :id=\"'balance-webhooks-configured'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"id\\\": \\\"BWHS00000000000000000000000001\\\",\\n    \\\"type\\\": \\\"balance\\\",\\n    \\\"target\\\": {\\n        \\\"type\\\": \\\"balanceAccount\\\",\\n        \\\"id\\\": \\\"BA00000000000000000LIABLE\\\"\\n    },\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"status\\\": \\\"active\\\",\\n    \\\"conditions\\\": [\\n        {\\n            \\\"balanceType\\\": \\\"available\\\",\\n            \\\"conditionType\\\": \\\"lessThan\\\",\\n            \\\"value\\\": 500000\\n        }\\n    ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>When you start receiving webhooks, make sure you <a href=\"\/pt\/development-resources\/webhooks\/handle-webhook-events\">accept each one<\/a>.<\/p>\n<h2>Troubleshooting<\/h2>\n<p>You may receive errors when setting balance webhook conditions. The following examples show some of the most common issues and how to resolve them.<\/p>\n<div class=\"accordion-shortcode adl-accordion adl-accordion--max-height-transition\" data-expand=\"true\" data-ignore=\"anchorjs-link\">\n    \n    <div class=\"adl-accordion__item\" style=\"\">\n        <div tabindex=\"0\" role=\"item\" aria-expanded=\"false\" class=\"adl-accordion__header\">\n            <i class=\"adl-accordion__toggle adl-icon-chevron-down\"><\/i>\n            <div class=\"adl-accordion__title-wrapper\" data-accordion=\"#duplicated-conditions\">\n                                    <h4 class=\"adl-accordion__title\">Duplicated conditions<\/h4>\n                            <\/div>\n        <\/div>\n        <div role=\"region\" class=\"adl-accordion__content\">\n            \n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Error code 1047_002'\" :id=\"'duplicate-conditions'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"type\\\": \\\"https:\\\/\\\/docs.adyen.com\\\/errors\\\/bad-request\\\",\\n    \\\"errorCode\\\": \\\"1047_002\\\",\\n    \\\"title\\\": \\\"Invalid request content error\\\",\\n    \\\"detail\\\": \\\"Duplicated conditions provided.\\\",\\n    \\\"requestId\\\": \\\"e23ba7fa86620e34a5f2643703450b96\\\",\\n    \\\"status\\\": 400,\\n    \\\"invalidFields\\\": [\\n        {\\n            \\\"name\\\": \\\"conditions\\\",\\n            \\\"value\\\": \\\"[Condition[balanceType=available, conditionType=lessThan, value=500000], Condition[balanceType=available, conditionType=lessThan, value=500000]]\\\",\\n            \\\"message\\\": \\\"The conditions of the setting.\\\"\\n        }\\n    ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h4>Solution<\/h4>\n<p>Make a PATCH  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/patch\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings\/(settingId)\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/balancePlatforms\/{id}\/webhooks\/{id}\/settings\/{id}<\/a> request and change or delete one of the duplicated condition values.<\/p>\n\n        <\/div>\n    <\/div>\n<\/div>\n\n<div class=\"accordion-shortcode adl-accordion adl-accordion--max-height-transition\" data-expand=\"true\" data-ignore=\"anchorjs-link\">\n    \n    <div class=\"adl-accordion__item\" style=\"\">\n        <div tabindex=\"0\" role=\"item\" aria-expanded=\"false\" class=\"adl-accordion__header\">\n            <i class=\"adl-accordion__toggle adl-icon-chevron-down\"><\/i>\n            <div class=\"adl-accordion__title-wrapper\" data-accordion=\"#account-not-found\">\n                                    <h4 class=\"adl-accordion__title\">Account not found<\/h4>\n                            <\/div>\n        <\/div>\n        <div role=\"region\" class=\"adl-accordion__content\">\n            \n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Error code 1047_404'\" :id=\"'no-account'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"type\\\": \\\"https:\\\/\\\/docs.adyen.com\\\/errors\\\/not-found\\\",\\n  \\\"errorCode\\\": \\\"1047_404\\\",\\n  \\\"title\\\": \\\"Not found\\\",\\n  \\\"detail\\\": \\\"Account not found.\\\",\\n  \\\"requestId\\\": \\\"7830854fd16bac465dd2f06545455fa8\\\",\\n  \\\"status\\\": 404,\\n  \\\"invalidFields\\\": [\\n    {\\n      \\\"name\\\": \\\"type\\\",\\n      \\\"value\\\": \\\"BalancePlatform\\\",\\n      \\\"message\\\": \\\"The target account type.\\\"\\n    },\\n    {\\n      \\\"name\\\": \\\"id\\\",\\n      \\\"value\\\": \\\"AdyenBan\\\",\\n      \\\"message\\\": \\\"The target account id.\\\"\\n    }\\n  ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h4>Solution<\/h4>\n<ol>\n<li>Check the ID of the target balance platform, account holder, or balance account included in the response.<\/li>\n<li>Resend the POST  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/patch\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings\/(settingId)\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/balancePlatforms\/{id}\/webhooks\/{id}\/settings\/{id}<\/a> request with the correct ID.<\/li>\n<\/ol>\n\n        <\/div>\n    <\/div>\n<\/div>\n\n<div class=\"accordion-shortcode adl-accordion adl-accordion--max-height-transition\" data-expand=\"true\" data-ignore=\"anchorjs-link\">\n    \n    <div class=\"adl-accordion__item\" style=\"\">\n        <div tabindex=\"0\" role=\"item\" aria-expanded=\"false\" class=\"adl-accordion__header\">\n            <i class=\"adl-accordion__toggle adl-icon-chevron-down\"><\/i>\n            <div class=\"adl-accordion__title-wrapper\" data-accordion=\"#invalid-currency-provided\">\n                                    <h4 class=\"adl-accordion__title\">Invalid currency provided<\/h4>\n                            <\/div>\n        <\/div>\n        <div role=\"region\" class=\"adl-accordion__content\">\n            \n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Error code 1047_001'\" :id=\"'invalid-currency'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"type\\\": \\\"https:\\\/\\\/docs.adyen.com\\\/errors\\\/validation\\\",\\n  \\\"errorCode\\\": \\\"1047_001\\\",\\n  \\\"title\\\": \\\"Validation error\\\",\\n  \\\"detail\\\": \\\"Invalid currency provided.\\\",\\n  \\\"requestId\\\": \\\"6f5f850c80706cf8e47f4094b80b6e48\\\",\\n  \\\"status\\\": 400,\\n  \\\"invalidFields\\\": [\\n    {\\n      \\\"name\\\": \\\"currency\\\",\\n      \\\"value\\\": \\\"EU\\\",\\n      \\\"message\\\": \\\"The currency of the webhook setting.\\\"\\n    }\\n  ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h4>Solution<\/h4>\n<ol>\n<li>Check the currency code in the response.<\/li>\n<li>Resend the POST  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/balanceplatform\/latest\/patch\/balancePlatforms\/(balancePlatformId)\/webhooks\/(webhookId)\/settings\/(settingId)\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/balancePlatforms\/{id}\/webhooks\/{id}\/settings\/{id}<\/a> request with the correct <a href=\"https:\/\/en.wikipedia.org\/wiki\/ISO_4217\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">3-letter ISO currency code<\/a>.<\/li>\n<\/ol>\n\n        <\/div>\n    <\/div>\n<\/div>\n\n<h2>See also<\/h2>\n<div class=\"next-steps\" id=\"next-steps\" >\n<a href=\"\/platforms\/balance-updates\/use-cases\" class=\"next-steps__step\" style=\"width:29%;\" target=\"_self\"><div class=\"next-steps__title\">Use cases<\/div><p class=\"next-steps__body\"><p>See examples of how you can configure the balance webhook for specific use cases.<\/p><\/p><\/a><a href=\"\/platforms\/balance-updates\/manage-balance-webhook\" class=\"next-steps__step\" style=\"width:29%;\" target=\"_self\"><div class=\"next-steps__title\">Manage balance webhook settings<\/div><p class=\"next-steps__body\"><p>Learn how you can update or delete your balance webhook settings.<\/p><\/p><\/a><a href=\"\/platforms\/top-up-balance-account\" class=\"next-steps__step\" style=\"width:29%;\" target=\"_self\"><div class=\"next-steps__title\">Top up balance accounts<\/div><p class=\"next-steps__body\"><p>Set up automatic or on-demand direct debits from your user's bank account.<\/p><\/p><\/a><\/div>\n","url":"https:\/\/docs.adyen.com\/pt\/platforms\/balance-updates\/configure-balance-webhook","articleFields":{"description":"Learn how you can configure and receive automatic notifications about the balance changes in your balance platform.","cache_enable":false,"parameters":{"directoryPath":"\/platforms","model":"platform"}},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/platforms\/balance-updates\/configure-balance-webhook","title":"Configure balance webhooks","content":"Limited availability\nBalance webhooks are in pilot phase. Some of the processes and documentation may change as the feature evolves.\n\nAdyen 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.\nTo 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:\n\nIn your entire balance platform\nIn the balance accounts of specific account holders\nIn a specific balance account\n\nRequirements\n\n\n\nRequirement\nDescription\n\n\n\n\nAPI credential roles\nMake sure that your  Configuration API credential has the following role: Balance Platform BCL role\n\n\nCustomer Area roles\nMake sure that you have at least one of the following roles: Merchant technical integrator Merchant admin\n\n\nLimitations\nYou can create maximum 20 webhook settings per balance webhook.In each webhook setting, you can configure maximum 20 sets of conditions in the conditions array.\n\n\n\n1. Subscribe to the balance webhook\nTo receive notifications about balance changes in you balance platform, you must subscribe to the Balance webhook in your Customer Area.\nTo subscribe to the balance webhook:\n\n\nLog in to your company account in your Customer Area.\n\n\nGo to Developers &gt; Webhooks.\n\n\nSelect the Platforms tab.\n\n\nSelect  Create new webhook.\nIf you have multiple balance platforms, select the one where you want to configure the new webhook.\n\n\nNext to Balance Webhook, select Add.\n\n\nUnder General, select the toggle to enable the webhook. You can also provide a description.\n\n\nUnder Server configuration, enter your webhook server's public URL and select an encryption protocol.\n\n\nUnder Security, configure the following:\n\n\n\nSetting\nDescription\n\n\n\n\nBasic authentication\nEnter your server's username and password. We include these details in the header of the webhook to authenticate with your server.\n\n\nHMAC Key\nSelect 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 \u2014 you won't be able to copy it later.\n\n\n\n\n\nSelect Save configuration.\n\n\nTake note of the ID of the webhook. You need it to configure the webhook settings with the  Configuration API.\n\n\n2. Configure the balance webhook\nTo 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.\nIn the body of the request, include the following parameters:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\n type\n\nThe type of the webhook that you want to configure. Set this to balance.\n\n\n target\n\nThe type and ID of the resource about whose balance changes you want to get notified.\n\n\n target.type\n\nThe 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.\n\n\n target.id\n\nThe unique identifier of the target.type. This can be the ID of your balance platform, your account holder, or a balance account.\n\n\n currency\n\nThe currency of the balance for which you want to receive webhooks.\n\n\n status\n\nSpecifies 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.\n\n\n conditions\n\nThe 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).\n\n\n conditions.balanceType\n\nThe 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.\n\n\n conditions.conditionType\n\nPossible values: greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual.\n\n\n conditions.value\n\nThe value limit you set for the specified balanceType and currency.\n\n\n\nThe 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.\n\n    \n\nIn 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.\n\n    \n\nWhen you start receiving webhooks, make sure you accept each one.\nTroubleshooting\nYou may receive errors when setting balance webhook conditions. The following examples show some of the most common issues and how to resolve them.\n\n    \n    \n        \n            \n            \n                                    Duplicated conditions\n                            \n        \n        \n            \n\n    \n\nSolution\nMake a PATCH  \/balancePlatforms\/{id}\/webhooks\/{id}\/settings\/{id} request and change or delete one of the duplicated condition values.\n\n        \n    \n\n\n\n    \n    \n        \n            \n            \n                                    Account not found\n                            \n        \n        \n            \n\n    \n\nSolution\n\nCheck the ID of the target balance platform, account holder, or balance account included in the response.\nResend the POST  \/balancePlatforms\/{id}\/webhooks\/{id}\/settings\/{id} request with the correct ID.\n\n\n        \n    \n\n\n\n    \n    \n        \n            \n            \n                                    Invalid currency provided\n                            \n        \n        \n            \n\n    \n\nSolution\n\nCheck the currency code in the response.\nResend the POST  \/balancePlatforms\/{id}\/webhooks\/{id}\/settings\/{id} request with the correct 3-letter ISO currency code.\n\n\n        \n    \n\n\nSee also\n\nUse casesSee examples of how you can configure the balance webhook for specific use cases.Manage balance webhook settingsLearn how you can update or delete your balance webhook settings.Top up balance accountsSet up automatic or on-demand direct debits from your user's bank account.\n","type":"page","locale":"pt","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Platforms","lvl2":"Track balance updates","lvl3":"Configure balance webhooks"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/platforms","lvl2":"https:\/\/docs.adyen.com\/pt\/platforms\/balance-updates","lvl3":"\/pt\/platforms\/balance-updates\/configure-balance-webhook"},"levels":4,"category":"Platforms","category_color":"green","tags":["Configure","balance","webhooks"]}}