Adyen for Platforms is our end-to-end solution designed for marketplaces and other platform models looking to set up a scalable, feature-rich platform for their merchants and end users. Amongst its vast array of features, one stands out: the Hosted Onboarding solution.

Hosted Onboarding simplifies the process for both the platform and its merchants. It reduces the complexities that come with complying to regulatory requirements and enables sellers to quickly get onboarded and accept payments.

While Hosted Onboarding offers an out-of-the box intuitive user interface, customizable themes and configuration, and tailored onboarding flows, it's important to understand there is some development work required to ensure a seamless integration.

In this article…

...discover the key benefits and functionalities of Adyen's Hosted Onboarding solution. Design an optimal flow between the platform and the Hosted Onboarding solution. Learn what developers need to consider, implement and optimize to deliver a frictionless and secure integration.

Onboarding flow

The onboarding of new sellers on the platform involves multiple steps and the process can vary significantly. The main factors that determine this process are the platform type (marketplace or platform setup), its location (countries), and the type of end merchants (individuals, organizations, sole proprietorships). Moreover when making financial products available, additional regulations may apply.

You can find a comprehensive guide of the verification process on Adyen Docs. Now we are going to focus on a specific example: get ready to onboard the restaurant Healthy Tacos for a US based platform in the food and beverage industry.

In this context the onboarding journey of Healthy Tacos looks like:

• Create a profile
• Fill in the required information
• Provide the necessary documents (if applicable)
• The Healthy Tacos account is verified and can begin accepting transactions

The diagram helps us visualize the journey on a mobile. It also distinguishes the ownership of each phase (Platform vs Adyen).

The “Setup” is the responsibility of the platform and consists of the following:

1. Create the “Legal Entity”
2. Create the “Account Holder”
3. Create the onboarding link

Those steps are to be implemented by the platform developers, integrating the Adyen APIs, before merchants can be involved.

Once the account is set up the “Onboarding” journey begins. This is taken care of by Adyen.

Finally the account is “Ready”. The platform must listen and process the incoming webhooks to confirm the onboarding status.

Let’s start the journey and look at what each step entails and what, as a developer, you need to design and implement.

Create a new platform

Check out the Get started guide to learn how to register for a new account as well as understanding all requirements and preliminary decisions to consider.

Prerequisites: API key and webhooks

Before starting the integration process, few prerequisites must be fulfilled.

API access

Create the API credential (and API key) for the Legal Entity Management API.

Create the API credential (and API key) for the Balance Platform Configuration API.

You will be using both APIs to create the information required to kick off the onboarding.

Tip: Check out the AdyenDev Postman space to access the Postman collections with predefined requests and JSON payloads for all Adyen APIs, including the platform and onboarding endpoints.

User role

Ensure the “Manage hosted onboarding themes” role has been assigned to your user account in the Balance Platform Customer Area.

Webhooks

Set up the webhooks to receive real-time updates from the verification process.

Webhooks play an essential role in ensuring an efficient onboarding process. You need to set up the “Configuration” webhook to always stay informed about any changes. For example, when the onboarding is completed or in case additional details must be provided.

Additionally, it is crucial to have the webhook in place after the seller is onboarded. For instance, if a new (financial) product is introduced, which mandates additional documentation, or an expired passport must be replaced, the webhook will be the mechanism to notify you about such events.

Seller account setup

Let’s tackle the first step: the account creation of the seller that must be onboarded onto the platform. This falls under the responsibility of the platform and therefore involves some development effort.

Each entity operating on the platform must have its own “Legal Entity”. This can be created using the Legal Entity Management API.

POST /legalEntities

{
   "type":"organization",
   "organization":{
      "legalName":"Healthy Tacos",
      "registeredAddress":{
         "country":"US"
      }
   }
}

which will return, if successful, the identifier of the newly created “Legal Entity” (ie LE000123).

Tip: You should consider adopting the Adyen Libraries for a robust and scalable integration. Avoid writing the REST API integration code. Instead work with your preferred tech stack and get access to pre-built functions, helpers, error handling and security features.

The next step is the creation of the “AccountHolder” linked to the “Legal Entity”. This step will be accomplished using the Balance Platform Configuration API.

POST /accountHolders

{
  "balancePlatform": "MY_PLATFORM_BP",
  "description":"Healthy Tacos account holder",
  "legalEntityId":"LE000123"
}

The seller account is now created and we are almost ready to start the onboarding. The last task is the creation of the Hosted Onboarding link.

Hosted Onboarding link

The Hosted Onboarding link is the URL that is provided to merchants who are invited to onboard onto the platform. It should be embedded into a page within your platform, for example in their “User Account” page.

It is crucial to note that the link expires after 4 minutes, therefore it should not be generated and stored to be used later. Instead, you should create the link on-demand by utilizing the LEM API's '/onboardingLinks' endpoint:

POST /legalEntities/{{id}}/onboardingLinks/

{
 “themeId” : “YOUR_THEME_ID”,
 "redirectUrl" : "https://your.redirect-url.com/",
 "locale" : "en-US"
}

The themeId allows you to specify a custom theme for the Hosted Onboarding experience. You can create, view and update customized onboarding themes in the Balance Platform Custom Area. A theme can have its own background image, colors and logo. The links to the Support, FAQ and Privacy pages can also be defined.

The redirectUrl property specifies the page where merchants are redirected upon completing the onboarding process. Don’t forget that they are sent to the Adyen hosted application, therefore it is very important to redirect them back to your platform at the end of the onboarding flow.

The locale property can be utilized to specify the desired language. By default, the application will use the language set in the user's browser. However, you have the option to configure the language by passing the corresponding locale, enabling customization of the link based on the market and even combining it with different themes.

Additional settings can be configured, when creating the link, to control further what the merchants can change during the onboarding.

