{"title":"Account settings webhooks","category":"default","creationDate":1685115480,"content":"<p>Account setting <a href=\"\/development-resources\/webhooks\">webhooks<\/a> inform you of status changes related to your company account, merchant accounts, and stores.<\/p>\n<p>For example, an account settings webhook event is sent when:<\/p>\n<ul>\n<li>A merchant account or store is created, activated, deactivated, or closed.<\/li>\n<li>The main settlement currency is changed.<\/li>\n<li>A merchant account is assigned to a different merchant category code (MCC).<\/li>\n<\/ul>\n<p>On this page we describe what you need to do to receive account settings webhooks, what triggers them, and what they contain.<\/p>\n<h2>Set up account settings webhooks<\/h2>\n<ol>\n<li>\n<p><a href=\"\/development-resources\/webhooks\/configure-and-manage#expose-an-endpoint-on-your-server\">Expose an endpoint on your server<\/a> where you want to receive account settings webhooks.<\/p>\n<\/li>\n<li>\n<p>Implement a way to <a href=\"\/development-resources\/webhooks\/configure-and-manage#accept-webhooks\">accept webhooks<\/a>. This includes <a href=\"\/development-resources\/webhooks\/secure-webhooks\/verify-hmac-signatures\">verifying the HMAC signature<\/a> using our libraries or your own solution. You must acknowledge every notification with a <a href=\"https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/HTTP\/Status#successful_responses\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">successful HTTP status code<\/a>, for example <strong>202<\/strong>, within 10 seconds.<\/p>\n<\/li>\n<li>\n<p>Configure account settings webhooks as described in <a href=\"\/development-resources\/webhooks\/configure-and-manage#set-up-webhooks-in-your-customer-area\">Set up webhooks in your Customer Area<\/a>. Note the following:<\/p>\n<ul>\n<li>\n<p>In your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>, go to <strong>Developers<\/strong> &gt; <strong>Webhooks<\/strong>, and select <strong>+ Webhook<\/strong>. In the pop-up window, find <strong>Account settings details<\/strong>, and select <strong>Add<\/strong>.<\/p>\n<\/li>\n<li>\n<p>Under <strong>Server Configuration<\/strong> &gt; <strong>Method<\/strong>, select <em>JSON<\/em> as the notification format.<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n<p>When <a href=\"\/development-resources\/webhooks\/configure-and-manage#test-and-go-live\">going live<\/a>, you need to configure account settings webhooks again in your <a href=\"https:\/\/ca-live.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">live Customer Area<\/a>. If you are using HMAC signed webhooks, this includes generating and verifying a new HMAC key.<\/p>\n<h3 id=\"exclude-account-fields\">Exclude account fields from SOAP webhooks<\/h3>\n<p>If you selected <em>SOAP<\/em> as the notification format, you can customize the content by excluding one or more <a href=\"#accountfieldnames\">account field names<\/a> from your implementation of the WSDL definition. The corresponding information is then not included in the notification messages.<br \/>\nThese are the <strong>test<\/strong> and <strong>live<\/strong> URL endpoints exposing the WSDL definitions:<\/p>\n<table><tbody><tr><td><strong>Test account settings<\/strong><br>\n<strong>notification service<\/strong><\/td><td><p>https:\/\/ca-<strong>test<\/strong>.adyen.com\/ca\/services\/AccountSettingsNotification?wsdl<\/p><\/td><\/tr><tr><td><strong>Live account settings<\/strong><br>\n<strong>notification service<\/strong><\/td><td><p>https:\/\/ca-<strong>live<\/strong>.adyen.com\/ca\/services\/AccountSettingsNotification?wsdl<\/p><\/td><\/tr><\/tbody><\/table>\n<p>When you exclude a field, no new webhooks are generated for that field. However, if there are any pending unsent webhook events that include it, they are processed normally and the excluded field is not removed before sending.<\/p>\n<h2 id=\"accountfieldnames\">Events that trigger account settings webhooks<\/h2>\n<p>Account settings webhooks are sent when there is a change in one or more of the following account fields for your company account, merchant account, or store:<\/p>\n<table><thead><tr class=\"header\"><th>Account field<\/th><th>Description<\/th><\/tr><\/thead><tbody>\n<tr><td>\n<p><strong><code>accountStatus<\/code><\/strong><\/p>\n<\/td><td>The status of the account or store:<ul>\n  <li>\n<p><code>PreActive<\/code>: The merchant account or store has been created, but not yet activated.<\/p>\n<\/li>\n  <li>\n<p><code>Active<\/code>: The merchant account or store has been activated. This means you can process payments over the merchant account or store.<\/p>\n<\/li>\n  <li>\n<p><code>Inactive<\/code>: The merchant account or store is currently not active.<\/p>\n<\/li>\n  <li>\n<p><code>InactiveWithModifications<\/code>: The merchant account or store is currently not active, but payment modifications such as refunds are still allowed.<\/p>\n<\/li>\n  <li>\n<p><code>Closed<\/code>: The merchant account or store has been closed. Closing a merchant account also closes any underlying stores.<\/p>\n<\/li><\/ul>\n  Merchant accounts can also have the following status:<ul>\n  <li>\n<p><code>TemporaryInactive<\/code>: The merchant account is temporarily not active.<\/p>\n<\/li><\/ul><\/td><\/tr>\n<tr><td>\n<p><strong><code>blockPayout<\/code><\/strong><\/p>\n<\/td><td>\n<p>The payable status of a payout. For example, <code>Payable<\/code> or <code>Blocked<\/code><\/p>\n<\/td><\/tr>\n<tr><td>\n<p><strong><code>merchantName<\/code><\/strong><\/p>\n<\/td><td>\n<p>The registered merchant name associated with the account. For example, Acme.<\/p>\n<\/td><\/tr>\n<tr><td>\n<p><strong><code>settlementCurrency<\/code><\/strong><\/p>\n<\/td><td>\n<p>The primary currency used for settlements, in <a href=\"https:\/\/en.wikipedia.org\/wiki\/ISO_4217\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">ISO currency code<\/a> format.<\/p>\n<\/td><\/tr>\n<tr><td>\n<p><strong><code>merchantCategoryCode<\/code><\/strong><\/p>\n<\/td><td>\n<p>The <a href=\"https:\/\/en.wikipedia.org\/wiki\/Merchant_category_code\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">merchant category code (MCC)<\/a> assigned to the merchant by the card issuer.<\/p>\n<\/td><\/tr><\/tbody><\/table>\n<h2>Structure of account settings webhooks<\/h2>\n<p>account settings webhooks show information in the following fields:<\/p>\n<table><thead><tr class=\"header\"><th>Notification field<\/th><th>Type<\/th><th>Included by default<\/th><th>Description<\/th><\/tr><\/thead>\n<tbody>\n<tr><td>\n<p><strong><code>entityKey<\/code><\/strong><\/p>\n<\/td><td>\n<p>String<\/p>\n<\/td><td>\n<p><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/p>\n<\/td><td>\n<p>The entity that was changed. This can be at company, merchant, store, or user level. Format:<ul><li markdown=\"1\"><code>Company.companyCode<\/code><\/li><li markdown=\"1\"><code>MerchantAccount.merchantCode<\/code><\/li><li markdown=\"1\"><code>Store.merchantCode.storeCode<\/code><\/li><li markdown=\"1\"><a href=\"mailto:code&gt;username@accountKey&lt;\/code\" class=\"mailto\">code&gt;username@accountKey&lt;\/code<\/a><\/li><\/ul><\/p>\n<\/td><\/tr>\n<tr><td>\n<p><strong><code>executingDate<\/code><\/strong><\/p>\n<\/td><td>\n<p>String<\/p>\n<\/td><td>\n<p><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/p>\n<\/td><td>\n<p>The date and time when the change was applied. Format:<ul><li markdown=\"1\"><a href=\"http:\/\/www.w3.org\/TR\/NOTE-datetime\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">\n  <code>YYYY_MM_DD_HH_MM_SS_sss_Z<\/code>\n<\/a><\/li><\/ul><\/p>\n<\/td><\/tr>\n<tr><td>\n<p><strong><code>executingUserKey<\/code><\/strong><\/p>\n<\/td><td>\n<p>String<\/p>\n<\/td><td>\n<p><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/p>\n<\/td><td>\n<p>Identifies the author of the change. Format:<ul><li markdown=\"1\"><a href=\"mailto:code&gt;username@accountKey&lt;\/code\" class=\"mailto\">code&gt;username@accountKey&lt;\/code<\/a><\/li><\/ul><p>If a change is implemented by Adyen, the <code>executingUserKey<\/code> value is <span translate=\"no\"><b>internal<\/b>.<code><\/code><\/span><\/p><\/p>\n<\/td><\/tr>\n<tr><td>\n<p><strong><code>fieldName<\/code><\/strong><\/p>\n<\/td><td>\n<p>String<\/p>\n<\/td><td>\n<p><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/p>\n<\/td><td>The <a href=\"\/development-resources\/webhooks\/webhook-types\/account-settings-webhooks#accountfieldnames\">account field<\/a> that the change applies to:<br>\n<ul><li>\n<p><code>accountStatus<\/code><\/p>\n<\/li><li>\n<p><code>blockPayout<\/code><\/p>\n<\/li><li>\n<p><code>merchantName<\/code><\/p>\n<\/li><li>\n<p><code>settlementCurrency<\/code><\/p>\n<\/li><li>\n<p><code>merchantCategoryCode<\/code><\/p>\n<\/li><\/ul><\/td><\/tr>\n<tr><td>\n<p><strong><code>newValue<\/code><\/strong><\/p>\n<\/td><td>\n<p>String<\/p>\n<\/td><td>\n<p><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/p>\n<\/td><td>\n<p>Returns the new or current value that replaced the old one.<\/p>\n<\/td><\/tr>\n<tr><td>\n<p><strong><code>oldValue<\/code><\/strong><\/p>\n<\/td><td>\n<p>String<\/p>\n<\/td><td>\n<p><img title=\"-x-\" alt=\"-x-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/x.png\" \/><\/p>\n<\/td><td>\n<p>Returns the original value, before it was changed.<\/p>\n<\/td><\/tr>\n<tr><td>\n<p><strong><code>pspReference<\/code><\/strong><\/p>\n<\/td><td>\n<p>String<\/p>\n<\/td><td>\n<p><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/p>\n<\/td><td>\n<p>Adyen's 16-character unique reference associated with the change that triggered the notification. Normally a PSP reference is associated with a payment. In this case it isn't, so <span translate=\"no\"><b>NO_PSP_REF<\/b> is added before the 16 characters. This value is globally unique; quote it when communicating with us about the change.<\/span><\/p>\n<\/td><\/tr>\n<\/tbody><\/table>\n<h2>Examples<\/h2>\n<h4>Account status change: store de-activated<\/h4>\n<pre><code class=\"language-json\">{\n    \"entityKey\": \"Store.Acme_POS.Acme_Store2\",\n    \"executingDate\": \"2020-04-21 18:01:19.263 CEST\",\n    \"executingUserKey\": \"internal\",\n    \"fieldName\": \"accountStatus\",\n    \"newValue\": \"Inactive\",\n    \"oldValue\": \"Active\",\n    \"pspReference\": \"NO_PSP_REF_1587484879263067\"\n}<\/code><\/pre>\n<h4>Payout status change<\/h4>\n<pre><code class=\"language-json\">{\n    \"entityKey\": \"MerchantAccount.AcmeBulkSettlement\",\n    \"executingDate\": \"2015-07-13 19:37:22.403 CEST\",\n    \"executingUserKey\": \"internal\",\n    \"fieldName\": \"blockPayout\",\n    \"newValue\": \"Payable\",\n    \"oldValue\": \"Blocked\",\n    \"pspReference\": \"NO_PSP_REF_9914368090421650\"\n}<\/code><\/pre>\n<h4>Merchant name change<\/h4>\n<pre><code class=\"language-json\">{\n    \"entityKey\": \"MerchantAccount.SimoneFrancez\",\n    \"executingDate\": \"2020-02-21 20:44:23.693 CET\",\n    \"executingUserKey\": \"internal\",\n    \"fieldName\": \"merchantName\",\n    \"newValue\": \"Si\",\n    \"oldValue\": \"Sim\",\n    \"pspReference\": \"NO_PSP_REF_1582314263693431\"\n}<\/code><\/pre>\n<h4>Settlement currency change<\/h4>\n<pre><code class=\"language-json\">{\n    \"entityKey\": \"MerchantAccount.Acme\",\n    \"executingDate\": \"2020-02-06 00:54:01.700 CET\",\n    \"executingUserKey\": \"internal\",\n    \"fieldName\": \"settlementCurrency\",\n    \"newValue\": \"USD\",\n    \"oldValue\": \"EUR\",\n    \"pspReference\": \"NO_PSP_REF_1580946841700291\"\n}<\/code><\/pre>\n<h2>See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/development-resources\/webhooks\/secure-webhooks\/verify-hmac-signatures\"\n                        target=\"_self\"\n                        >\n                    Verify HMAC signatures\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/development-resources\/webhooks\/webhook-types\/account-settings-webhooks","articleFields":{"description":"Receive status updates for your company and merchant accounts and stores.","feedback_component":true,"type":"page","_expandable":{"operations":""},"status":"current","last_edit_on":"26-05-2023 17:38","filters_component":false},"algolia":{"url":"https:\/\/docs.adyen.com\/development-resources\/webhooks\/webhook-types\/account-settings-webhooks","title":"Account settings webhooks","content":"Account setting webhooks inform you of status changes related to your company account, merchant accounts, and stores.\nFor example, an account settings webhook event is sent when:\n\nA merchant account or store is created, activated, deactivated, or closed.\nThe main settlement currency is changed.\nA merchant account is assigned to a different merchant category code (MCC).\n\nOn this page we describe what you need to do to receive account settings webhooks, what triggers them, and what they contain.\nSet up account settings webhooks\n\n\nExpose an endpoint on your server where you want to receive account settings webhooks.\n\n\nImplement a way to accept webhooks. This includes verifying the HMAC signature using our libraries or your own solution. You must acknowledge every notification with a successful HTTP status code, for example 202, within 10 seconds.\n\n\nConfigure account settings webhooks as described in Set up webhooks in your Customer Area. Note the following:\n\n\nIn your Customer Area, go to Developers &gt; Webhooks, and select + Webhook. In the pop-up window, find Account settings details, and select Add.\n\n\nUnder Server Configuration &gt; Method, select JSON as the notification format.\n\n\n\n\nWhen going live, you need to configure account settings webhooks again in your live Customer Area. If you are using HMAC signed webhooks, this includes generating and verifying a new HMAC key.\nExclude account fields from SOAP webhooks\nIf you selected SOAP as the notification format, you can customize the content by excluding one or more account field names from your implementation of the WSDL definition. The corresponding information is then not included in the notification messages.\nThese are the test and live URL endpoints exposing the WSDL definitions:\nTest account settings\nnotification servicehttps:\/\/ca-test.adyen.com\/ca\/services\/AccountSettingsNotification?wsdlLive account settings\nnotification servicehttps:\/\/ca-live.adyen.com\/ca\/services\/AccountSettingsNotification?wsdl\nWhen you exclude a field, no new webhooks are generated for that field. However, if there are any pending unsent webhook events that include it, they are processed normally and the excluded field is not removed before sending.\nEvents that trigger account settings webhooks\nAccount settings webhooks are sent when there is a change in one or more of the following account fields for your company account, merchant account, or store:\nAccount fieldDescription\n\naccountStatus\nThe status of the account or store:\n  \nPreActive: The merchant account or store has been created, but not yet activated.\n\n  \nActive: The merchant account or store has been activated. This means you can process payments over the merchant account or store.\n\n  \nInactive: The merchant account or store is currently not active.\n\n  \nInactiveWithModifications: The merchant account or store is currently not active, but payment modifications such as refunds are still allowed.\n\n  \nClosed: The merchant account or store has been closed. Closing a merchant account also closes any underlying stores.\n\n  Merchant accounts can also have the following status:\n  \nTemporaryInactive: The merchant account is temporarily not active.\n\n\nblockPayout\n\nThe payable status of a payout. For example, Payable or Blocked\n\n\nmerchantName\n\nThe registered merchant name associated with the account. For example, Acme.\n\n\nsettlementCurrency\n\nThe primary currency used for settlements, in ISO currency code format.\n\n\nmerchantCategoryCode\n\nThe merchant category code (MCC) assigned to the merchant by the card issuer.\n\nStructure of account settings webhooks\naccount settings webhooks show information in the following fields:\nNotification fieldTypeIncluded by defaultDescription\n\n\nentityKey\n\nString\n\n\n\nThe entity that was changed. This can be at company, merchant, store, or user level. Format:Company.companyCodeMerchantAccount.merchantCodeStore.merchantCode.storeCodecode&gt;username@accountKey&lt;\/code\n\n\nexecutingDate\n\nString\n\n\n\nThe date and time when the change was applied. Format:\n  YYYY_MM_DD_HH_MM_SS_sss_Z\n\n\n\nexecutingUserKey\n\nString\n\n\n\nIdentifies the author of the change. Format:code&gt;username@accountKey&lt;\/codeIf a change is implemented by Adyen, the executingUserKey value is internal.\n\n\nfieldName\n\nString\n\n\nThe account field that the change applies to:\n\naccountStatus\n\nblockPayout\n\nmerchantName\n\nsettlementCurrency\n\nmerchantCategoryCode\n\n\nnewValue\n\nString\n\n\n\nReturns the new or current value that replaced the old one.\n\n\noldValue\n\nString\n\n\n\nReturns the original value, before it was changed.\n\n\npspReference\n\nString\n\n\n\nAdyen's 16-character unique reference associated with the change that triggered the notification. Normally a PSP reference is associated with a payment. In this case it isn't, so NO_PSP_REF is added before the 16 characters. This value is globally unique; quote it when communicating with us about the change.\n\n\nExamples\nAccount status change: store de-activated\n{\n    \"entityKey\": \"Store.Acme_POS.Acme_Store2\",\n    \"executingDate\": \"2020-04-21 18:01:19.263 CEST\",\n    \"executingUserKey\": \"internal\",\n    \"fieldName\": \"accountStatus\",\n    \"newValue\": \"Inactive\",\n    \"oldValue\": \"Active\",\n    \"pspReference\": \"NO_PSP_REF_1587484879263067\"\n}\nPayout status change\n{\n    \"entityKey\": \"MerchantAccount.AcmeBulkSettlement\",\n    \"executingDate\": \"2015-07-13 19:37:22.403 CEST\",\n    \"executingUserKey\": \"internal\",\n    \"fieldName\": \"blockPayout\",\n    \"newValue\": \"Payable\",\n    \"oldValue\": \"Blocked\",\n    \"pspReference\": \"NO_PSP_REF_9914368090421650\"\n}\nMerchant name change\n{\n    \"entityKey\": \"MerchantAccount.SimoneFrancez\",\n    \"executingDate\": \"2020-02-21 20:44:23.693 CET\",\n    \"executingUserKey\": \"internal\",\n    \"fieldName\": \"merchantName\",\n    \"newValue\": \"Si\",\n    \"oldValue\": \"Sim\",\n    \"pspReference\": \"NO_PSP_REF_1582314263693431\"\n}\nSettlement currency change\n{\n    \"entityKey\": \"MerchantAccount.Acme\",\n    \"executingDate\": \"2020-02-06 00:54:01.700 CET\",\n    \"executingUserKey\": \"internal\",\n    \"fieldName\": \"settlementCurrency\",\n    \"newValue\": \"USD\",\n    \"oldValue\": \"EUR\",\n    \"pspReference\": \"NO_PSP_REF_1580946841700291\"\n}\nSee also\n\n\n                    Verify HMAC signatures\n                \n","type":"page","locale":"en","boost":16,"hierarchy":{"lvl0":"Home","lvl1":"Development resources","lvl2":"Webhooks","lvl3":"Webhook structure and types","lvl4":"Account settings webhooks"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/development-resources","lvl2":"https:\/\/docs.adyen.com\/development-resources\/webhooks","lvl3":"https:\/\/docs.adyen.com\/development-resources\/webhooks\/webhook-types","lvl4":"\/development-resources\/webhooks\/webhook-types\/account-settings-webhooks"},"levels":5,"category":"Development Resources","category_color":"green","tags":["Account","settings","webhooks"]},"articleFiles":{"blockpayout-change.json":"<p alt=\"\">blockpayout-change.json<\/p>"}}