Balances

​

View the balances for sub-accounts in an entity, and retrieve the bank details used to top them up.

Balances Operations

Retrieve entity balances

​

Use this endpoint to retrieve balances for each sub-account in an entity.
Note: The sub-account is referred to as currency account in the API.

Path Parameters
  • id
    Type: string
    required

    The ID of the entity.

Query Parameters
  • query
    Type: string

    The query to apply to limit the currency accounts.

  • withCurrencyAccountId
    Type: boolean

    Specifies if the response should include the sub-account ID that corresponds to each set of balances.

  • balancesAt
    Type: string Format: date-time

    A UTC datetime to retrieve historical balances at a specific point in time, in the format yyyy-MM-ddTHH:mm:ssZ (e.g. 2026-05-06T13:59:59.9999999+00:00). Must be in the past. If omitted, the response returns live balances.

Responses
  • application/json
  • 400

    Invalid query parameter — for example, an unsupported query filter value, a non-boolean withCurrencyAccountId, or a malformed balancesAt value.

  • 401

    Unauthorized

  • 404

    Entity not found

  • application/json
Request Example for get/balances/{id}
curl https://balances.checkout.com/balances/ent_w4jelhppmfiufdnatam37wrfc4 \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "currency_account_id": "ca_g5y7d6jo4e2urgforcbf2ey5jm",
      "descriptor": "Revenue Account 1",
      "holding_currency": "EUR",
      "balances_as_of": "2026-05-06T13:59:59.9999999+00:00",
      "balances": {
        "pending": 23000,
        "available": 50000,
        "payable": 2700,
        "collateral": 6000,
        "operational": 7000,
        "collateral_breakdown": {
          "fixed_reserve": 4000,
          "rolling_reserve": 2000
        }
      }
    }
  ]
}

Balances retrieved successfully.

Retrieve top-up instructions

​

Use this endpoint to retrieve the bank details required to top up a sub-account, along with the payment reference that attributes an incoming payment to that sub-account.
Note: The sub-account is referred to as currency account in the API.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the entity that owns the sub-account, or of an entity above it in your hierarchy. A platform can use its own entity ID to reach the sub-accounts of any entity beneath it.

  • currencyAccountId
    Type: string
    required

    The ID of the sub-account to retrieve top-up instructions for.

Responses
  • application/json
  • 400

    Invalid entityId or currencyAccountId.

  • 401

    Unauthorized

  • 403

    The credential lacks access to top-up instructions, or top-ups aren't enabled for the sub-account.

  • 404

    The specified sub-account could not be found, or has no top-up instructions available.

  • 502

    The request could not be completed. Try again later.

Request Example for get/entities/{entityId}/currency-accounts/{currencyAccountId}/top-up-instructions
Shell Curl
curl https://balances.checkout.com/entities/ent_w4jelhppmfiufdnatam37wrfc4/currency-accounts/ca_g5y7d6jo4e2urgforcbf2ey5jm/top-up-instructions \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "currency_account_id": "ca_g5y7d6jo4e2urgforcbf2ey5jm",
  "currency": "USD",
  "payment_reference": "TP-ABC123",
  "bank_details": {
    "domestic": {
      "beneficiary_account_name": "Acme Inc",
      "beneficiary_address": "1 Example Street, Exampleville, EX, 00000, US",
      "bank_name": "Example Bank",
      "bank_address": "1 Example Street, Exampleville, EX, 00000, US",
      "account_number": "1234567890",
      "sort_code": "000000",
      "routing_number": "000000000",
      "iban": "GB00EXAM00000000000000",
      "swift_code": "TESTUS00XXX"
    },
    "international": {
      "beneficiary_account_name": "Acme Inc",
      "beneficiary_address": "1 Example Street, Exampleville, EX, 00000, US",
      "bank_name": "Example Bank",
      "bank_address": "1 Example Street, Exampleville, EX, 00000, US",
      "account_number": "1234567890",
      "sort_code": "000000",
      "routing_number": "000000000",
      "iban": "GB00EXAM00000000000000",
      "swift_code": "TESTUS00XXX"
    }
  }
}

Top-up instructions retrieved successfully.