Migrating to 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
• What you need to do to migrate to v5
• Handling asynchronous communications

Changes in v5

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

• Asynchronous request handling for all create, update, and delete requests.
• New granular KYC verification error codes.
• Support for updating legal entity type of an existing account holder.
• Support for pre-checking account holder verification.
• Support for deleting payout methods.

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

• API changes:

  • 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, bankAccountReference , and shareholderReference .
  • Replaced personalData.idNumber with personalData.documentData.number .
  • Updated parameter names for KYC summary code and descriptions: parameters renamed tokycCheckCode 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.

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.

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. 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 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 to request to delete payout methods of an existing account holder.

New granular verification error codes

In 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:

• 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.
2. Update your notification configuration.
3. Check your API requests to make sure that you are sending the request format.
4. Change your Adyen for Platforms Account and Fund API to v5.

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, and set the includeMode to INCLUDE.

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

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

{
  "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 and 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.

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 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:

Copy code
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.

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 so that you can safely retry the request multiple times without duplicating the changes.

Response codes

When you submit an asynchronous API request, 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 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 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

Changes to request parameters

Changes to response parameters

Notification configuration service

Changes to request parameters

Changes to response parameters