Search

Are you looking for test card numbers?

Would you like to contact support?

Developer-resource icon

Account settings notifications

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

Account settings notifications are notification webhooks informing you of status changes related to your company account, merchant accounts, and stores.

For example, an account settings notification 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 notifications, what triggers them, and what they contain.

Set up account settings notifications

Setting up account settings notifications is very similar to setting up standard notifications, but there are a few differences:

  • By default, account settings notifications are not available in your Customer Area as a configurable notification type. You need to contact Support first.
  • The only additional setting that you can configure is for HMAC signing.

Proceed as follows:

  1. Expose an endpoint on your server where you want to receive account settings notifications.

  2. Contact our Support Team to enable account settings notifications at company level or at merchant level. This notification type will then appear in your Customer Area for further configuration.

  3. Configure account settings notifications as described in Set up notifications in your Customer Area. Note the following:

    • In your Customer Area, go to Account > Server communication, find Account Settings Notification, and select Add.

    • To set up HMAC signing of the notifications:

      1. Under Transport, in the Method field, select JSON as the notification format.
      2. Under Additional settings select Generate new HMAC key.
      3. Securely save the HMAC key in your system - you won't be able to restore it later.

  4. If you configured the notifications to be HMAC signed, set up a way to verify HMAC signatures, either using our libraries or using your own solution.

  5. If you selected SOAP as the notification format, implement the WSDL definition for account status notifications on your end. 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
  6. Implement a way to accept notifications properly. This includes verifying the HMAC signature and acknowledging every notification with an [accepted] response within 30 seconds.

When going live, you need to configure account settings notifications again in your live Customer Area. If you are using HMAC signed notifications, this includes generating and verifying a new HMAC key.

Exclude account fields from SOAP notifications

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.
When you exclude a field, no new notifications are generated for that field. However, if there are any pending unsent notifications that include it, they are processed normally and the excluded field is not removed before sending.

Events that trigger account settings notifications

Account settings notifications 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, yet there are some modification requests associated with it.
  • 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 notifications

Account settings notifications show information in the following fields:

Notification field Type Included by default Description
entityKey String -white_check_mark- The entity that was changed. This can be at company, merchant, store, or user level. Format:
  • Company.companyCode
  • MerchantAccount.merchantCode
  • Store.merchantCode.storeCode
  • username@accountKey
executingDate String -white_check_mark- The date and time when the change was applied. Format:
executingUserKey String -white_check_mark- Identifies the author of the change. Format:
  • username@accountKey

If a change is implemented by Adyen, the executingUserKey value is internal.

fieldName

String -white_check_mark- The account field that the change applies to:
  • accountStatus
  • blockPayout
  • merchantName
  • settlementCurrency
  • merchantCategoryCode
newValue String -white_check_mark- Returns the new or current value that replaced the old one.
oldValue String -x- Returns the original value, before it was changed.
pspReference String -white_check_mark- 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"
}

See also