Integration and go-live checklist

On this page, you can learn about the steps required to integrate Adyen's payment processing capabilities to your platform, and how to take your integration live.

Before you start building your integration, make sure that you have already designed your implementation with your Adyen implementation manager.

Not yet in touch with Adyen? Contact us to register your interest for Adyen for Platforms.

Review your account structure

Before you start the integration process, you must be familiar with the Adyen account structure. You’ll need this information when building the different parts of your implementation.

Every Adyen for Platforms integration must have at least the following resource types:

• Company account: Represents your core business entity and holds your merchant accounts.
• Merchant account: The account where we process payments for your users. You can have multiple merchant accounts.
• Store: Ensures that the transactions you process for your users correspond to an accurate payer statement.
• Balance platform: The accounting system in which you manage your users and funds.
• Account holder: Specifies what your user can do in your platform, for example, receive fund transfers to their balance account and payouts to their verified transfer instrument (bank account).
• Balance account: Holds the funds of your user or your platform. All financial activities in your platform, such as paying out to a bank account, happen through balance accounts.
• Legal entity: Contains information about your user, for example, the legal name, address, and tax information of the organization. Adyen uses this information to perform verification checks required by payment industry regulations.
• Transfer instrument: Your user's verified bank account where they can receive payouts.
• Business line: Contains information about your user's line of business, including their industry and source of funds.

For details on the different account structures and example use cases, see Account structures.

Get ready for development

At the end of this section you should have the API keys and the webhook configuration that you need to start integrating.

Check out Adyen’s server-side libraries

Adyen provides server-side API libraries in several languages. Installing a library is not required, but will save you development time, because a library:

• Uses the latest API version.
• Has generated models and examples to help you construct requests.
• Sends the request to Adyen using its built-in HTTP client, so you do not have to create your own.

Pick a library in the language of your choice and follow the installation instructions.

Generate and test your API keys

Adyen is an API-first payment service provider, which means that you must integrate with our APIs to build and customize your implementation. You can generate your API credentials in your Customer Area.

You need credentials for the following APIs:

To verify that your test API credentials are working, make your first requests.

curl https://balanceplatform-api-test.adyen.com/bcl/v2/balancePlatforms/{id} \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X GET

{
    "id": "YOUR_BALANCE_PLATFORM_ID",
    "status": "Active"
}

Set up webhooks

Webhooks are a crucial part of your integration. Adyen sends webhooks to communicate events in your platform, such as if your user needs to provide additional information for onboarding, or when their funds have been paid out.

1. Set up webhook endpoints on your server and build the logic for acknowledging webhooks.
2. Configure webhooks in your Customer Area.
3. Secure webhooks with HMAC signing.

Integrate components

To reduce implementation time and effort, take advantage of Adyen's prebuilt component libraries that you can seamlessly integrate into your user interface.

Components simplify the process of collecting user input for payments or during onboarding, and allows you to showcase interactive dashboards to your users, such as an overview of their transactions and other reporting data.

1. Create an authentication session from your server
   Create a session token to ensure secure communication between the component and the Adyen server.
2. Install the component library in your front end
   Install the npm package, then import the library, component, and style sheet in your front-end application.
3. Initialize the component
   1. Gather the required information on the specific library and component you want to integrate.
   2. Create a DOM element on your user interface page where you want the component to be rendered.
   3. Add a function that calls your API to retrieve and refresh an authentication session token.
   4. Initialize the component and mount it to the DOM element you created.
4. Customize the component(s)
   Customize the component to match your platform's look and feel.

Some components may require additional steps or conditions.

Onboard and verify users

Before you can start processing payments for your users and pay out to them, Adyen needs to verify their information.

You can choose from the following types of onboarding:

Hosted onboarding (recommended): Your users are directed to a page hosted by Adyen, where Adyen manages the onboarding flow and user interface. Adyen offers two different ways to implement hosted onboarding:

• Onboarding on invite: In your Customer Area, request Adyen to create an account holder for your user. You then create a hosted onboarding link to redirect your user to enter their information.
• API-initiated: Create resources and a hosted onboarding link by making API calls to several endpoints, and redirect your user to enter their information.

API-only onboarding: Build your own UI and collect required user data. You make API requests to create resources and submit the user data to Adyen. This onboarding type gives you complete control over the user journey within your platform's environment.

Choose the option that best suits your use case.

Process payments

Build your payments integration

Online payments: Build an Adyen online payments integration and checkout UI. After you build your integration, you can accept payments with cards, wallets, and local payment methods on your website and mobile app.

In-person payments: Integrate your POS app with Adyen's terminals and Terminal API. After you finish your integration, you can accept payments at the point of sale using Adyen's payment terminals.

Start processing payments

To make sure that the pay-in, settlement, and payout processes run smoothly, you must book the incoming funds and fees to the correct balance accounts. This means that you have to include information on how to split the funds between your users' balance accounts and your platform's liable balance account.

Pay out

Pay out funds to your user's bank account.

1. Listen to webhooks
   Learn which webhooks Adyen sends to inform your server of payout events.
2. Make scheduled payouts
   Set up scheduled payouts.
3. Pay out on demand
   Make on-demand payouts.

Transfer funds

Move funds between balance accounts in your balance platform, for example, to cover subscription fees or pass through chargeback costs.

1. Listen to webhooks
   Learn which webhooks Adyen sends to inform your server of internal transfer events.
2. Make scheduled transfers
   Set up scheduled transfers.
3. Transfer funds on demand
   Send funds or initiate an internal direct debit between balance accounts within your balance platform.
4. Return transferred funds
   Return funds to the original balance account without creating a new transfer.

Accounting and reconciliation

Use reports to reconcile payments and balances in your system.

1. Set up your reports credentials
   Your Adyen contact will provide you with a reports credential, which you'll need if you want to programmatically download reports.
2. Download reports
   Listen to the balancePlatform.report.created webhook to know when a report is generated and ready to be downloaded. To download a report, you must authenticate your GET requests with your report credentials.
3. Reconcile using reports
   Familiarize yourself with the common reconciliation processes at Adyen.

Go live

To take your Adyen for Platforms integration live, you need to apply for a live account. When you have your live account, follow the steps below to take your integration live.

1. Replicate your test account setup
   The setup from your test Adyen for Platforms account is not replicated to your live Adyen for Platforms account automatically.
2. Update your code base
3. Switch to live API credentials
   Get your live API credentials from your Adyen contact. Use these credentials in your live account.
4. Switch from test to live endpoints
   Change the endpoints from test to live. For example, https://balanceplatform-api-test.adyen.com/ to
   https://balanceplatform-api-live.adyen.com/.
5. Run end-to-end tests
   • Live API credentials: Make your first live API request to make sure that your live API credentials are working.
   • Legal entities: Confirm that you can create legal entities.
   • Account holders and balance accounts: Confirm you can create and retrieve account holders and balance accounts.
   • Payments:
     • Test successful payment scenarios.
     • Test your error handling scenarios, for example, when payments are declined.
   • Payouts: Confirm that your scheduled or on-demand payouts are working as expected.
   • Verification errors: Test your error handling scenarios when onboarding users.
   • Webhooks: Confirm that you can receive and accept webhooks in the live environment.
   • Reports: Confirm that you can download reports in the live environment.