This page explains the steps to integrate Adyen Capital into your existing Adyen for Platforms integration.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
| Requirement | Description |
|---|---|
| Integration type | You must have an Adyen for Platforms integration. |
| Limitations | Your user must operate in one of the supported countries/regions. |
| Setup steps | Before you begin, make sure:
|
How it works
Integrating Capital consists of the following steps:
- Review your account structure
- Complete the integration checklist for Adyen for Platforms
- Test your API keys
- Set up webhooks
- Implement Capital features
- Go live
1. Review your account structure
Before you start the integration process, you must be familiar with the account structure for Capital. You need this information to building the different parts of your implementation.
Every integration that includes Capital must have at least the following resources:
- 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.
- Grant account: allows you to track the total amount of outstanding receivables that Adyen has in relation to grants in your balance platform.
- Grant references: tracks the balances related to specific grants. These references are created when a grant is paid out.
2. Complete the integration checklist for Adyen for Platforms
Before integrating Capital, you must complete the integration steps for either the marketplace or platform model of Adyen for Platforms.
3. Test your API keys
To make API requests related to Capital, you can use the same API credentials that you generated for your marketplace or platform. If needed, you can generate your API credentials and assign roles to them in your Customer Area.
Make sure that you have the following API credentials and roles.
| API | Credential | Roles |
|---|---|---|
| Capital API Configuration API |
ws@BalancePlatform.[YourBalancePlatform] Use this API credential to make grant requests and disburse grants, create resources such as account holders and balance accounts, and request user capabilities. |
|
| Legal Entity Management API | ws_[123456]@Scope.Company_[YourCompanyAccount] Use this API credential to create and manage legal entities that contain the information required for verification checks. |
4. Set up webhooks
Adyen sends webhooks to communicate events related to your grant requests. For example, you receive a webhook when a grant is configured or when the grant funds have been paid out.
To configure webhooks:
- 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.
5. Implement Capital features
You can implement Capital features in two ways:
- By using capital components
- By using the Capital API
6. Go live
To take your Capital integration live:
- Replicate your test account setup in your live account: The Capital setup from your test account for Adyen for Platforms is not automatically replicated in your live account.
- 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 fromtesttolive. 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 requests to make sure that your live API credentials are working.
- Grant account: Create a grant account in your live environment.
- Grant offers: Confirm that you can get grant offers for users with the required capability.
- Pay out grants: Confirm that grant amounts are correctly paid out to the corresponding balance accounts or transfer instruments.
- Webhooks: Confirm that you can receive and accept webhooks in the live environment.