Platforms integration and go live checklist

On this page, you can find the checks that you can perform to make sure you have set up your Adyen for Platforms integration correctly before you go live.

Requirements

The integration checklist and the go live checklist on this page assume that you have set up a test integration and that you are familiar with the Adyen for Platforms integration options and choices. If you haven't started yet, check out the Platforms quick start guide.

The choices you make have an impact how and what you should verify for your integration. Make sure that you have made a decision on how you:

• Collect information necessary for verifying sub-merchants; staggered or all at once.
• Onboard sub-merchants as account holders; using a Hosted Onboarding Page (HOP) or using your own onboarding flow.
• Handle payouts; automatically trigger scheduled payouts to bank accounts, or manually send payouts to bank accounts or eligible cards.

Also, make sure that you are familiar with:

• The account structure of Adyen for Platforms.
• The endpoints in the Platforms API and the error codes.
• The Adyen for Platforms reports: the balance report, the payments accounting report and the payout report (for automatic payouts only).

Integration checklist

Onboard a test sub-merchant as an account holder, test a payment and test your integration before you configure your live environment, process real payments and start payouts. Follow the steps in this checklist:

• Step 1: Verify your test account
• Step 2: Test your onboarding and verification process
• Step 3: Processing payments
• Step 4: Verify payouts
• Step 5: Set up and test notifications
• Step 6: Reconcile transactions using reports

Step 1: Verify your test account

Before you start your integration test, check that you have an Adyen for Platforms test account with the required API credentials. You can only verify your integration if these are in place.

1. Log in to your test Customer Area with your Adyen for Platforms test account.
2. Select your platform merchant account, and then Accounts > API credentials.
3. Check that you have API credentials for your platform account and for processing payments:
   1. Platform: ws_[123456]@MarketPlace.[YourPlatformAccount].
   2. Payments: ws@Company.[YourCompanyAccount].
4. By default, the cards payment method is added to your platform test account. If you want to test other payment methods, make sure you request them first.

Step 2: Test your onboarding and verification process

Configure verification notifications and then sign up, onboard a sub-merchant as an account holder, and perform checks to verify that your process works. Test the process that you have chosen: using a Hosted Onboarding Page or using your own onboarding flow.

Set up verification notifications

Because the verification process is such an important part of your platform, we strongly recommend that you set up the notifications ACCOUNT_HOLDER_CREATED, ACCOUNT_HOLDER_UPDATED, ACCOUNT_HOLDER_STATUS_CHANGE and ACCOUNT_HOLDER_VERIFICATION to be able to fully verify that your onboarding process works.

Once you go live, you will use these notifications to monitor an account holder's verification status, so that you can take the appropriate follow-up action and communicate with account holder about their onboarding status.

1. Set up verification notifications.
   Create a notification configuration for the following notification types:
   • ACCOUNT_HOLDER_CREATED
   • ACCOUNT_HOLDER_UPDATED
   • ACCOUNT_HOLDER_STATUS_CHANGE
   • ACCOUNT_HOLDER_VERIFICATION
2. Expose an endpoint to handle notifications.
   By exposing an endpoint, you make sure that you can accept notifications.
3. Test the notifications while you test your onboarding process.
   Continue with the onboarding verification steps in using a Hosted Onboarding Page or using your own onboarding flow to verify that the notifications work.

Onboard using a Hosted Onboarding Page (HOP)

Sign up, onboard a sub-merchant as an account holder, and perform a check to verify that the process works.

You can use the details from the Adyen for Platforms test scenarios when you fill out the Hosted Onboarding Page.

1. Create an account holder.
   Create an account holder with a POST /createAccountHolder request. The minimum required information depends on the legal entity type and the country where the account holder is based.
2. Test your Hosted Onboarding Page.
   • Start the verification process and get the HOP URL.
   • When you redirect the sub-merchant to your return URL, inform them of their onboarding progress based on the notification webhooks you receive.
   • Look at the notifications to determine if the sub-merchant is successfully onboarded as an account holder, stopped the process or that you require additional information to complete the verification.

Onboard using your own verification process

When you build your own verification process, you need a webpage or an app that sub-merchants can use to fill out their information.

To test your onboarding process, make sure that you have a webpage or an app ready to collect the required information, and that you understand how to send the information to Adyen. See Build your own implementation for more information.

You can use the details from the Adyen for Platforms test scenarios when you fill out your onboarding webpage or app.

1. Create an account holder.
   Create an account holder for with a POST /createAccountHolder request. The minimum required information depends on the legal entity type and the country where the account holder is based.
