**Last updated**: 14 May 2025 | [**Change log**](/products/balance/changelog/)

# Balances API

Request your account details for a single account or all accounts under an entity.

Important
Make yourself familiar with our [API Principles](/products/reference/api-principles) to ensure a resilient integration.

## Get started

Ready to integrate? Use our [API Reference](/products/balance/v1/openapi) and set your headers.

## Request

There are two ways you can retrieve the details of your account:

* by [account number](#by-account-number) or
* by [entity](#by-entity)


### Request by account number

`GET`  `https://try.access.worldpay-bsh.securedataplatform.com/accounts/balance//{accountNumber}`

#### Mandatory string parameter

| Field Name | Description | Data Type/Format | Length | Validation Criteria |
|  --- | --- | --- | --- | --- |
| `accountNumber` | The account number. | String | 16 | Alphanumeric only. Special characters are restricted. |


### Response

#### Schema

br
#### Examples

Successful response example
{
  "entity": "111155",
  "accounts": [
    {
      "accountNumber": "1111550000000044",
      "accountName": "PLN account",
      "currency": "PLN",
      "clearedBalance": 1418.64,
      "unclearedBalance": 0,
      "balance": 1418.64
    }
  ]
}
Error response example
{
    "httpStatusCode": 404,
    "customCode": "ACCN15",
    "message": "Could not find details for accountNumber"
}

#### Errors

Check out our API reference for the [error code schema](/products/balance/).

### Request by entity

`GET`  `https://try.access.worldpay-bsh.securedataplatform.com/accounts/balance/?entity={entity}`

#### Mandatory string parameter

| Field Name | Description | Data Type/Format | Min-Max Length |
|  --- | --- | --- | --- |
| `entity` | Unique ID given to you during the onboarding process. | String | 32 |


### Response

##### Response examples

Successful response
{
  "entity": "111155",
  "accounts": [
    {
      "accountNumber": "1111550000000044",
      "accountName": "PLN account",
      "currency": "PLN",
      "clearedBalance": 1418.64,
      "unclearedBalance": 0,
      "balance": 1418.64
    },
    {
      "accountNumber": "1111550000000045",
      "accountName": "EUR account",
      "currency": "EUR",
      "clearedBalance": 9997.01,
      "unclearedBalance": 0,
      "balance": 9997.01
    },
    {
      "accountNumber": "1111550000000046",
      "accountName": "USD account",
      "currency": "USD",
      "clearedBalance": 2235.11,
      "unclearedBalance": 0,
      "balance": 2235.11
    }
  ]
}
Error response
{
    "httpStatusCode": 400,
    "customCode": "ACCB05",
    "message": "Schema validation failed",
    "errors": {
         "entity": "111155"
     }
}

#### Response schema

br
#### Errors

Check out our API reference for the full [error code schema](/products/balance/openapi/).