Sweeps on the Adyen Balance Platform for Developers

Adyen for Platforms offers a comprehensive solution tailored for marketplaces that aim to deliver a flexible, robust and fully-featured platform to support their merchants and end users on a large scale. The core of every successful platform is the unique relationship built over time between the platform and its customers. Merchants process a vast number of complex transactions everyday, with different attributes and configurations, like currency, payment methods, split amounts and fees. They also need easy access to their funds, making fast and reliable payouts an indispensable tool of the platform.

In this blog, we’ll answer the following questions:

1. What are sweeps?

2. What types of sweeps exist and their use cases.

3. How to configure sweeps.

Let’s start with an example. Jan runs a very successful marketplace that allows users to buy and sell their cars in Amsterdam. As their user base grows, Jan is having trouble with making sure his users are paid out consistently at a set interval. This has proven quite troublesome as more and more users join their marketplace. Jan is looking for some kind of automation. This is where sweeps come into play, an Adyen feature that allows him full control of his payout functionality. Sweeps pull in or push out funds from a balance account based on a predefined schedule, amount, currency, and a source or a destination.

Before we delve into the specifics, let’s clarify two key terms: 

• Account holder: This refers to the user entity within the balance platform. Depending on your account structure, the account holder can either be your company, or your customers.

• Balance account: This is the account where funds are held for an account holder. All financial activity happens through balance accounts. Each account holder can have one or more balance accounts for accounting flexibility, but in most use cases, a single balance account is sufficient.

An account holder can be one of the following legal entities: Individual, Business, Nonprofit, Partnership, or Public company. To create an account holder, send a request to the /createAccountHolder endpoint. Refer to this documentation page to understand the different request parameters for each legal entity.

Account holders rely on the platforms for the benefit of their business but also for features like reliability and ease of access to their funds. The skeleton of reliability, trust and ease are equal parts of a massive pillar in this business model. The core of this trust relies on the payout functionality being spot on and easy for both the account holders and the platforms to configure and customize based on their needs. 

A sweep automatically pushes out or pulls in funds from a balance account based on a predefined schedule, amount, and source or destination. There are two types of sweeps that exist as part of the Adyen Balance Platform. 

1. The push sweep 

2. The pull sweep

The push sweep 

The push sweep is the type of sweep used for configuring payouts. Platforms use this type of sweep to send a payout to the account holders based on a configurable schedule and other additional parameters such as the currency. 

The push sweep is configured for the balance account of the account holder. This means that an account holder with multiple balance accounts can define sweeps with different configurations, based on the preferences of the business case.

The pull sweep 

The pull sweep is the type of sweep used for the auto-funding functionality on the balance platform for account holders. Platforms can use this type of sweep to pull funds into a designated balance account when a certain threshold is reached. 

Auto-funding use cases are those as old as time, where an account holder needs funds to process refunds but is below a threshold to process them successfully. At this point, the autofunding functionality configured via a pull sweep comes to the rescue by pulling in funds for operational ease. 

You can configure sweeps for balance accounts through two primary methods:

1. Customer Area 

2. API functionality 

Customer Area

You can directly configure sweeps for balance accounts via the Customer Area by performing the following steps:  

1. Log into the Customer Area using your credentials. 

2. Navigate to the account holder. 

3. Navigate to the balance account you want to configure the sweep for. 

4. On the balance account page, use the button as shown below to add a sweep configuration for the balance account.

5. Choose the type of sweep you would like to configure. For the purpose of this example, we will be proceeding with the push sweeps for payouts.

6. Once the type of sweep has been selected, you will proceed to a page with an extensive range of customization options that allow you to tailor the structure of your sweep according to your preferences.

7. Finally confirm the configuration by clicking next and viewing the summary of the sweep you are ready to create.

API functionality 

For developers, it is possible to use the Adyen Platform Configuration APIs for automating the sweep configurations for account holders. 

You can create a sweep by specifying its type and send a POST request to the /balanceAccounts/{balanceAccountId}/sweeps endpoint. You can configure the request parameters in the body of the API call as shown below. For a more detailed overview on what each of these parameters do, read our API documentation here.

Create a push sweep using a POST request:

A successful request returns the newly created push sweep.

Adyen will also asynchronously send the “balancePlatform.balanceAccountSweep.created” webhook with the sweep response. You can find an example of the webhook payload below.

In summary, we've covered sweeps using a real-life example and discussed the two types of  sweeps: push and pull. We've shown how to set these up through the Adyen Customer Area or using API calls. Going back to our introduction, Jan now has a better understanding of how this works and he can now feel more confident about the functionality as it allows him just the right amount of control over the payouts for his customers. This means that his users can continue selling and buying cars on his platform without having to worry whether they get their money on time.

Are you looking for more developer-related content? Have a look at developers.adyen.com today or let us know on Twitter what you’d like to see next!