---
title: "Manage balance accounts"
description: "View and manage the balance accounts in your platform."
url: "https://docs.adyen.com/platforms/manage-balance-accounts"
source_url: "https://docs.adyen.com/platforms/manage-balance-accounts.md"
canonical: "https://docs.adyen.com/platforms/manage-balance-accounts"
last_modified: "2026-05-24T12:54:31+02:00"
language: "en"
---

# Manage balance accounts

View and manage the balance accounts in your platform.

[View source](/platforms/manage-balance-accounts.md)

A [balance account](/platforms/account-structure-resources/) is an API resource that contains information about the funds held by your user. To manage the balance accounts use the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview).

This page contains instructions for common balance account operations. These operations are part of a larger process which includes [verification](/platforms/verification-overview) and [onboarding steps](/platforms/onboard-users/onboarding-steps).

## Create a balance account

You can create balance accounts manually using the Configuration API. To create a balance account:

1. Make a POST [/balanceAccounts](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts) request using the account holder ID you want to attach the balance account to.

   **Create a balance account**

   #### curl

   ```bash
   curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts \
   -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
   -H 'content-type: application/json' \
   -X POST \
   -d '{
      "accountHolderId": "AH00000000000000000000001",
      "description": "AccountHolder Primary Balance Account"
   }'
   ```

   #### Java

   ```java
   // Adyen Java API Library v33.0.0
   import com.adyen.Client;
   import com.adyen.enums.Environment;
   import com.adyen.model.balanceplatform.*;
   import java.time.OffsetDateTime;
   import java.util.*;
   import com.adyen.service.balancePlatform.*;

   Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST);

   // Create the request object(s)
   BalanceAccountInfo balanceAccountInfo = new BalanceAccountInfo()
     .accountHolderId("AH00000000000000000000001")
     .description("AccountHolder Primary Balance Account");

   // Send the request
   BalanceAccountsApi service = new BalanceAccountsApi(client);
   BalanceAccount response = service.createBalanceAccount(balanceAccountInfo, null);
   ```

   #### PHP

   ```php
   <?php
   // Adyen PHP API Library v24.0.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Model\BalancePlatform\BalanceAccountInfo;
   use Adyen\Service\BalancePlatform\BalanceAccountsApi;

   $client = new Client();
   $client->setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY");
   $client->setEnvironment(Environment::TEST);


   // Create the request object(s)
   $balanceAccountInfo = new BalanceAccountInfo();
   $balanceAccountInfo
     ->setAccountHolderId("AH00000000000000000000001")
     ->setDescription("AccountHolder Primary Balance Account");

   // Send the request
   $service = new BalanceAccountsApi($client);
   $response = $service->createBalanceAccount($balanceAccountInfo);
   ```

   #### C\#

   ```cs
   // Adyen .net API Library v28.0.0
   using Adyen;
   using Environment = Adyen.Model.Environment;
   using Adyen.Model;
   using Adyen.Model.BalancePlatform;
   using Adyen.Service.BalancePlatform;

   var config = new Config()
   {
       XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY",
       Environment = Environment.Test
   };
   var client = new Client(config);

   // Create the request object(s)
   BalanceAccountInfo balanceAccountInfo = new BalanceAccountInfo
   {
     AccountHolderId = "AH00000000000000000000001",
     Description = "AccountHolder Primary Balance Account"
   };

   // Send the request
   var service = new BalanceAccountsService(client);
   var response = service.CreateBalanceAccount(balanceAccountInfo);
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v23.3.0
   const { Client, BalancePlatformAPI } = require('@adyen/api-library');

   const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" });

   // Create the request object(s)
   const balanceAccountInfo = {
     accountHolderId: "AH00000000000000000000001",
     description: "AccountHolder Primary Balance Account"
   }

   // Send the request
   const balancePlatformAPI = new BalancePlatformAPI(client);
   const response = balancePlatformAPI.BalanceAccountsApi.createBalanceAccount(balanceAccountInfo);
   ```

   #### Go

   ```go
   // Adyen Go API Library v17.0.0
   import (
     "context"
     "github.com/adyen/adyen-go-api-library/v17/src/common"
     "github.com/adyen/adyen-go-api-library/v17/src/adyen"
     "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform"
   )
   client := adyen.NewClient(&common.Config{
     ApiKey:      "ADYEN_BALANCE_PLATFORM_API_KEY",
     Environment: common.TestEnv,
   })

   // Create the request object(s)
   balanceAccountInfo := balancePlatform.BalanceAccountInfo{
     AccountHolderId: "AH00000000000000000000001",
     Description: common.PtrString("AccountHolder Primary Balance Account"),
   }

   // Send the request
   service := client.BalancePlatform()
   req := service.BalanceAccountsApi.CreateBalanceAccountInput().BalanceAccountInfo(balanceAccountInfo)
   res, httpRes, err := service.BalanceAccountsApi.CreateBalanceAccount(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v13.3.0
   import Adyen

   adyen = Adyen.Adyen()
   adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY"
   adyen.client.platform = "test" # The environment to use library in.

   # Create the request object(s)
   json_request = {
     "accountHolderId": "AH00000000000000000000001",
     "description": "AccountHolder Primary Balance Account"
   }

   # Send the request
   result = adyen.balancePlatform.balance_accounts_api.create_balance_account(request=json_request)
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v10.1.1
   require "adyen-ruby-api-library"

   adyen = Adyen::Client.new
   adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY'
   adyen.env = :test # Set to "live" for live environment

   # Create the request object(s)
   request_body = {
     :accountHolderId => 'AH00000000000000000000001',
     :description => 'AccountHolder Primary Balance Account'
   }

   # Send the request
   result = adyen.balancePlatform.balance_accounts_api.create_balance_account(request_body)
   ```

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v23.3.0
   import { Client, BalancePlatformAPI, Types } from "@adyen/api-library";

   const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" });

   // Create the request object(s)
   const balanceAccountInfo: Types.balancePlatform.BalanceAccountInfo = {
     accountHolderId: "AH00000000000000000000001",
     description: "AccountHolder Primary Balance Account"
   };

   // Send the request
   const balancePlatformAPI = new BalancePlatformAPI(client);
   const response = balancePlatformAPI.BalanceAccountsApi.createBalanceAccount(balanceAccountInfo);
   ```

2. In the response, note the `id`. You need this ID to:

   * [View a balance account](#view-balance-accounts)
   * [Update a balance account](#update-balance-account)
   * [Close a balance account](#close-a-balance-account)

   **Create balance account response**

   ```json
   {
       "accountHolderId": "AH00000000000000000000001",
       "defaultCurrencyCode": "EUR",
       "description": "Main Account",
       "reference": "Referee",
       "timeZone": "Europe/Amsterdam",
       "balances": [
           {
               "available": 0,
               "balance": 0,
               "currency": "EUR",
               "pending": 0,
               "reserved": 0
           }
       ],
       "id": "BA00000000000000000000001",
       "status": "active"
   }
   ```

## View balance accounts

To view the balance accounts and the available balances of your account holder, you can either use your [Customer Area](https://ca-test.adyen.com/) or make an API request.

### Tab: Customer Area

To view balance accounts in your [Customer Area](https://ca-test.adyen.com/):

1. Select **Accounts & balances** > **Balance accounts**.

2. In the **Balance platform** dropdown, select the balance platform. You can view balance accounts from one balance platform at a time.

3. Select a **Balance account ID** to view more details, such as the available balances.

Alternatively, enter a balance account ID in the **Search** menu to find a balance account.

### Tab: API

To get balance accounts, use the following endpoints:

* GET [/accountHolders/{id}/balanceAccounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}/balanceAccounts): get a list of the balance accounts of an account holder. This endpoint returns a paginated list of balance accounts.
* GET [/balanceAccounts/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)): get the details of a balance account, including a list of [balances](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balanceAccounts/{id}__resParam_balances) associated with the balance account.
* GET [/balanceAccounts/{id}/paymentInstruments](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/paymentInstruments): get a list of the payment instruments (cards) associated with the balance account.

## Update a balance account

To update a balance account, make a PATCH [/balanceAccounts/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/patch/balanceAccounts/{id}) request. The following example shows how to update the description of a balance account.

**Change the description of a balance account**

#### curl

```bash
curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001 \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X PATCH \
-d '{
    "description":"Balance account for new business"
}'
```

#### Java

```java
// Adyen Java API Library v33.0.0
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.model.balanceplatform.*;
import java.time.OffsetDateTime;
import java.util.*;
import com.adyen.service.balancePlatform.*;

Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST);

