Integration and go-live checklist

Checklist for building and taking your Adyen for Platforms integration live.

Adyen APIs Postman collections

Fork our Postman collections in your private workspace to start testing API calls with your own credentials.

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 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 and manage payment methods, stores, and automatic split payments for your users.

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

Use the API key for your ws@BalancePlatform.[YourBalancePlatform] API credential.

If the call was successful, you receive an HTTP 200 result code along with the id and status of your balance platform.

Use the API key for your ws_[123456]@Scope.Company_[YourCompanyAccount] API credential.

If the call was successful, you receive an HTTP 200 result code along with the id and type of the legal entity you created.

Use the API key for your ws@Company.[YourCompanyAccount] API credential. Your Adyen contact also provides you with the name of your merchant account, which you must include in your payments request.

If your account is set up correctly and the request is successful, you receive a response containing an HTTP 200 result code along with resultCode: Authorised. You have just made a successful test credit card payment of 10 EUR!

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.

Set up webhook endpoints on your server and build the logic for acknowledging webhooks.
Configure webhooks in your Customer Area.
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.

Gather resource IDs
Get the resource IDs linked to the user, and determine which role is required for the use of the component.
Get authentication session token
Generate a session token for secure communication between backend and frontend.
Install and import the npm package
Install the node package, and import the package and the style sheet in your application
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.
Customize the component
You can customize components to match your platform'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.

Identify and collect the required information
Check the required information based on the country or region in which your user operates.
Create legal entities
Create the required legal entity resources for your user, including the main and supporting legal entities.
Associate legal entities
Link supporting legal entities to the main legal entity of your user.
Create the account holder
Create an account holder and link it to main legal entity.
Create business lines
Create business lines to provide Adyen with information about your users' line of business, such as their industry and sales channels.
Create stores
Create stores to ensure that payments are processed in a compliant manner and settled with the correct user.
Add payment methods
Configure which payment methods you want to accept in each store.
Create the hosted onboarding link
Generate the link for the onboarding page, through which your user can provide the information required for verification checks.
Create balance accounts
Create balance accounts to hold the funds of your user.
Get verification updates
Get verification status updates via webhooks, and resolve verification errors if necessary.

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.

You can configure your user's store to automatically apply your billing logic to all payments by creating split configuration profiles. For example, you can deduct your platform's commission and the transaction fees, or choose how to book potential chargebacks. This means that you don't need to send split instructions in every payment, capture, refund, or chargeback.

Create split configuration profiles
Create profiles with the conditions that determine how to split the transaction amount between balance accounts.
Link the profile to you user's store
Associate the split configuration profile with your user's store.

The core of your Adyen integration is being able to process payments and handle their subsequent states. If you don't automate payment splits, or if you want to overwrite the automatic split instructions, you can split individual transactions using the Checkout API.

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

The core of your Adyen integration is being able to process payments and handle their subsequent states. If you don't automate payment splits, you can split individual transactions using the Terminal API.

Split payments
Split the payment amount at authorization or at capture.
Split refunds
Book the refund amount to multiple balance accounts.
Handle transaction fees
Define the balance accounts from which you want to deduct the fees incurred by transactions.
Configure tipping (gratuity)
Select the balance accounts to which you want to book tips added to the payment.

Pay out

Pay out funds to your user's bank account.

Listen to webhooks
Learn which webhooks Adyen sends to inform your server of payout events.
Make scheduled payouts
Set up scheduled payouts.
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.

Listen to webhooks
Learn which webhooks Adyen sends to inform your server of internal transfer events.
Make scheduled transfers
Set up scheduled transfers.
Transfer funds on demand
Send funds or initiate an internal direct debit between balance accounts within your balance platform.
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.

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

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.
Update your code base
Switch to live API credentials
Get your live API credentials from your Adyen contact. Use these credentials in your live account.
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/.
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.