A use case

When the platform wants to operate in Europe, it could decide to employ the language for each country (IT for Italy, NL for the Netherlands, etc.) while sharing the same custom theme (logo and branding). The platform, passing the additional settings, can also remove the possibility to edit the type and country of the “Legal Entity” which has been already set during the account setup.

Onboard your users

Once the seller account is set up and the custom theme is defined, it’s finally onboarding time!

A potential scenario involves sending an email to the sellers to access your platform, where they will find a newly generated Hosted Onboarding link. As they access the Onboarding screens, Adyen takes on the responsibility of collecting all necessary information and relevant documentation.

The happy flow

The Hosted Onboarding application will guide the merchants through a few screens:

• Enter company details and decision makers
• Upload or scan legitimate ID like passport or driving license
• Verify the bank details
• Sign the service agreement

The application is mobile-friendly and the real-time verification functionalities provide the best experience. Users can take pictures of an ID document and (where supported) choose the instant bank account verification.

To see an example of the entire hosted onboarding flow, you can watch our videos here.

In most cases the onboarding process completes smoothly. You will receive a webhook to confirm the seller is onboarded and they can start accepting payments.

Dealing with verification errors

In some cases, it may not be possible to verify all the details provided by users. Or they might be required to make modifications to the information they have submitted as well as include additional data.

The range of issues can vary, from verification errors caused by incomplete information to the rejection if a risk of fraudulent activity is detected.

When the verification is unsuccessful and the capability is denied, the webhook delivers all the information necessary to deal with it:

• “allowed” false indicates the “Account Holder” cannot operate
• “verificationStatus” can be invalid or rejected
• “problems” listing the details of what went wrong

The payload of a webhook notifying that there is missing information (i.e. bank statement) looks like:

{
  "data": {
    "accountHolder": {
      "capabilities": {
        "sendToTransferInstrument": {
          "allowed": "false",
          "enabled": "true",
          "problems": [
            {
              "entity": {
                "id": "LE00000000000000000000001",
                "type": "LegalEntity"
              },
              "verificationErrors": [
                {
                  "code": "2_8037",
                  "message": "bankStatement was missing.",
                  "remediatingActions": [
                    {
                      "code": "1_703",
                      "message": "Upload a bank statement"
                    }
                  ],
                  "type": "dataMissing"
                }
              ]
            }
          ],
          "requested": "true",
          "verificationStatus": "invalid"
        }
      },
      "description": "Test Account holder",
      "reference": "YOUR_INTERNAL_IDENTIFIER",
      "id": "AH00000000000000000000001",
      "legalEntityId": "LE00000000000000000000001",
      "status": "Active"
    },
    "balancePlatform": "YOUR_BALANCE_PLATFORM"
  },
  "environment": "test",
  "type": "balancePlatform.accountHolder.updated"
}

You should read and process the detailed information about the error(s) and rely on the “remediatingActions” to plan the next step.

Adyen uses specific verification codes to provide the most accurate feedback. Codes are unique and never change; this should allow you to create workflows that trigger the course of action based on the verification status and corresponding code.

In the majority of cases, users will be asked to provide additional information to successfully complete the onboarding. To facilitate this, make sure to notify your users that they need to come back to the platform and continue onboarding via a newly generated onboarding link. This link will redirect the users to the application where they can provide what it is missing or incorrect.

Best practices for developers

Several aspects are very important to developers. Let’s recap the essential best practices to follow for creating a seamless onboarding process.

Webhook setup

The setup of the webhook is crucial. Make sure your application endpoint can receive and correctly handle the events that Adyen will send during and after the onboarding. Implement the necessary security measures (Basic Authentication and HMAC validation).

To learn more about webhook processing and best practices, including security, error handling, and event retries, check out the "Consuming webhooks" article on the Adyen tech blog.

Custom theme

We strongly advise creating a custom theme that seamlessly integrates with the design and style of your platform. This gives the users the feeling they are always operating within your platform, enhancing the overall user experience.

By reusing your platform's logo, images, and color schemes, you maintain a consistent branding experience and a cohesive flow between the platform and applications.

Onboarding link

Remember to generate the onboarding link on demand: create the link dynamically when the user accesses a specific page, just before starting or resuming the onboarding. Avoid storing the link permanently (as it expires after 4 minutes) and never send the onboarding link by email.

The recommended approach is to make the link available in a page that is only accessible to the user, after login. Provide a way, such as a button, for the user to generate the onboarding link. Alternatively, create one on-the-fly when the user wants to access the onboarding application.

Onboarding status

While webhook is the most effective way to stay up-to-date with the status of the onboarding, it is also possible to make a GET /accountHolders/{id} request using the LEM API endpoint. The response fetches the “Account Holder” listing all capabilities and the current verification status.

Avoid excessive and unnecessary calls to the API endpoint, instead use it only when strictly necessary. In cases where webhook processing fails or there is a requirement for real-time verification of certain information, the endpoint can be used selectively to perform these checks.

Conclusion

The Adyen for Platforms Hosted Onboarding solution offers a simple and streamlined process for platform owners to implement the onboarding of merchants, reducing complexity and ensuring compliance with regulatory requirements across markets and regions.

While the application provides out-of-the-box management of onboarding flows, an intuitive mobile-friendly user interface and customizable themes, it is important for platforms to understand there is some development work.

In this article, and through the Adyen Docs site, we advised developers to implement an effective integration that blends in with the platform branding and style. By deploying webhooks, platforms receive real-time updates, reducing the duration and effort of the entire process. By following the recommended practices, developers can deliver a solution that ensures a user-friendly end-to-end onboarding experience.

Are you ready for the next step? Visit our Adyen Developer website to discover more content and resources for developers who are building the best platforms for their users.