Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Balance accounts

Create balance accounts to hold your user's funds.

After you create account holders, you need to create a balance account resource to hold their funds. The balance account is to which funds from payments are settled and from which funds are paid out.

To use their balance account, the account holder must have the capabilities to use it.

In most cases, one balance account for an account holder is sufficient, but there are some scenarios when you might need to create multiple balance accounts. For example, if an account holder has different businesses and would like to keep funds and accounting history separate for each line.

Before you begin

Make sure that:

Create a balance account

All of the account holder's transactions such as payouts and settled payments are processed against their balance account.

To create a balance account, make a POST /balanceAccounts request specifying the accountHolderId to be associated with the balance account. In your request, you can also include a human-readable description to help you differentiate between multiple balance accounts under one account holder.

This example shows how you can create a balance account for an account holder with id AHA1B2C3D4E5F6G7H8I9J0.

Create balance account
curl \
-H "content-type: application/json" \
-d '{
  "{hint:Free-text field}description{/hint}":"S.Hopper - Main balance account"

The response returns the balanceAccount resource, identified by its unique id. The response also includes the balances array that contains information about the account's funds. By default, the first balance account that you create for an account holder is assigned as their primary balance account. To change their primary balance account, you can update the account holder.

  "defaultCurrencyCode": "EUR",
  "description":"S.Hopper - Main balance account",
  "balances": [
            "available": 0,
            "balance": 0,
            "currency": "EUR",
            "reserved": 0

After you create a balance account, get updates about whether the account holder has the required capabilities to process payments and payouts. The account holder can start using the balance account to process payments and payouts if they have the required capabilities.

See also