Account settings webhooks

Receive status updates for your company and merchant accounts and stores.

Account setting webhooks inform you of status changes related to your company account, merchant accounts, and stores.

For example, an account settings webhook event is sent when:

A merchant account or store is created, activated, deactivated, or closed.
The main settlement currency is changed.
A merchant account is assigned to a different merchant category code (MCC).

On this page we describe what you need to do to receive account settings webhooks, what triggers them, and what they contain.

Set up account settings webhooks

Expose an endpoint on your server where you want to receive account settings webhooks.
Implement 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.
Configure account settings webhooks as described in Set up webhooks in your Customer Area. Note the following:
- In your Customer Area, go to Developers > Webhooks, and select + Webhook. In the pop-up window, find Account settings details, and select Add.
- Under Server Configuration > Method, select JSON as the notification format.

When 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.

Exclude account fields from SOAP webhooks

If 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.
These are the test and live URL endpoints exposing the WSDL definitions:

Test account settings notification service	https://ca-test.adyen.com/ca/services/AccountSettingsNotification?wsdl
Live account settings notification service	https://ca-live.adyen.com/ca/services/AccountSettingsNotification?wsdl

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.

Events that trigger account settings webhooks

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:

Account field	Description
`accountStatus`	The status of the account or store: `PreActive`: The merchant account or store has been created, but not yet activated. `Active`: The merchant account or store has been activated. This means you can process payments over the merchant account or store. `Inactive`: The merchant account or store is currently not active. `InactiveWithModifications`: The merchant account or store is currently not active, but payment modifications such as refunds are still allowed. `Closed`: The merchant account or store has been closed. Closing a merchant account also closes any underlying stores. Merchant accounts can also have the following status: `TemporaryInactive`: The merchant account is temporarily not active.
`blockPayout`	The payable status of a payout. For example, `Payable` or `Blocked`
`merchantName`	The registered merchant name associated with the account. For example, Acme.
`settlementCurrency`	The primary currency used for settlements, in ISO currency code format.
`merchantCategoryCode`	The merchant category code (MCC) assigned to the merchant by the card issuer.

Structure of account settings webhooks

account settings webhooks show information in the following fields:

Notification field	Type	Description
`entityKey`	String	The entity that was changed. This can be at company, merchant, store, or user level. Format: `Company.companyCode` `MerchantAccount.merchantCode` `Store.merchantCode.storeCode` code>username@accountKey</code
`executingDate`	String	The date and time when the change was applied. Format: `YYYY_MM_DD_HH_MM_SS_sss_Z`
`executingUserKey`	String	Identifies the author of the change. Format: code>username@accountKey</code If a change is implemented by Adyen, the `executingUserKey` value is internal.
`fieldName`	String	The account field that the change applies to: `accountStatus` `blockPayout` `merchantName` `settlementCurrency` `merchantCategoryCode`
`newValue`	String	Returns the new or current value that replaced the old one.
`oldValue`	String	Returns the original value, before it was changed.
`pspReference`	String	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 NO_PSP_REF is added before the 16 characters. This value is globally unique; quote it when communicating with us about the change.

Examples

Account status change: store de-activated

{
    "entityKey": "Store.Acme_POS.Acme_Store2",
    "executingDate": "2020-04-21 18:01:19.263 CEST",
    "executingUserKey": "internal",
    "fieldName": "accountStatus",
    "newValue": "Inactive",
    "oldValue": "Active",
    "pspReference": "NO_PSP_REF_1587484879263067"
}

Payout status change

{
    "entityKey": "MerchantAccount.AcmeBulkSettlement",
    "executingDate": "2015-07-13 19:37:22.403 CEST",
    "executingUserKey": "internal",
    "fieldName": "blockPayout",
    "newValue": "Payable",
    "oldValue": "Blocked",
    "pspReference": "NO_PSP_REF_9914368090421650"
}

Merchant name change

{
    "entityKey": "MerchantAccount.SimoneFrancez",
    "executingDate": "2020-02-21 20:44:23.693 CET",
    "executingUserKey": "internal",
    "fieldName": "merchantName",
    "newValue": "Si",
    "oldValue": "Sim",
    "pspReference": "NO_PSP_REF_1582314263693431"
}

Settlement currency change

{
    "entityKey": "MerchantAccount.Acme",
    "executingDate": "2020-02-06 00:54:01.700 CET",
    "executingUserKey": "internal",
    "fieldName": "settlementCurrency",
    "newValue": "USD",
    "oldValue": "EUR",
    "pspReference": "NO_PSP_REF_1580946841700291"
}