Search

Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Manage accounts

Retrieve information about account holders and balance accounts.

After you create account holders and balance accounts, you can use the Balance Platform API to:

Update an existing account holder

After creating an account holder resource, you might need to update the resource at a later time to change its status or to link it to a legal entity resource. You can update an account holder resource with a PATCH /accountHolders/{id} request.

Link account holder to legal entity

The legal entity resource contains information required for Adyen to perform Know Your Customer (KYC) verification checks. You need to link the legal entity resource to the account holder. When the legal entity passes the KYC checks, you will be able to create and issue cards to the account holder.

Here is how you would update an account holder resource to link the legalEntityId.

Link the legal entity resource
curl https://balanceplatform-api-test.adyen.com/bcl/v1/accountHolders/AHA1B2C3D4E5F6G7H8I9J0 \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-X PATCH \
-d '{
    "legalEntityId":"LE32272223222D5CKDZFL7DQC"
}'

Retrieve account holders

To get the account holder details, make a GET /accountHolders/{id} request, where id is the unique identifier returned when you created the account holder.

Get account holder details
curl https://balanceplatform-api-test.adyen.com/bcl/v1/accountHolders/AHA1B2C3D4E5F6G7H8I9J0 \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
Response
{
    "balancePlatform": "YOUR_BALANCE_PLATFORM",
    "contactDetails": {
        "address": {
            "city": "Amsterdam",
            "country": "NL",
            "houseNumberOrName": "274",
            "postalCode": "1020CD",
            "street": "Brannan Street"
        },
        "email": "s.hopper@example.com",
        "phone": {
            "number": "+315551231234",
            "type": "Mobile"
        }
    },
    "description": "S.Hopper - Staff 123",
    "id": "AH32272223222B5BRQZLD2M7S",
    "status": "Active"
}

Retrieve balance accounts

After you have created balance accounts, you might want to see the status of each, or to see the balance accounts associated with an account holder.

Get the details of a balance account

Get the details of a balance account with a GET /balanceAccounts/{id} request, specifying the unique id returned when you created the balance account. This endpoint returns the specific balanceAccount resource, including a list of balances and paymentInstruments (cards) associated with the balance account.

Get balance account details
curl https://balanceplatform-api-test.adyen.com/bcl/v1/balanceAccounts/BA3227C223222H8NLP6JQC3FD \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
Response
 {
     "accountHolderId": "AHA1B2C3D4E5F6G7H8I9J0",
     "defaultCurrencyCode": "EUR",
     "description": "Main balance account",
     "balances": [
         {
             "available": 12500,
             "balance": 12500,
             "currency": "EUR",
             "reserved": 0
         }
     ],
     "id": "BA3227C223222H8NLP6JQC3FD",
     "paymentInstruments": [
         {
             "id": "PI3227C223222B5BPCMFXD2XG"
         }
     ],
     "status": "Active"
 }

Get the account holder's balance accounts

Use GET /accountHolders/{id}/balanceAccounts to get a collection of balanceAccount resources associated with the specific accountHolder.

Because an account holder can have multiple balance accounts, we paginate the results to make the response more manageable. Use the query parameters offset and limit to page through the items. By default, we limit the number of items returned per page to 10.

Here is an example of how you would limit the page items to 2 and to skip the first 4 items:

Get account holder's balance accounts
curl https://balanceplatform-api-test.adyen.com/bcl/v1/accountHolders/AHA1B2C3D4E5F6G7H8I9J0/balanceAccounts?limit=2&offset=4 \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \

The response returns the list, along with a hasNext and hasPrevious boolean parameters which indicate if there are more items in the previous or next page.

Response
{
    "balanceAccounts": [
        {
            "accountHolderId": "AHA1B2C3D4E5F6G7H8I9J0",
            "defaultCurrencyCode": "EUR",
            "id": "BA3227C223222H8NLP6JQC3FD",
            "status": "Active"
        },
        {
            "accountHolderId": "AHA1B2C3D4E5F6G7H8I9J0",
            "defaultCurrencyCode": "EUR",
            "id": "BA32272223222B5BRR27D2M7B",
            "status": "Active"
        }
    ],
    "hasNext": "true",
    "hasPrevious": "true"
}

Next steps