**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


```json
{
  "$ref": "#/components/schemas/AccountResponse",
  "components": {
    "schemas": {
      "Account": {
        "type": "object",
        "properties": {
          "accountNumber": {
            "type": "string",
            "description": "The account number.",
            "nullable": true,
            "example": "1111557890987654"
          },
          "accountName": {
            "type": "string",
            "description": "The name of the account. (This is given to you during onboarding and typically consists of your merchant name followed by the currency code.)",
            "nullable": true,
            "example": "Etsy GBP"
          },
          "currency": {
            "type": "string",
            "description": "The [ISO 4217 currency codes](/products/reference/supported-countries-currencies#iso-currency-codes) of the account.",
            "nullable": true,
            "example": "GBP"
          },
          "clearedBalance": {
            "type": "number",
            "description": "The cleared balance.",
            "format": "double",
            "example": 142.5
          },
          "unclearedBalance": {
            "type": "number",
            "description": "The uncleared balance.",
            "format": "double",
            "example": 100.8
          },
          "balance": {
            "type": "number",
            "description": "The total balance.",
            "format": "double",
            "example": 243.5
          },
          "accountStatus": {
            "type": "string",
            "description": "The status of the account.",
            "nullable": true,
            "example": "ACTIVE"
          }
        },
        "additionalProperties": false
      },
      "AccountResponse": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "string",
            "description": "Your unique 6-digit ID given to you during the onboarding process.",
            "nullable": true,
            "example": "111155"
          },
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Account"
            },
            "description": "Collection of account details.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "The GET account response."
      }
    }
  }
}
```

br
#### 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"
}
```

#### 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

```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"
     }
}
```

#### Response schema


```json
{
  "$ref": "#/components/schemas/AccountResponse",
  "components": {
    "schemas": {
      "Account": {
        "type": "object",
        "properties": {
          "accountNumber": {
            "type": "string",
            "description": "The account number.",
            "nullable": true,
            "example": "1111557890987654"
          },
          "accountName": {
            "type": "string",
            "description": "The name of the account. (This is given to you during onboarding and typically consists of your merchant name followed by the currency code.)",
            "nullable": true,
            "example": "Etsy GBP"
          },
          "currency": {
            "type": "string",
            "description": "The [ISO 4217 currency codes](/products/reference/supported-countries-currencies#iso-currency-codes) of the account.",
            "nullable": true,
            "example": "GBP"
          },
          "clearedBalance": {
            "type": "number",
            "description": "The cleared balance.",
            "format": "double",
            "example": 142.5
          },
          "unclearedBalance": {
            "type": "number",
            "description": "The uncleared balance.",
            "format": "double",
            "example": 100.8
          },
          "balance": {
            "type": "number",
            "description": "The total balance.",
            "format": "double",
            "example": 243.5
          },
          "accountStatus": {
            "type": "string",
            "description": "The status of the account.",
            "nullable": true,
            "example": "ACTIVE"
          }
        },
        "additionalProperties": false
      },
      "AccountResponse": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "string",
            "description": "Your unique 6-digit ID given to you during the onboarding process.",
            "nullable": true,
            "example": "111155"
          },
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Account"
            },
            "description": "Collection of account details.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "The GET account response."
      }
    }
  }
}
```

br
#### Errors

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