**Last updated**: 14 May 2025 | [**Change log**](/access/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](/access/products/reference/api-principles) to ensure a resilient integration.

## Get Started

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

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

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


## Request by account number

`GET`  `https://try.access.worldpay-bsh.securedataplatform.com/accounts/{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

### Examples

Successful response example

```json
{
  "entity": "111155",
  "accounts": [
    {
      "accountNumber": "1111550000000044",
      "accountName": "PLN account",
      "currency": "PLN",
      "clearedBalance": 1418.64,
      "unclearedBalance": 0,
      "balance": 1418.64
    }
  ]
}
```

Error response example

```json
{
    "httpStatusCode": 404,
    "customCode": "ACCN15",
    "message": "Could not find details for accountNumber"
}
```

### Schema

br
#### Errors

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

## Request by entity

`GET`  `https://try.access.worldpay-bsh.securedataplatform.com/accounts/?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 | 1-32 |


## Response

### Response examples

Successful response

```json
{
  "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

```json
{
    "httpStatusCode": 400,
    "customCode": "ACCB05",
    "message": "Schema validation failed",
    "errors": {
         "entity": "111155"
     }
}
```

### Schema

br
#### Errors

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