{"title":"Migrating to v5","category":"Classic Platforms","creationDate":1778842588,"content":"<p>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.<\/p>\n<p>On this page, we describe the key changes and provide recommendations for the changes that you need to do in your existing integration.<\/p>\n<ul>\n<li><a href=\"#v5-changes\">Changes introduced in v5<\/a><\/li>\n<li><a href=\"#what-you-need-to-do\">What you need to do to migrate to v5<\/a><\/li>\n<li><a href=\"#async-requests\">Handling asynchronous communications<\/a><\/li>\n<\/ul>\n<h2 id=\"v5-changes\">Changes in v5<\/h2>\n<p>We introduced the following new functionality and improvements in Adyen for Platforms API v5:<\/p>\n<ul>\n<li><a href=\"#async\">Asynchronous request handling<\/a> for all create, update, and delete requests.<\/li>\n<li>New <a href=\"#new-kyc-codes\">granular KYC verification error codes<\/a>.<\/li>\n<li>Support for <a href=\"#update-legal-entity\">updating legal entity type<\/a> of an existing account holder.<\/li>\n<li>Support for <a href=\"#pre-check\">pre-checking account holder verification<\/a>.<\/li>\n<li>Support for <a href=\"#delete-payout\">deleting payout methods<\/a>.<\/li>\n<li>\n<p>Improvements on notifications:<\/p>\n<ul>\n<li>Validation errors are now returned in the <code>content.invalidFields<\/code> array.<\/li>\n<li>New top-level <code>error<\/code> object containing the <code>errorCode<\/code> and <code>message<\/code>. This object contains both validation and server errors.<\/li>\n<li>Support for <a href=\"\/classic-platforms\/configure-notifications\/signing-notifications-with-hmac\/\">signing Adyen for Platforms notifications with HMAC<\/a>.<\/li>\n<\/ul>\n<\/li>\n<li>\n<p><a href=\"#api-change-log\">API changes<\/a>:<\/p>\n<ul>\n<li>Validation errors are now returned in the <code>invalidFields<\/code> array.<\/li>\n<li>Simplified array structures for <code>shareholders<\/code> and <code>bankAccountDetails<\/code>.<\/li>\n<li>Account holder country now required when creating a business account holder.<\/li>\n<li>Support for adding <a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/Account\/v5\/createAccount__reqParam_metadata\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">account <code>metadata<\/code><\/a>, <a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/Account\/v5\/createAccountHolder__reqParam_accountHolderDetails-bankAccountDetails-bankAccountReference\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\n  <code>bankAccountReference<\/code>\n<\/a>, and <a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/Account\/v5\/createAccountHolder__reqParam_accountHolderDetails-businessDetails-shareholders-shareholderReference\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\n  <code>shareholderReference<\/code>\n<\/a>.<\/li>\n<li>Replaced <code>personalData.idNumber<\/code> with <a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/Account\/v5\/createAccountHolder__reqParam_accountHolderDetails-individualDetails-personalData-documentData-number\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\n  <code>personalData.documentData.number<\/code>\n<\/a>.<\/li>\n<li>Updated parameter names for <a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/Account\/v5\/createAccountHolder__resParam_verification-accountHolder-checks-summary\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">KYC summary code and descriptions<\/a>: parameters renamed to<code>kycCheckCode<\/code> and <code>kycCheckDescription<\/code>.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h3 id=\"async\">Asynchronous requests<\/h3>\n<p>In v5, all create, update, and delete requests are processed asynchronously. We return the final results of a request in notifications.<\/p>\n<p>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.<\/p>\n<div class=\"sc-notice note\"><div>\n<p>If your system is currently not relying on notifications to know the result of a request, see our <a href=\"#async-requests\">recommendations for handling asynchronous communications<\/a>.<\/p>\n<\/div><\/div>\n<h4 id=\"async-endpoints\">Asynchronous endpoints<\/h4>\n<p>We process the following API requests asynchronously starting from Adyen for Platforms API version 5 and later.<\/p>\n<p>Check your existing notification configuration to make sure that these notifications are being sent to your server.<\/p>\n<table>\n<thead>\n<tr>\n<th>Endpoints<\/th>\n<th>Notifications <span translate=\"no\"><strong>eventType<\/strong><\/span> triggered<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>createAccountHolder<\/td>\n<td>ACCOUNT_HOLDER_CREATED <br> ACCOUNT_CREATED<\/td>\n<\/tr>\n<tr>\n<td>updateAccountHolder<\/td>\n<td>ACCOUNT_HOLDER_UPDATED<\/td>\n<\/tr>\n<tr>\n<td>uploadDocument<\/td>\n<td>ACCOUNT_HOLDER_UPDATED<\/td>\n<\/tr>\n<tr>\n<td>deleteShareholders<\/td>\n<td>ACCOUNT_HOLDER_UPDATED<\/td>\n<\/tr>\n<tr>\n<td>deleteBankAccounts<\/td>\n<td>ACCOUNT_HOLDER_UPDATED<\/td>\n<\/tr>\n<tr>\n<td>createAccount<\/td>\n<td>ACCOUNT_CREATED<\/td>\n<\/tr>\n<tr>\n<td>updateAccount<\/td>\n<td>ACCOUNT_UPDATED<\/td>\n<\/tr>\n<tr>\n<td>closeAccount<\/td>\n<td>ACCOUNT_CLOSED<\/td>\n<\/tr>\n<tr>\n<td>updateAccountHolderState<\/td>\n<td>ACCOUNT_HOLDER_STATUS_CHANGE<\/td>\n<\/tr>\n<tr>\n<td>suspendAccountHolder<\/td>\n<td>ACCOUNT_HOLDER_STATUS_CHANGE<\/td>\n<\/tr>\n<tr>\n<td>unSuspendAccountHolder<\/td>\n<td>ACCOUNT_HOLDER_STATUS_CHANGE<\/td>\n<\/tr>\n<tr>\n<td>closeAccountHolder<\/td>\n<td>ACCOUNT_HOLDER_STATUS_CHANGE<\/td>\n<\/tr>\n<tr>\n<td>payoutAccountHolder<\/td>\n<td>ACCOUNT_HOLDER_PAYOUT<\/td>\n<\/tr>\n<tr>\n<td>refundNotPaidOutTransfers<\/td>\n<td>SCHEDULED_REFUNDS<\/td>\n<\/tr>\n<tr>\n<td>transferFunds<\/td>\n<td>TRANSFER_FUNDS<\/td>\n<\/tr>\n<tr>\n<td>setupBeneficiary<\/td>\n<td>BENEFICIARY_SETUP<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3 id=\"update-legal-entity\">Support for updating the legal entity type of an existing account holder<\/h3>\n<p>Sometimes sub-merchants sign up with an incorrect legal entity type. In v5, you can fix this by <a href=\"\/classic-platforms\/account-holders-and-accounts\/change-legal-entity\">changing the legal entity of the account holder<\/a>. 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 <code>accountHolderCode<\/code>, <code>accountCode<\/code>, and the transaction history of the account holder.<\/p>\n<h3 id=\"pre-check\">Support for pre-checking account holder verification<\/h3>\n<p>You can now use the <a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/Account\/v5\/checkAccountHolder\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\n  <code>\/checkAccountHolder<\/code>\n<\/a> endpoint to send a request to trigger account holder verification earlier than required by the currently processed volume.<\/p>\n<h3 id=\"delete-payout\">Support for deleting payout methods<\/h3>\n<p>You can now use the <a href=\"https:\/\/docs.adyen.com\/api-explorer\/#\/Account\/v5\/deletePayoutMethods\" class=\"codeLabel external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\n  <code>\/deletePayoutMethods<\/code>\n<\/a> to request to delete payout methods of an existing account holder.<\/p>\n<h3 id=\"new-kyc-codes\">New granular verification error codes<\/h3>\n<p>In v5, we implemented better <a href=\"\/classic-platforms\/verification-process\/verification-codes\">verification error codes<\/a> to help you determine which type of check the error is for. Error codes are now divided into check categories:<\/p>\n<ul>\n<li><strong>Photo ID verification<\/strong>: Error codes starting with 11xx.<\/li>\n<li><strong>Identity check<\/strong>: Error codes starting with 13xx.<\/li>\n<li><strong>Company verification<\/strong>: Error codes starting with 21xx.<\/li>\n<li><strong>Bank account verification<\/strong>: Error codes starting with 31xx.<\/li>\n<\/ul>\n<h2 id=\"what-you-need-to-do\">What you need to do<\/h2>\n<p>To migrate your existing Adyen for Platforms API integration to v5, you need to:<\/p>\n<ol>\n<li><a href=\"#check-response-notifications\">Review if you need to change your API response and notification handling<\/a>.<\/li>\n<li><a href=\"#update-notif\">Update your notification configuration<\/a>.<\/li>\n<li><a href=\"#check-api-request\">Check your API requests<\/a> to make sure that you are sending the request format.<\/li>\n<li><a href=\"#update-endpoint\">Change your Adyen for Platforms Account and Fund API to v5<\/a>.<\/li>\n<\/ol>\n<h3 id=\"check-response-notifications\">Step 1: Review your API response and notifications handling<\/h3>\n<p>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.<\/p>\n<p>To compare, you get the <code>shareholderCode<\/code> from:<\/p>\n<ul>\n<li>v4: <code>accountHolderDetails.businessDetails.shareholders.ShareholderContact.shareholderCode<\/code><\/li>\n<li>v5: <code>accountHolderDetails.businessDetails.shareholders.shareholderCode<\/code><\/li>\n<\/ul>\n<p>The same applies for <code>bankAccountDetails<\/code>. You get the <code>bankAccountUUID<\/code> from:<\/p>\n<ul>\n<li>v4: <code>accountHolderDetails.bankAccountDetails.bankAccountDetail.bankAccountUUID<\/code><\/li>\n<li>v5: <code>accountHolderDetails.bankAccountDetails.bankAccountUUID<\/code><\/li>\n<\/ul>\n<p>The same also applies for getting the <code>accountCode<\/code>:<\/p>\n<ul>\n<li>v4: <code>accountHolderDetails.accounts.Account.accountCode<\/code><\/li>\n<li>v5: <code>accountHolderDetails.accounts.accountCode<\/code><\/li>\n<\/ul>\n<p>In v5, we also included additional objects that you can use for error handling:<\/p>\n<ul>\n<li><code>invalidFields<\/code>: 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 <code>content.invalidFields<\/code>.<\/li>\n<li><code>error<\/code>: 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.<\/li>\n<\/ul>\n<h3 id=\"update-notif\">Step 2: Update your notification configuration<\/h3>\n<p>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:<\/p>\n<ul>\n<li><code>apiVersion<\/code>: Set this to version <strong>5<\/strong>.<\/li>\n<li><code>eventTypes<\/code>: Enable all the <code>eventType<\/code> values in the for all <a href=\"#async-endpoints\">asynchronous requests<\/a>, and set the <code>includeMode<\/code> to <span translate=\"no\"><strong>INCLUDE<\/strong><\/span>.<\/li>\n<\/ul>\n<p>In the example below, we update the existing active configuration <code>notificationId<\/code> <strong>20008<\/strong> to <code>apiVersion<\/code> <strong>5<\/strong>.<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Update notification configuration to v5'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"configurationDetails\\\":{\\n  \\t\\\"apiVersion\\\": 5,\\n    \\\"notificationId\\\": 20008,\\n\\\"notifyURL\\\":\\\"https:\\\/\\\/www.merchant-domain.com\\\/notification-handler\\\",\\n\\\"eventConfigs\\\": [\\n   {\\n     \\\"eventType\\\": \\\"TRANSFER_FUNDS\\\",\\n     \\\"includeMode\\\": \\\"INCLUDE\\\"\\n   },\\n   {\\n     \\\"eventType\\\": \\\"BENEFICIARY_SETUP\\\",\\n     \\\"includeMode\\\": \\\"INCLUDE\\\"\\n   }\\n   ...\\n  ]\\n  }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Notification configuration response'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"pspReference\\\": \\\"8515652643411036\\\",\\n  \\\"configurationDetails\\\": {\\n    \\\"active\\\": true,\\n    \\\"apiVersion\\\": 5,\\n    \\\"eventConfigs\\\": [\\n      {\\n        \\\"eventType\\\": \\\"TRANSFER_FUNDS\\\",\\n        \\\"includeMode\\\": \\\"INCLUDE\\\"\\n      },\\n      {\\n        \\\"eventType\\\": \\\"BENEFICIARY_SETUP\\\",\\n        \\\"includeMode\\\": \\\"INCLUDE\\\"\\n      }\\n      ...\\n    ],\\n    \\\"notificationId\\\": 20008,\\n    \\\"notifyURL\\\": \\\"https:\\\/\\\/www.merchant-domain.com\\\/notification-handler\\\",\\n    \\\"sslProtocol\\\": \\\"SSLInsecureCiphers\\\"\\n  }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>For more information on configuring notifications, refer to\u00a0<a href=\"\/classic-platforms\/configure-notifications\">Configure notifications<\/a>\u00a0and\u00a0<a href=\"\/classic-platforms\/notification-types\">Notification types<\/a>.\u00a0You may also want to configure HMAC signing of notifications for additional verification. To do this, see <a href=\"\/classic-platforms\/configure-notifications\/signing-notifications-with-hmac\">Signing Adyen for Platforms notifications with HMAC<\/a>.<\/p>\n<h3 id=\"check-api-request\">Step 3: Check your API requests<\/h3>\n<p>In v5, we simplified the array structure for <code>shareholders<\/code> and <code>bankAccountDetails<\/code>. Make sure that you are sending your requests using the array structure changes.<\/p>\n<p>To compare, you send the shareholder name in:<\/p>\n<ul>\n<li>v4: <code>accountHolderDetails.businessDetails.shareholders.ShareholderContact.name<\/code><\/li>\n<li>v5: <code>accountHolderDetails.businessDetails.shareholders.name<\/code><\/li>\n<\/ul>\n<p>The same applies for <code>bankAccountDetails<\/code>. To compare creating new bank account details:<\/p>\n<ul>\n<li>v4: <code>accountHolderDetails.bankAccountDetails.bankAccountDetail.accountNumber<\/code><\/li>\n<li>v5: <code>accountHolderDetails.bankAccountDetails.accountNumber<\/code><\/li>\n<\/ul>\n<p>In this step, also check for mandatory and optional fields introduced in v5. For example, <code>accountHolderDetails.address.country<\/code> is now required when creating a business holder account.<\/p>\n<p>Refer to our <a href=\"#api-change-log\">Adyen for Platforms API v5 change log<\/a> for the changes in API parameters.<\/p>\n<h3 id=\"update-endpoint\">Step 4: Update your endpoints to v5<\/h3>\n<p>Change all your Adyen for Platforms Account and Fund APIs to v5. For example:<\/p>\n<pre><code class=\"language-js\">https:\/\/cal-test.adyen.com\/cal\/services\/Account\/v5\/updateAccountHolder<\/code><\/pre>\n<h2 id=\"async-requests\">Recommendations for handling asynchronous communication<\/h2>\n<p>In v5, you must rely on notifications to know about the final result of a transaction.<\/p>\n<p>When you make a create, update, or delete request, you get a corresponding <code>pspReference<\/code> in the response. We then add the request in our queue. Use the <code>pspReference<\/code> from the response to match the transactions. Once the request has been processed, we send a notification containing the same <code>pspReference<\/code> and the final result of the transaction.<\/p>\n<p>In the example below, we show a scenario where a sub-merchant updates bank details.<\/p>\n<div style=\"text-align: center;\">\n<p><img alt=\"\" src=\"\/user\/pages\/docs\/06.classic-platforms\/38.migrating-to-v5\/async-notif.svg?decoding=auto&amp;fetchpriority=auto\" \/><\/p>\n<\/div>\n<p>We recommend that you perform the update in the following manner:<\/p>\n<ol>\n<li>Make an <code>\/updateAccountHolder<\/code> request.<\/li>\n<li>Check if the response contains validation errors in the <code>invalidFields<\/code> 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 <code>pspReference<\/code> from the response.<\/li>\n<li>Wait for the notification containing the same <code>pspReference<\/code>.<\/li>\n<li>Store the notification in your system.<\/li>\n<li>Acknowledge the notification.<\/li>\n<li>Process the request result from the notification. For example, inform your sub-merchant that the bank details has been successfully updated.<\/li>\n<\/ol>\n<p>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 <code>error<\/code> 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.<\/p>\n<p>In step 2, if you did not get a response or if you did not get a <code>pspReference<\/code>, resend the request. We recommend that you apply API <a href=\"\/development-resources\/api-idempotency#enable-idempotency\">idempotency<\/a> so that you can safely retry the request multiple times without duplicating the changes.<\/p>\n<h3>Response codes<\/h3>\n<p>When you submit an <a href=\"#async-endpoints\">asynchronous API request<\/a>, you'll receive a response that may contain any of the following status codes:<\/p>\n<ul>\n<li>\n<p><span translate=\"no\"><strong>HTTP 200<\/strong><\/span>: 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.<\/p>\n<p>For example, if you get an HTTP 200 response to a <code>\/createAccountHolder<\/code> request, you can use the <code>accountCode<\/code> for your reference. However, wait for the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Notification\/latest\/post\/ACCOUNT_HOLDER_CREATED\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">ACCOUNT_HOLDER_CREATED<\/a> notification before performing any <code>\/payoutAccountHolder<\/code> request.<\/p>\n<\/li>\n<li>\n<p><span translate=\"no\"><strong>HTTP 202<\/strong><\/span>: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made.<\/p>\n<p>For example, if you get an HTTP 202 response to a <code>\/createAccountHolder<\/code> request, wait for the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Notification\/latest\/post\/ACCOUNT_HOLDER_CREATED\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">ACCOUNT_HOLDER_CREATED<\/a> notification to confirm if the account holder has been successfully created. Get the corresponding <code>accountCode<\/code> from the notification.<\/p>\n<\/li>\n<\/ul>\n<h2 id=\"api-change-log\">Adyen for Platforms API parameters change log<\/h2>\n<p>In the following sections we list out the changes from API v4 to v5:<\/p>\n<h3>Account service<\/h3>\n<h4>New endpoints<\/h4>\n<table>\n<thead>\n<tr>\n<th>New endpoints<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>\/checkAccountHolder<\/td>\n<td>Request to trigger the verification of the account holder earlier than required by the currently processed volume.<\/td>\n<\/tr>\n<tr>\n<td>\/deletePayoutMethods<\/td>\n<td>Delete payout methods of an existing account holder.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h4>Changes to request parameters<\/h4>\n<table>\n<thead>\n<tr>\n<th>Endpoints<\/th>\n<th>Request parameters<\/th>\n<th>Status<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>\/createAccount <br> \/updateAccount<\/td>\n<td>metadata<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Optional. A set of key-value pairs when creating accounts for an existing account holder. You can now use this in \/createAccount and \/updateAccount<\/td>\n<\/tr>\n<tr>\n<td rowspan=\"4\">\/createAccountHolder <br>\/updateAccountHolder<\/td>\n<td>accountHolderDetails.payoutMethod array<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Optional. Array of card tokens associated with the account holder.<\/td>\n<\/tr>\n<tr>\n<td>bankAccountDetails.bankAccountReference<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Optional. Your own bank account reference.<\/td>\n<\/tr>\n<tr>\n<td>shareholders.shareholderReference<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Optional. Your own shareholder reference.<\/td>\n<\/tr>\n<tr>\n<td>personalData.idNumber<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td>Replaced with documentData.number<\/td>\n<\/tr>\n<tr>\n<td rowspan=\"2\">\/updateAccountHolder<\/td>\n<td>AccountHolderDetails.Address.country<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>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').<\/td>\n<\/tr>\n<tr>\n<td>legalEntity<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Optional. The new legal entity for the account holder.<\/td>\n<\/tr>\n<tr>\n<td rowspan=\"3\">\/uploadDocument<\/td>\n<td>accountHolderCode<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td>Replaced with documentDetail.accountHolderCode<\/td>\n<\/tr>\n<tr>\n<td>bankAccountUUID<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td>Replaced with documentDetail.bankAccountUUID<\/td>\n<\/tr>\n<tr>\n<td>shareholderCode<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td>Replaced with documentDetail.shareholderCode<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h4>Changes to response parameters<\/h4>\n<table>\n<thead>\n<tr>\n<th>Endpoints<\/th>\n<th>Response parameters<\/th>\n<th>Status<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>All endpoints<\/td>\n<td>invalidFields<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>This array is returned if there are field validation errors in the request.<\/td>\n<\/tr>\n<tr>\n<td rowspan=\"6\">\/getAccountHolder <br> \/updateAccountHolder <br> \/createAccountHolder<\/td>\n<td>accountHolderStatus.payoutState.notAllowedReason<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Contains the reason why payouts to all of the account holder's accounts have been disabled by Adyen. <\/td>\n<\/tr>\n<tr>\n<td>verification.accountHolder.checks.summary.code<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td>Renamed as verification.accountHolder.checks.summary.kycCheckCode.<\/td>\n<\/tr>\n<tr>\n<td>verification.accountHolder.checks.summary.description<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td>Renamed as verification.accountHolder.checks.summary.kycCheckDescription.<\/td>\n<\/tr>\n<tr>\n<td>verification.accountHolder.checks.summary.kycCheckCode<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Replaced verification.accountHolder.checks.summary.code.<\/td>\n<\/tr>\n<tr>\n<td>verification.accountHolder.checks.summary.kycCheckDescription<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Replaced verification.accountHolder.checks.summary.description.<\/td>\n<\/tr>\n<tr>\n<td>primaryCurrency<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>Now returned in the response.<\/td>\n<\/tr>\n<tr>\n<td>\/updateAccountHolder<\/td>\n<td>updatedFields<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td>No longer returned.<\/td>\n<\/tr>\n<tr>\n<td rowspan=\"2\">All endpoints<\/td>\n<td>invalidFields<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>This array is returned if there are field validation errors in the request.<\/td>\n<\/tr>\n<tr>\n<td>submittedAsync<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td> All create and update requests are now asynchronous<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3>Notification configuration service<\/h3>\n<h4>Changes to request parameters<\/h4>\n<table>\n<thead>\n<tr>\n<th>Endpoints<\/th>\n<th>Request parameters<\/th>\n<th>Status<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>\/createNotificationConfiguration <br> \/updateNotificationConfiguration <\/td>\n<td>configurationDetails.hmacSignatureKey<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td> 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`.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h4>Changes to response parameters<\/h4>\n<table>\n<thead>\n<tr>\n<th>Endpoints<\/th>\n<th>Request parameters<\/th>\n<th>Status<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td rowspan=\"2\">All endpoints<\/td>\n<td>invalidFields<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;success&quot;>\n        NEW\n    <\/tag>\n<\/div>\n<\/td>\n<td>This array is returned if there are field validation errors in the request.<\/td>\n<\/tr>\n<tr>\n<td>submittedAsync<\/td>\n<td><div data-component-wrapper=\"tag\">\n    <tag :variant=&quot;error&quot;>\n        REMOVED\n    <\/tag>\n<\/div>\n<\/td>\n<td> All create and update requests are now asynchronous<\/td>\n<\/tr>\n<\/tbody>\n<\/table>","url":"https:\/\/docs.adyen.com\/classic-platforms\/migrating-to-v5","articleFields":{"description":"Learn about the changes in Adyen for Platforms API v5.","search_category":"Classic Platforms","last_edit_on":"16-08-2019 11:43","parameters":{"directoryPath":"\/classic-platforms"}},"algolia":{"url":"https:\/\/docs.adyen.com\/classic-platforms\/migrating-to-v5","title":"Migrating to v5","content":"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.\nOn this page, we describe the key changes and provide recommendations for the changes that you need to do in your existing integration.\n\nChanges introduced in v5\nWhat you need to do to migrate to v5\nHandling asynchronous communications\n\nChanges in v5\nWe introduced the following new functionality and improvements in Adyen for Platforms API v5:\n\nAsynchronous request handling for all create, update, and delete requests.\nNew granular KYC verification error codes.\nSupport for updating legal entity type of an existing account holder.\nSupport for pre-checking account holder verification.\nSupport for deleting payout methods.\n\nImprovements on notifications:\n\nValidation errors are now returned in the content.invalidFields array.\nNew top-level error object containing the errorCode and message. This object contains both validation and server errors.\nSupport for signing Adyen for Platforms notifications with HMAC.\n\n\n\nAPI changes:\n\nValidation errors are now returned in the invalidFields array.\nSimplified array structures for shareholders and bankAccountDetails.\nAccount holder country now required when creating a business account holder.\nSupport for adding account metadata, \n  bankAccountReference\n, and \n  shareholderReference\n.\nReplaced personalData.idNumber with \n  personalData.documentData.number\n.\nUpdated parameter names for KYC summary code and descriptions: parameters renamed tokycCheckCode and kycCheckDescription.\n\n\n\nAsynchronous requests\nIn v5, all create, update, and delete requests are processed asynchronously. We return the final results of a request in notifications.\nWhen 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.\n\nIf your system is currently not relying on notifications to know the result of a request, see our recommendations for handling asynchronous communications.\n\nAsynchronous endpoints\nWe process the following API requests asynchronously starting from Adyen for Platforms API version 5 and later.\nCheck your existing notification configuration to make sure that these notifications are being sent to your server.\n\n\n\nEndpoints\nNotifications eventType triggered\n\n\n\n\ncreateAccountHolder\nACCOUNT_HOLDER_CREATED  ACCOUNT_CREATED\n\n\nupdateAccountHolder\nACCOUNT_HOLDER_UPDATED\n\n\nuploadDocument\nACCOUNT_HOLDER_UPDATED\n\n\ndeleteShareholders\nACCOUNT_HOLDER_UPDATED\n\n\ndeleteBankAccounts\nACCOUNT_HOLDER_UPDATED\n\n\ncreateAccount\nACCOUNT_CREATED\n\n\nupdateAccount\nACCOUNT_UPDATED\n\n\ncloseAccount\nACCOUNT_CLOSED\n\n\nupdateAccountHolderState\nACCOUNT_HOLDER_STATUS_CHANGE\n\n\nsuspendAccountHolder\nACCOUNT_HOLDER_STATUS_CHANGE\n\n\nunSuspendAccountHolder\nACCOUNT_HOLDER_STATUS_CHANGE\n\n\ncloseAccountHolder\nACCOUNT_HOLDER_STATUS_CHANGE\n\n\npayoutAccountHolder\nACCOUNT_HOLDER_PAYOUT\n\n\nrefundNotPaidOutTransfers\nSCHEDULED_REFUNDS\n\n\ntransferFunds\nTRANSFER_FUNDS\n\n\nsetupBeneficiary\nBENEFICIARY_SETUP\n\n\n\nSupport for updating the legal entity type of an existing account holder\nSometimes 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. 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.\nSupport for pre-checking account holder verification\nYou can now use the \n  \/checkAccountHolder\n endpoint to send a request to trigger account holder verification earlier than required by the currently processed volume.\nSupport for deleting payout methods\nYou can now use the \n  \/deletePayoutMethods\n to request to delete payout methods of an existing account holder.\nNew granular verification error codes\nIn v5, we implemented better verification error codes to help you determine which type of check the error is for. Error codes are now divided into check categories:\n\nPhoto ID verification: Error codes starting with 11xx.\nIdentity check: Error codes starting with 13xx.\nCompany verification: Error codes starting with 21xx.\nBank account verification: Error codes starting with 31xx.\n\nWhat you need to do\nTo migrate your existing Adyen for Platforms API integration to v5, you need to:\n\nReview if you need to change your API response and notification handling.\nUpdate your notification configuration.\nCheck your API requests to make sure that you are sending the request format.\nChange your Adyen for Platforms Account and Fund API to v5.\n\nStep 1: Review your API response and notifications handling\nIf 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.\nTo compare, you get the shareholderCode from:\n\nv4: accountHolderDetails.businessDetails.shareholders.ShareholderContact.shareholderCode\nv5: accountHolderDetails.businessDetails.shareholders.shareholderCode\n\nThe same applies for bankAccountDetails. You get the bankAccountUUID from:\n\nv4: accountHolderDetails.bankAccountDetails.bankAccountDetail.bankAccountUUID\nv5: accountHolderDetails.bankAccountDetails.bankAccountUUID\n\nThe same also applies for getting the accountCode:\n\nv4: accountHolderDetails.accounts.Account.accountCode\nv5: accountHolderDetails.accounts.accountCode\n\nIn v5, we also included additional objects that you can use for error handling:\n\ninvalidFields: 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.\nerror: 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.\n\nStep 2: Update your notification configuration\nTo 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:\n\napiVersion: Set this to version 5.\neventTypes: Enable all the eventType values in the for all asynchronous requests, and set the includeMode to INCLUDE.\n\nIn the example below, we update the existing active configuration notificationId 20008 to apiVersion 5.\n\n    \n\n\n    \n\nFor more information on configuring notifications, refer to\u00a0Configure notifications\u00a0and\u00a0Notification types.\u00a0You may also want to configure HMAC signing of notifications for additional verification. To do this, see Signing Adyen for Platforms notifications with HMAC.\nStep 3: Check your API requests\nIn v5, we simplified the array structure for shareholders and bankAccountDetails. Make sure that you are sending your requests using the array structure changes.\nTo compare, you send the shareholder name in:\n\nv4: accountHolderDetails.businessDetails.shareholders.ShareholderContact.name\nv5: accountHolderDetails.businessDetails.shareholders.name\n\nThe same applies for bankAccountDetails. To compare creating new bank account details:\n\nv4: accountHolderDetails.bankAccountDetails.bankAccountDetail.accountNumber\nv5: accountHolderDetails.bankAccountDetails.accountNumber\n\nIn 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.\nRefer to our Adyen for Platforms API v5 change log for the changes in API parameters.\nStep 4: Update your endpoints to v5\nChange all your Adyen for Platforms Account and Fund APIs to v5. For example:\nhttps:\/\/cal-test.adyen.com\/cal\/services\/Account\/v5\/updateAccountHolder\nRecommendations for handling asynchronous communication\nIn v5, you must rely on notifications to know about the final result of a transaction.\nWhen 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.\nIn the example below, we show a scenario where a sub-merchant updates bank details.\n\n\n\nWe recommend that you perform the update in the following manner:\n\nMake an \/updateAccountHolder request.\nCheck 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.\nWait for the notification containing the same pspReference.\nStore the notification in your system.\nAcknowledge the notification.\nProcess the request result from the notification. For example, inform your sub-merchant that the bank details has been successfully updated.\n\nIf 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.\nIn 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 so that you can safely retry the request multiple times without duplicating the changes.\nResponse codes\nWhen you submit an asynchronous API request, you'll receive a response that may contain any of the following status codes:\n\n\nHTTP 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.\nFor 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 notification before performing any \/payoutAccountHolder request.\n\n\nHTTP 202: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made.\nFor example, if you get an HTTP 202 response to a \/createAccountHolder request, wait for the  ACCOUNT_HOLDER_CREATED notification to confirm if the account holder has been successfully created. Get the corresponding accountCode from the notification.\n\n\nAdyen for Platforms API parameters change log\nIn the following sections we list out the changes from API v4 to v5:\nAccount service\nNew endpoints\n\n\n\nNew endpoints\nDescription\n\n\n\n\n\/checkAccountHolder\nRequest to trigger the verification of the account holder earlier than required by the currently processed volume.\n\n\n\/deletePayoutMethods\nDelete payout methods of an existing account holder.\n\n\n\nChanges to request parameters\n\n\n\nEndpoints\nRequest parameters\nStatus\nDescription\n\n\n\n\n\/createAccount  \/updateAccount\nmetadata\n\n    \n        NEW\n    \n\n\nOptional. A set of key-value pairs when creating accounts for an existing account holder. You can now use this in \/createAccount and \/updateAccount\n\n\n\/createAccountHolder \/updateAccountHolder\naccountHolderDetails.payoutMethod array\n\n    \n        NEW\n    \n\n\nOptional. Array of card tokens associated with the account holder.\n\n\nbankAccountDetails.bankAccountReference\n\n    \n        NEW\n    \n\n\nOptional. Your own bank account reference.\n\n\nshareholders.shareholderReference\n\n    \n        NEW\n    \n\n\nOptional. Your own shareholder reference.\n\n\npersonalData.idNumber\n\n    \n        REMOVED\n    \n\n\nReplaced with documentData.number\n\n\n\/updateAccountHolder\nAccountHolderDetails.Address.country\n\n    \n        NEW\n    \n\n\nRequired 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').\n\n\nlegalEntity\n\n    \n        NEW\n    \n\n\nOptional. The new legal entity for the account holder.\n\n\n\/uploadDocument\naccountHolderCode\n\n    \n        REMOVED\n    \n\n\nReplaced with documentDetail.accountHolderCode\n\n\nbankAccountUUID\n\n    \n        REMOVED\n    \n\n\nReplaced with documentDetail.bankAccountUUID\n\n\nshareholderCode\n\n    \n        REMOVED\n    \n\n\nReplaced with documentDetail.shareholderCode\n\n\n\nChanges to response parameters\n\n\n\nEndpoints\nResponse parameters\nStatus\nDescription\n\n\n\n\nAll endpoints\ninvalidFields\n\n    \n        NEW\n    \n\n\nThis array is returned if there are field validation errors in the request.\n\n\n\/getAccountHolder  \/updateAccountHolder  \/createAccountHolder\naccountHolderStatus.payoutState.notAllowedReason\n\n    \n        NEW\n    \n\n\nContains the reason why payouts to all of the account holder's accounts have been disabled by Adyen. \n\n\nverification.accountHolder.checks.summary.code\n\n    \n        REMOVED\n    \n\n\nRenamed as verification.accountHolder.checks.summary.kycCheckCode.\n\n\nverification.accountHolder.checks.summary.description\n\n    \n        REMOVED\n    \n\n\nRenamed as verification.accountHolder.checks.summary.kycCheckDescription.\n\n\nverification.accountHolder.checks.summary.kycCheckCode\n\n    \n        NEW\n    \n\n\nReplaced verification.accountHolder.checks.summary.code.\n\n\nverification.accountHolder.checks.summary.kycCheckDescription\n\n    \n        NEW\n    \n\n\nReplaced verification.accountHolder.checks.summary.description.\n\n\nprimaryCurrency\n\n    \n        NEW\n    \n\n\nNow returned in the response.\n\n\n\/updateAccountHolder\nupdatedFields\n\n    \n        REMOVED\n    \n\n\nNo longer returned.\n\n\nAll endpoints\ninvalidFields\n\n    \n        NEW\n    \n\n\nThis array is returned if there are field validation errors in the request.\n\n\nsubmittedAsync\n\n    \n        REMOVED\n    \n\n\n All create and update requests are now asynchronous\n\n\n\nNotification configuration service\nChanges to request parameters\n\n\n\nEndpoints\nRequest parameters\nStatus\nDescription\n\n\n\n\n\/createNotificationConfiguration  \/updateNotificationConfiguration \nconfigurationDetails.hmacSignatureKey\n\n    \n        NEW\n    \n\n\n 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`.\n\n\n\nChanges to response parameters\n\n\n\nEndpoints\nRequest parameters\nStatus\nDescription\n\n\n\n\nAll endpoints\ninvalidFields\n\n    \n        NEW\n    \n\n\nThis array is returned if there are field validation errors in the request.\n\n\nsubmittedAsync\n\n    \n        REMOVED\n    \n\n\n All create and update requests are now asynchronous\n\n\n","type":"page","locale":"en","boost":18,"hierarchy":{"lvl0":"Home","lvl1":"Classic integration","lvl2":"Migrating to v5"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/classic-platforms","lvl2":"\/classic-platforms\/migrating-to-v5"},"levels":3,"category":"Classic Platforms","category_color":"green","tags":["Migrating"]},"articleFiles":{"async-notif.svg":"<img alt=\"\" src=\"https:\/\/docs.adyen.com\/user\/pages\/docs\/06.classic-platforms\/38.migrating-to-v5\/async-notif.svg?decoding=auto&amp;fetchpriority=auto\" \/>"}}