// Create the request object(s)
BalanceAccountUpdateRequest balanceAccountUpdateRequest = new BalanceAccountUpdateRequest()
  .description("Balance account for new business");

// Send the request
BalanceAccountsApi service = new BalanceAccountsApi(client);
BalanceAccount response = service.updateBalanceAccount("id", balanceAccountUpdateRequest, null);
```

#### PHP

```php
<?php
// Adyen PHP API Library v24.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\BalancePlatform\BalanceAccountUpdateRequest;
use Adyen\Service\BalancePlatform\BalanceAccountsApi;

$client = new Client();
$client->setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY");
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$balanceAccountUpdateRequest = new BalanceAccountUpdateRequest();
$balanceAccountUpdateRequest
  ->setDescription("Balance account for new business");

// Send the request
$service = new BalanceAccountsApi($client);
$response = $service->updateBalanceAccount('id', $balanceAccountUpdateRequest);
```

#### C\#

```cs
// Adyen .net API Library v28.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.BalancePlatform;
using Adyen.Service.BalancePlatform;

var config = new Config()
{
    XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
BalanceAccountUpdateRequest balanceAccountUpdateRequest = new BalanceAccountUpdateRequest
{
  Description = "Balance account for new business"
};

// Send the request
var service = new BalanceAccountsService(client);
var response = service.UpdateBalanceAccount("id", balanceAccountUpdateRequest);
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v23.3.0
const { Client, BalancePlatformAPI } = require('@adyen/api-library');

const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" });

// Create the request object(s)
const balanceAccountUpdateRequest = {
  description: "Balance account for new business"
}

// Send the request
const balancePlatformAPI = new BalancePlatformAPI(client);
const response = balancePlatformAPI.BalanceAccountsApi.updateBalanceAccount("id", balanceAccountUpdateRequest);
```

#### Go

```go
// Adyen Go API Library v17.0.0
import (
  "context"
  "github.com/adyen/adyen-go-api-library/v17/src/common"
  "github.com/adyen/adyen-go-api-library/v17/src/adyen"
  "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform"
)
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_BALANCE_PLATFORM_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
balanceAccountUpdateRequest := balancePlatform.BalanceAccountUpdateRequest{
  Description: common.PtrString("Balance account for new business"),
}

// Send the request
service := client.BalancePlatform()
req := service.BalanceAccountsApi.UpdateBalanceAccountInput("id").BalanceAccountUpdateRequest(balanceAccountUpdateRequest)
res, httpRes, err := service.BalanceAccountsApi.UpdateBalanceAccount(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v13.3.0
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY"
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "description": "Balance account for new business"
}

# Send the request
result = adyen.balancePlatform.balance_accounts_api.update_balance_account(request=json_request, id="id")
```

#### Ruby

```rb
# Adyen Ruby API Library v10.1.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY'
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :description => 'Balance account for new business'
}

# Send the request
result = adyen.balancePlatform.balance_accounts_api.update_balance_account(request_body, 'id')
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v23.3.0
import { Client, BalancePlatformAPI, Types } from "@adyen/api-library";

const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" });

// Create the request object(s)
const balanceAccountUpdateRequest: Types.balancePlatform.BalanceAccountUpdateRequest = {
  description: "Balance account for new business"
};

// Send the request
const balancePlatformAPI = new BalancePlatformAPI(client);
const response = balancePlatformAPI.BalanceAccountsApi.updateBalanceAccount("id", balanceAccountUpdateRequest);
```

## Close a balance account

In some scenarios, you might want to close an account holder's balance account. For example, an account holder that has separate balance accounts for their businesses might want to close one of their businesses.

To permanently close a balance account:

1. Check if the balance account has [zero balance](#view-balance-accounts). You can only close empty balance accounts, so if there are funds left, you must [pay out](/platforms/managed-payouts) or [transfer](/platforms/internal-fund-transfers) any remaining balance.
2. Close a balance account by [updating the balance account](#update-balance-account) and setting the `status` to **Closed**.

If an account holder discontinues their contractual relationship with your platform, you can also [permanently deactivate the account holder](/platforms/manage-account-holders#permanent-deactivation).