Adyen may occasionally require your users to review and confirm that their data is up-to-date. This data includes information about their business and all entities associated with it, such as their ultimate beneficial owners (UBOs) and signatories. Once the user confirms that they reviewed the data, and updated it if needed, Adyen verifies them again.
Adyen sends a verification deadline in a webhook. While the deadline is active, the user can continue using their capabilities that were allowed prior to the review request. If the user does not review or update the data before the deadline expires, their capabilities will be disallowed.
Step 1: Get updates when a review is required
Adyen informs you if a user data review is required through a balancePlatform.accountHolder.updated webhook. The webhook contains the following information:
| Field | Description |
|---|---|
| verificationStatus | Set to invalid |
| allowed | Remains set to true |
| verificationErrors | Contains the verification error 3_10 and message "Review of data is required". |
| verificationDeadlines | The date when the capability will be disallowed if the verification error is not resolved. |
| remediatingActions | Contains the remediating action 3_100 and message "Use /legalEntities/{id}/confirmDataReview to indicate that the data is confirmed". |
Note that the webhook contains the capabilities that will be disallowed if the user does not confirm that they have reviewed and updated their data.
Step 2: Ask your users to review their data within the deadline
Inform your user that they need to review their data and to provide updated information if needed. Follow the steps below depending on your type of integration.
- Make a GET /legalEntities/{id} request with the legal entity ID of the user in the path. Review any user information that you submitted to Adyen through API requests. For example, information about the user's legal entities.
- If needed, make a PATCH /legalEntities/{id} request to update any user information.
- Then, create a hosted onboarding link. When the user is redirected to the link, they are presented with a summary page where they can confirm or update their data.
- After the user completes their review, they need to select the checkbox and then select Submit review to confirm that their data is now up-to-date. This resolves the verification error related to the data review.
Step 3: Get the verification results
Once the review has been submitted, Adyen verifies the user’s data and informs you of the results through the balancePlatform.accountHolder.updated webhook.
To resolve any verification errors, follow the steps based on your integration type: API-only onboarding or Hosted onboarding.
After the user has reviewed their data and the verification is valid, there is no further action needed.
Verification valid
When the checks are completed successfully, Adyen sends a balancePlatform.accountHolder.updated webhook with:
- verificationStatus: Set to valid.
- allowed: Set to true.
Verification invalid
When there are problems with the verification, Adyen sends a balancePlatform.accountHolder.updated webhook.
The webhook contains the following information:
- verificationStatus: Set to invalid.
- allowed: Set to false or true with the verificationDeadlines array showing when the capability will be disallowed if the verification error is not resolved.
- problems: Contains
verificationErrors,subErrors, andremediatingActionsarrays returned on the linked legal entity. If there are verification errors, you must resolve them.
To see any problems also returned on the transfer instrument resource, reach out to your Adyen contact to enable the feature. For example, if your users have multiple transfer instruments, this can help them more easily see the errors and on which transfer instrument they need to be resolved.
Test the data review flow
In this scenario, you force Adyen to send a verification error relating to one of your users (a legal entity). This verification error is due to an outstanding data review required by Adyen.
The account holder for the legal entity must already have capabilities allowed to be able test the flow.
Step 1: Make an API request
Using the Legal Entity Management API, make a PATCH /legalEntities/{id} request. Include the x-requested-verification-code 3_10 in the header of your request.
Step 2: Check verification results
To confirm that the legal entity has an outstanding data review required, you can:
- Listen to the balancePlatform.accountHolder.updated webhook or
- Make a GET /legalEntities/{id} request for the specified legal entity or
- Make a POST /checkVerificationErrors request for the specified legal entity.
These all contain the verification error 3_10 and message "Review of data is required".
Step 3: Resolve the verification error
Make a POST /legalEntities/{id}/confirmDataReview request with the specified legal entity ID in the path. The response returns the time when the data review was confirmed in the dataReviewedAt field. You can confirm the verification error was resolved by listening to webhooks or making a GET API request.