Integration and go-live checklist

On this page, you can learn about the steps required to integrate Adyen's payment processing capabilities to your marketplace, 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.
• 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 don't 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:

API	Credential	Description
Configuration API Transfers API	ws@BalancePlatform.[YourBalancePlatform]	Use these APIs to create account holders and balance accounts, schedule payouts, transfer funds, or make one-off payouts.
Legal Entity Management API	ws_[123456]@Scope.Company_[YourCompanyAccount]	Use this API to create and manage legal entities that contain the information required for verification checks.
Checkout API Management API	ws@Company.[YourCompanyAccount]	Use these APIs to process payments for your users.

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

Set up webhooks

Webhooks are a crucial part of your integration. Adyen sends webhooks to communicate events in your marketplace, 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.

Adyen for Platforms 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. Gather resource IDs
   Get the resource IDs linked to the user, and determine which role is required for the use of the component.
2. Get authentication session token
   Generate a session token for secure communication between backend and frontend.
3. Install and import the npm package
   Install the node package, and import the package and the style sheet in your application
4. 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.
   3. Add a function to generate an authentication session token.
   4. Initialize and mount the component to the container you created.
5. Customize the component
   You can customize components to match your marketplace's look and feel.

Specific components may require additional steps or conditions.

Onboard and verify users

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

Adyen provides two ways to integrate the onboarding process into your implementation:

• Hosted onboarding: This option involves implementing fewer API calls and allows you to redirect your user to an Adyen-hosted page, where we manage the onboarding flow and interface.
• API-only onboarding: With this option, you need to develop your own UI and make API calls to gather and send user data to Adyen. This onboarding type gives you complete control over the user journey within your platform's environment.

Process payments

Build your payments integration

To process payments, you must first 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.

Start processing online payments

The core of your Adyen integration is being able to process payments and handle their subsequent states. 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.

You can split individual transactions using the Checkout API.

1. Split payments
   Split the payment amount at authorization or at capture.
2. Split refunds
   Book the refund amount to multiple balance accounts.
3. Split chargebacks
   Split the chargeback amount between multiple balance accounts.
4. Handle transaction fees
   Define the balance accounts from which you want to deduct the fees incurred by transactions.

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.