2. Test your webpage or app: onboard a sub-merchant as an account holder.
   • On your webpage or app, collect the relevant details based on country requirements and their legal entity type. Send the information to Adyen with a POST /updateAccountHolder request.
   • Look at the notifications to determine if the sub-merchant is successfully onboarded as an account holder, stopped the process or that you require additional information to complete the verification.

Step 3: Processing payments

When a customer pays on your platform, you can automatically split these funds between multiple accounts. With every payment, capture, or refund you can customize the split between any number of accounts in your platform and amounts including your liable account. How you want to split your payments, and at what stage in the payment - immediately at authorisation or later at capture - is your decision. For more information, see processing payments.

1. Provide split instructions
   Provide an array of splits objects in the /payments call.

2. Check if split payments work
   Test a split payment with your preferred way of splitting with a test card number. To check what happens to the payment, see payment statuses.

We recommend to test the following:

• Split at authorization
• Split at capture
• Split a refund
• Chargebacks and fund transfer

Step 4: Verify payouts

To be able to perform payouts, account holders have to pass the verification checks and you have to know the accountCode and, for manual payouts, the accountHolderCode. Your platform's liable account also has its own accountCode. For more information, see payouts and accounts.

1. Test a one-off payout
   Use the test account holder and make a POST /payoutAccountHolder request.
2. Verify the payout
   Check that you get a successful 200 response to confirm that the payout is successful.

You can also set up and test notifications for payouts, see the next step.

Step 5: Set up and test notifications

Because the requests you send to the Platforms API are asynchronous, you have to set up notification webhooks to know the final result of the request. In step 2, you set up and tested the essential verification checks. In this step, you verify any other notifications that you want to use.

You configure notification webhooks to be able to get notifications of:

• The verification process, as mentioned earlier.
• Status changes of your accounts and account holders, as mentioned earlier.
• Fund management: notifications of payouts, transfers and refunds.
• Availability of reports.

For more information, see Notifications.

1. Create a notification configuration.
   Configure a notification configuration for the notifications that you want to receive.
2. Test your notification configuration.
   Follow the steps in the documentation to test your notification configuration.

Step 6: Reconcile transactions using reports

Use the reports generated in the test environment to test your reconciliation processes.

For more information on how you can use the reports, refer to Reconcile transactions through reports.

Make sure that you are able to:

1. Download reports.
2. Run your reconciliation process.

Go live checklist

After you have built out and tested your Adyen for Platforms integration, you will want to go live. When you are ready, follow these steps:

1. Request your account to be taken live
   Make sure that you have signed the Adyen for Platforms contract to get a live account. Your sales or account manager will help you with this process.
2. Access the live Customer Area
   Once you get an email confirmation that your live account is ready, use the live credentials to log in to the live Customer Area.
3. Update account settings
   When your account is taken live, some settings are copied over, but you need to update the settings for the following:
   • Notifications
   • Report subscriptions
   • API responses
   • Shopper statements for payouts and payments, aligned with your sales or account manager.
   • Recurring payment details (if applicable)
4. Set up risk configurations
   It is important that risk management is set up to handle live transactions, including selecting a risk profile that best matches your business.
5. Add a platform payout account
   Provide information for the payout account where you want to receive payments for the platform merchant account.
6. Request additional payment methods
   Review the payment methods in your Adyen merchant account. Based on where your platform is located, you will have some default payment methods that are ready for use. You can add more payment methods. Once your platform is live, onboarded and verified account holders can offer all the payment methods that you add to your platform merchant account.
7. Update code base
   Update your code base and platform merchant account settings.
   • Switch to live API credentials
     Generate API keys in your live Customer Area. Copy these keys to your live platform.
   • Switch your test endpoints to your live, custom URLs
     Change the Platforms API endpoints that you used to test your integration to live endpoints.
     For example, to change the Account API from test to live, change https://cal-test.adyen.com/cal/services/Account/v5 to https://cal-live.adyen.com/cal/services/Account/v5.
     Also change the payment endpoints to live.

8. End-to-end test
   Make sure that your platform can handle the entire payment lifecycle from authorization and refusals through payout and reconciliation. We suggest testing the following:

   • Payments:

     • Test the happy flow by making payments with real cards, and payments with real details for other payment methods that you support.
     • Test non-happy payment flows to ensure your integration can handle errors and refusal reasons.

     • Test the 3D Secure flow, if you implemented that.

   • Payment modifications, like cancellations and refunds.

   • Notification webhooks: Confirm you are able to acknowledge any notification type with an [accepted] response, to prevent notifications being queued.

   • Order handling.

   • Bank statements: Verify that payments appear correctly on the shopper's bank statement.

   • Payouts: Confirm you can onboard merchants, perform verification checks and can send and receive payouts.

   • Reconciliation: Confirm your system completes the reconciliation process.

See also