Checkout.com API logo

Balances

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

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.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string

The ID of the entity.

Example: ent_w4jelhppmfiufdnatam37wrfc4
query Parameters
query
string

The query to apply to limit the currency accounts.

Example: query=currency:EUR
withCurrencyAccountId
boolean
Default: false

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

balancesAt
string <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.

Example: balancesAt=2026-05-06T13:59:59.9999999+00:00
Responses
200

Balances retrieved successfully.

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

422

Invalid data was sent

get/balances/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Balances;
using Checkout.Common;

ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Balances)
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();


BalancesQuery query = new BalancesQuery {Query = "currency:" + Currency.GBP};

try
{
    BalancesResponse balances = await api.BalancesClient()
        .RetrieveEntityBalances("entitiy_id", query);
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
{
  • "data": [
    ]
}

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.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
entityId
required
string

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.

Example: ent_w4jelhppmfiufdnatam37wrfc4
currencyAccountId
required
string

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

Example: ca_g5y7d6jo4e2urgforcbf2ey5jm
Responses
200

Top-up instructions retrieved successfully.

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.

get/entities/{entityId}/currency-accounts/{currencyAccountId}/top-up-instructions
Request samples 
Response samples 
application/json
{
  • "currency_account_id": "ca_g5y7d6jo4e2urgforcbf2ey5jm",
  • "currency": "USD",
  • "payment_reference": "TP-ABC123",
  • "bank_details": {
    }
}
➔ Next to Payment Context