---
title: "Migrating to v5"
description: "Learn about the changes in Adyen for Platforms API v5."
url: "https://docs.adyen.com/classic-platforms/migrating-to-v5"
source_url: "https://docs.adyen.com/classic-platforms/migrating-to-v5.md"
canonical: "https://docs.adyen.com/classic-platforms/migrating-to-v5"
last_modified: "2019-08-16T11:43:00+02:00"
language: "en"
---

# Migrating to v5

Learn about the changes in Adyen for Platforms API v5.

If you are currently using Adyen for Platforms API version 4 and earlier, migrate to the latest version to take advantage of new functionality and improvements.

On this page, we describe the key changes and provide recommendations for the changes that you need to do in your existing integration.

* [Changes introduced in v5](#v5-changes)
* [What you need to do to migrate to v5](#what-you-need-to-do)
* [Handling asynchronous communications](#async-requests)

## Changes in v5

We introduced the following new functionality and improvements in Adyen for Platforms API v5:

* [Asynchronous request handling](#async) for all create, update, and delete requests.

* New [granular KYC verification error codes](#new-kyc-codes).

* Support for [updating legal entity type](#update-legal-entity) of an existing account holder.

* Support for [pre-checking account holder verification](#pre-check).

* Support for [deleting payout methods](#delete-payout).

* Improvements on notifications:

  * Validation errors are now returned in the `content.invalidFields` array.
  * New top-level `error` object containing the `errorCode` and `message`. This object contains both validation and server errors.
  * Support for [signing Adyen for Platforms notifications with HMAC](/classic-platforms/configure-notifications/signing-notifications-with-hmac/).

* [API changes](#api-change-log):

  * Validation errors are now returned in the `invalidFields` array.
  * Simplified array structures for `shareholders` and `bankAccountDetails`.
  * Account holder country now required when creating a business account holder.
  * Support for adding [account `metadata`](https://docs.adyen.com/api-explorer/#/Account/v5/createAccount__reqParam_metadata), [`bankAccountReference` ](https://docs.adyen.com/api-explorer/#/Account/v5/createAccountHolder__reqParam_accountHolderDetails-bankAccountDetails-bankAccountReference), and [`shareholderReference` ](https://docs.adyen.com/api-explorer/#/Account/v5/createAccountHolder__reqParam_accountHolderDetails-businessDetails-shareholders-shareholderReference).
  * Replaced `personalData.idNumber` with [`personalData.documentData.number` ](https://docs.adyen.com/api-explorer/#/Account/v5/createAccountHolder__reqParam_accountHolderDetails-individualDetails-personalData-documentData-number).
  * Updated parameter names for [KYC summary code and descriptions](https://docs.adyen.com/api-explorer/#/Account/v5/createAccountHolder__resParam_verification-accountHolder-checks-summary): parameters renamed to`kycCheckCode` and `kycCheckDescription`.

### Asynchronous requests

In v5, all create, update, and delete requests are processed asynchronously. We return the final results of a request in notifications.

When you submit a request, we will do a static validation. Next, we'll process the request from the queue. The request can either be successfully completed or rejected (for example, payout request rejected due to change in account holder status). We will then send the final result of the request in a notification.

If your system is currently not relying on notifications to know the result of a request, see our [recommendations for handling asynchronous communications](#async-requests).

#### Asynchronous endpoints

We process the following API requests asynchronously starting from Adyen for Platforms API version 5 and later.

Check your existing notification configuration to make sure that these notifications are being sent to your server.

| Endpoints                 | Notifications **eventType** triggered     |
| ------------------------- | ----------------------------------------- |
| createAccountHolder       | ACCOUNT\_HOLDER\_CREATED ACCOUNT\_CREATED |
| updateAccountHolder       | ACCOUNT\_HOLDER\_UPDATED                  |
| uploadDocument            | ACCOUNT\_HOLDER\_UPDATED                  |
| deleteShareholders        | ACCOUNT\_HOLDER\_UPDATED                  |
| deleteBankAccounts        | ACCOUNT\_HOLDER\_UPDATED                  |
| createAccount             | ACCOUNT\_CREATED                          |
| updateAccount             | ACCOUNT\_UPDATED                          |
| closeAccount              | ACCOUNT\_CLOSED                           |
| updateAccountHolderState  | ACCOUNT\_HOLDER\_STATUS\_CHANGE           |
| suspendAccountHolder      | ACCOUNT\_HOLDER\_STATUS\_CHANGE           |
| unSuspendAccountHolder    | ACCOUNT\_HOLDER\_STATUS\_CHANGE           |
| closeAccountHolder        | ACCOUNT\_HOLDER\_STATUS\_CHANGE           |
| payoutAccountHolder       | ACCOUNT\_HOLDER\_PAYOUT                   |
| refundNotPaidOutTransfers | SCHEDULED\_REFUNDS                        |
| transferFunds             | TRANSFER\_FUNDS                           |
| setupBeneficiary          | BENEFICIARY\_SETUP                        |

### Support for updating the legal entity type of an existing account holder

Sometimes sub-merchants sign up with an incorrect legal entity type. In v5, you can fix this by [changing the legal entity of the account holder](/classic-platforms/account-holders-and-accounts/change-legal-entity). You also have the choice to migrate the account holder's existing details to the new legal entity type, or to provide new details. In both options, you get to keep the same `accountHolderCode`, `accountCode`, and the transaction history of the account holder.

### Support for pre-checking account holder verification

You can now use the [`/checkAccountHolder` ](https://docs.adyen.com/api-explorer/#/Account/v5/checkAccountHolder)endpoint to send a request to trigger account holder verification earlier than required by the currently processed volume.

### Support for deleting payout methods

You can now use the [`/deletePayoutMethods` ](https://docs.adyen.com/api-explorer/#/Account/v5/deletePayoutMethods)to request to delete payout methods of an existing account holder.

### New granular verification error codes

In v5, we implemented better [verification error codes](/classic-platforms/verification-process/verification-codes) to help you determine which type of check the error is for. Error codes are now divided into check categories:

* **Photo ID verification**: Error codes starting with 11xx.
* **Identity check**: Error codes starting with 13xx.
* **Company verification**: Error codes starting with 21xx.
* **Bank account verification**: Error codes starting with 31xx.

## What you need to do

To migrate your existing Adyen for Platforms API integration to v5, you need to:

1. [Review if you need to change your API response and notification handling](#check-response-notifications).
2. [Update your notification configuration](#update-notif).
3. [Check your API requests](#check-api-request) to make sure that you are sending the request format.
4. [Change your Adyen for Platforms Account and Fund API to v5](#update-endpoint).

### Step 1: Review your API response and notifications handling

If you are using data from the API response or from the notifications, make sure that you change your implementation to handle the changes in the array structure.

To compare, you get the `shareholderCode` from:

* v4: `accountHolderDetails.businessDetails.shareholders.ShareholderContact.shareholderCode`
* v5: `accountHolderDetails.businessDetails.shareholders.shareholderCode`

The same applies for `bankAccountDetails`. You get the `bankAccountUUID` from:

* v4: `accountHolderDetails.bankAccountDetails.bankAccountDetail.bankAccountUUID`
* v5: `accountHolderDetails.bankAccountDetails.bankAccountUUID`

The same also applies for getting the `accountCode`:

* v4: `accountHolderDetails.accounts.Account.accountCode`
* v5: `accountHolderDetails.accounts.accountCode`

In v5, we also included additional objects that you can use for error handling:

* `invalidFields`: This array contains field validation errors. If there were no invalid fields in the request, this array will be empty. The validation errors are also returned in notifications, in the `content.invalidFields`.
* `error`: This top-level object is returned in notifications, containing information why the request failed. If no error occurred during the processing, this object will be empty.

### Step 2: Update your notification configuration

To start accepting the notifications for all asynchronous requests and to get the new notification format in v5, you need to create a new notification configuration or update an existing active configuration, containing the following additional information:

* `apiVersion`: Set this to version **5**.
* `eventTypes`: Enable all the `eventType` values in the for all [asynchronous requests](#async-endpoints), and set the `includeMode` to **INCLUDE**.

In the example below, we update the existing active configuration `notificationId` **20008** to `apiVersion` **5**.

**Update notification configuration to v5**

```json
{
  "configurationDetails":{
  	"apiVersion": 5,
    "notificationId": 20008,
"notifyURL":"https://www.merchant-domain.com/notification-handler",
"eventConfigs": [
   {
     "eventType": "TRANSFER_FUNDS",
     "includeMode": "INCLUDE"
   },
   {
     "eventType": "BENEFICIARY_SETUP",
     "includeMode": "INCLUDE"
   }
   ...
  ]
  }
}
```

**Notification configuration response**

```json
{
  "pspReference": "8515652643411036",
  "configurationDetails": {
    "active": true,
    "apiVersion": 5,
    "eventConfigs": [
      {
        "eventType": "TRANSFER_FUNDS",
        "includeMode": "INCLUDE"
      },
      {
        "eventType": "BENEFICIARY_SETUP",
        "includeMode": "INCLUDE"
      }
      ...
    ],
    "notificationId": 20008,
    "notifyURL": "https://www.merchant-domain.com/notification-handler",
    "sslProtocol": "SSLInsecureCiphers"
  }
}
```

For more information on configuring notifications, refer to [Configure notifications](/classic-platforms/configure-notifications) and [Notification types](/classic-platforms/notification-types). You may also want to configure HMAC signing of notifications for additional verification. To do this, see [Signing Adyen for Platforms notifications with HMAC](/classic-platforms/configure-notifications/signing-notifications-with-hmac).

### Step 3: Check your API requests

In v5, we simplified the array structure for `shareholders` and `bankAccountDetails`. Make sure that you are sending your requests using the array structure changes.

To compare, you send the shareholder name in:

* v4: `accountHolderDetails.businessDetails.shareholders.ShareholderContact.name`
* v5: `accountHolderDetails.businessDetails.shareholders.name`

The same applies for `bankAccountDetails`. To compare creating new bank account details:

* v4: `accountHolderDetails.bankAccountDetails.bankAccountDetail.accountNumber`
* v5: `accountHolderDetails.bankAccountDetails.accountNumber`

In this step, also check for mandatory and optional fields introduced in v5. For example, `accountHolderDetails.address.country` is now required when creating a business holder account.

Refer to our [Adyen for Platforms API v5 change log](#api-change-log) for the changes in API parameters.

### Step 4: Update your endpoints to v5

Change all your Adyen for Platforms Account and Fund APIs to v5. For example:

```js
https://cal-test.adyen.com/cal/services/Account/v5/updateAccountHolder
```

## Recommendations for handling asynchronous communication

In v5, you must rely on notifications to know about the final result of a transaction.

When you make a create, update, or delete request, you get a corresponding `pspReference` in the response. We then add the request in our queue. Use the `pspReference` from the response to match the transactions. Once the request has been processed, we send a notification containing the same `pspReference` and the final result of the transaction.

In the example below, we show a scenario where a sub-merchant updates bank details.

![](/user/pages/docs/06.classic-platforms/38.migrating-to-v5/async-notif.svg?decoding=auto\&fetchpriority=auto)

We recommend that you perform the update in the following manner:

1. Make an `/updateAccountHolder` request.
2. Check if the response contains validation errors in the `invalidFields` array. Handle this in your front end (for example, ask sub-merchant to provide a valid account number) and resend the request if needed. Keep the `pspReference` from the response.
3. Wait for the notification containing the same `pspReference`.
4. Store the notification in your system.
5. Acknowledge the notification.
6. Process the request result from the notification. For example, inform your sub-merchant that the bank details has been successfully updated.

If there were any conflicting, concurrent change requested for the same account holder that resulted to an error, we will return the information in the `error` object in the notification. For example, the bank account update request can fail if there was a concurrent request to update the account holder status to Suspended.

In step 2, if you did not get a response or if you did not get a `pspReference`, resend the request. We recommend that you apply API [idempotency](/development-resources/api-idempotency#enable-idempotency) so that you can safely retry the request multiple times without duplicating the changes.

### Response codes

When you submit an [asynchronous API request](#async-endpoints), you'll receive a response that may contain any of the following status codes:

* **HTTP 200**: You can use the information returned in API response but wait for the corresponding notification before using the information on the response to perform any business logic. The notification confirms when the resource has been added in our central database.

  For example, if you get an HTTP 200 response to a `/createAccountHolder` request, you can use the `accountCode` for your reference. However, wait for the [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_CREATED) notification before performing any `/payoutAccountHolder` request.

* **HTTP 202**: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made.

  For example, if you get an HTTP 202 response to a `/createAccountHolder` request, wait for the [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_CREATED) notification to confirm if the account holder has been successfully created. Get the corresponding `accountCode` from the notification.

## Adyen for Platforms API parameters change log

In the following sections we list out the changes from API v4 to v5:

### Account service

#### New endpoints

| New endpoints        | Description                                                                                                        |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| /checkAccountHolder  | Request to trigger the verification of the account holder earlier than required by the currently processed volume. |
| /deletePayoutMethods | Delete payout methods of an existing account holder.                                                               |

#### Changes to request parameters

| Endpoints                                 | Request parameters                      | Status  | Description                                                                                                                                                                               |
| ----------------------------------------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| /createAccount /updateAccount             | metadata                                | NEW     | Optional. A set of key-value pairs when creating accounts for an existing account holder. You can now use this in /createAccount and /updateAccount                                       |
| /createAccountHolder /updateAccountHolder | accountHolderDetails.payoutMethod array | NEW     | Optional. Array of card tokens associated with the account holder.                                                                                                                        |
|                                           | bankAccountDetails.bankAccountReference | NEW     | Optional. Your own bank account reference.                                                                                                                                                |
|                                           | shareholders.shareholderReference       | NEW     | Optional. Your own shareholder reference.                                                                                                                                                 |
|                                           | personalData.idNumber                   | REMOVED | Replaced with documentData.number                                                                                                                                                         |
| /updateAccountHolder                      | AccountHolderDetails.Address.country    | NEW     | Required when creating a business account holder. The two-character country code of the address. The permitted country codes are defined in ISO-3166-1 alpha-2. For example, (e.g. 'NL'). |
|                                           | legalEntity                             | NEW     | Optional. The new legal entity for the account holder.                                                                                                                                    |
| /uploadDocument                           | accountHolderCode                       | REMOVED | Replaced with documentDetail.accountHolderCode                                                                                                                                            |
|                                           | bankAccountUUID                         | REMOVED | Replaced with documentDetail.bankAccountUUID                                                                                                                                              |
|                                           | shareholderCode                         | REMOVED | Replaced with documentDetail.shareholderCode                                                                                                                                              |

#### Changes to response parameters

| Endpoints                                                   | Response parameters                                           | Status  | Description                                                                                          |
| ----------------------------------------------------------- | ------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| All endpoints                                               | invalidFields                                                 | NEW     | This array is returned if there are field validation errors in the request.                          |
| /getAccountHolder /updateAccountHolder /createAccountHolder | accountHolderStatus.payoutState.notAllowedReason              | NEW     | Contains the reason why payouts to all of the account holder's accounts have been disabled by Adyen. |
|                                                             | verification.accountHolder.checks.summary.code                | REMOVED | Renamed as verification.accountHolder.checks.summary.kycCheckCode.                                   |
|                                                             | verification.accountHolder.checks.summary.description         | REMOVED | Renamed as verification.accountHolder.checks.summary.kycCheckDescription.                            |
|                                                             | verification.accountHolder.checks.summary.kycCheckCode        | NEW     | Replaced verification.accountHolder.checks.summary.code.                                             |
|                                                             | verification.accountHolder.checks.summary.kycCheckDescription | NEW     | Replaced verification.accountHolder.checks.summary.description.                                      |
|                                                             | primaryCurrency                                               | NEW     | Now returned in the response.                                                                        |
| /updateAccountHolder                                        | updatedFields                                                 | REMOVED | No longer returned.                                                                                  |
| All endpoints                                               | invalidFields                                                 | NEW     | This array is returned if there are field validation errors in the request.                          |
|                                                             | submittedAsync                                                | REMOVED | All create and update requests are now asynchronous                                                  |

### Notification configuration service

#### Changes to request parameters

| Endpoints                                                         | Request parameters                    | Status | Description                                                                                                                                                                                                                                                           |
| ----------------------------------------------------------------- | ------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| /createNotificationConfiguration /updateNotificationConfiguration | configurationDetails.hmacSignatureKey | NEW    | Optional. A string with which to salt the notification(s) before hashing. If this field is provided, a hash value will be included under the notification header \`HmacSignature\` and the hash protocol will be included under the notification header \`Protocol\`. |

#### Changes to response parameters

| Endpoints     | Request parameters | Status  | Description                                                                 |
| ------------- | ------------------ | ------- | --------------------------------------------------------------------------- |
| All endpoints | invalidFields      | NEW     | This array is returned if there are field validation errors in the request. |
|               | submittedAsync     | REMOVED | All create and update requests are now asynchronous                         |