Hello Clever Developer Docs

The v2 Balance API lets you query your current balance position across all currencies configured in your Hello Clever account. You can inspect five distinct balance types to understand exactly how much is available, in-flight, reserved, or ready to withdraw, and retrieve a dated history of every transaction that changed your balance.

Balance types

Balance type	Description
`available_balance`	The balance available for all transactions.
`incoming_balance`	Successful payments where the third-party provider has not yet settled funds (e.g., payment card transactions).
`outgoing_balance`	Funds currently being transferred, waiting to be deducted from the available balance to process refunds, disputes, or payouts.
`rolling_reserve_balance`	A floating reserve amount held in the merchant balance. This is not mandatory; contact Hello Clever support to enable.
`withdrawable_balance`	The amount you can withdraw, which excludes the rolling reserve.

Get Balance Details

GET /v2/balances/detail Returns the current balance breakdown for your account in a specified currency.

Query parameters

string

required

ISO 4217 currency code (e.g., AUD, VND, MYR). Must be a currency configured in your Hello Clever account.

Response fields

string

The currency of the balance.

number

Balance available for transactions.

number

Funds received but not yet settled by the third-party provider.

number

Funds in-transit for outgoing operations (refunds, payouts, disputes).

number

Reserved balance amount. Returns 0 if no rolling reserve is configured.

number

Amount you can withdraw: available_balance minus rolling_reserve_balance.

curl --request GET \
  --url 'https://api.cleverhub.co/api/v2/balances/detail?currency=AUD' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "currency": "AUD",
  "available_balance": 125000.00,
  "incoming_balance": 5000.00,
  "outgoing_balance": 2500.00,
  "rolling_reserve_balance": 10000.00,
  "withdrawable_balance": 115000.00
}

To query balances for multiple currencies, call this endpoint once per currency. Each app-id maps to a single currency. If you operate multiple currencies, you will have a separate app-id and secret-key for each.

Get Balance History

GET /v2/balances/history Access a detailed history of balance transactions over a specified date range. This includes every balance change on your account, including incoming payments, payouts, settlements, refunds, top-ups, withdrawals, disputes, cashback payouts, and account transfers, across all currencies configured on your account.

Query parameters

date-time

required

Start of the date range, in the format YYYY-MM-DDThh:mm:ssZ. Interpreted as UTC.

date-time

required

End of the date range, in the format YYYY-MM-DDThh:mm:ssZ. Interpreted as UTC.

string

Pagination cursor, taken from next_cursor in the previous response. Omit this parameter to fetch the first page.

integer

default:"20"

Number of records to return per page.

Response fields

string

Start of the queried date range.

string

End of the queried date range.

string

The balance model of the requesting account: aggregated or dedicated. See managing balances and accounts for what each model means.

integer

Number of records returned in this page.

string

Cursor to pass as the cursor query parameter to fetch the next page. null when there are no more records.

boolean

Whether more records are available after this page.

array

List of balance history entries.

Show properties

string

Balance ID: unique identifier for this balance entry.

number

Net amount of the transaction, after fees.

string

Direction of the balance change: money_in (added) or money_out (deducted).

string

What caused the balance change: payment, payout, settlement, refund, topup, withdrawal, dispute, dispute_fee, cashback_payout, transfer_in, or transfer_out.

string

Currency of this entry.

string

The payment method used, for example bsb.

string

Current status of the balance flow: waiting, done, or failed.

string

The reference code for the underlying transaction.

object

Gross, net, and fee breakdown for the entry.

Show properties

number

Transaction amount excluding fees.

number

Transaction amount charged, after fees.

number

Fee charged on the transaction.

string

Timestamp when the balance transaction was created (UTC).

curl --request GET \
  --url 'https://api.cleverhub.co/api/v2/balances/history?from_date=2026-01-01T00:00:00Z&to_date=2026-01-31T00:00:00Z' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "from_date": "2026-01-01T00:00:00Z",
  "to_date": "2026-01-31T00:00:00Z",
  "account_type": "aggregated",
  "size": 20,
  "next_cursor": "eyJpZCI6ImJsX3BpX3duNFRXaGxYQnJaSyJ9",
  "has_more": true,
  "records": [
    {
      "id": "bl_pi_wn4TWhlXBrZK",
      "amount": 202.66,
      "request_type": "money_out",
      "transaction_type": "settlement",
      "currency": "AUD",
      "payment_method": "bsb",
      "status": "done",
      "reference_id": "BAL_cqxDHqDOSs8=--4",
      "balance_detail": {
        "outgoing": 205,
        "total": 202.66,
        "fees": 2.34
      },
      "created_at": "2026-01-01T00:00:00.000+0000"
    }
  ]
}

Status labels in the portal

The status values returned by this endpoint do not all match the labels shown in the Merchant Portal:

API value	Portal label
`waiting`	Processing
`done`	Done
`failed`	Failed

Map waiting to Processing if you surface these statuses in your own interface alongside the portal, or when reconciling an API response against what a colleague sees on the balances screen.

Paginating through results

This endpoint uses cursor-based pagination. To walk the full result set:

Request the first page

Call the endpoint with from_date and to_date only, and omit cursor.

Check `has_more`

If has_more is false, you have every record and next_cursor is null. Stop here.

Request the next page

Pass the next_cursor value from the previous response as the cursor parameter, keeping from_date, to_date, and size unchanged. Repeat until has_more is false.

Treat next_cursor as an opaque token. Its contents are an implementation detail and may change. Do not parse it, construct one yourself, or store it as a durable bookmark.

Migrating from v1 balance history

If you currently call GET /v1/balances/history, note these differences:

	v1	v2
Currency coverage	AUD only	All currencies configured on your account
Pagination	`page` + `per_page` numbers	`cursor` + `size` (opaque cursor)
Date parameters	Dates (`2026-01-01`)	Timestamps (`2026-01-01T00:00:00Z`), UTC
Record list field	`data`	`records`
Amount convention	Signed, with negative values as debits	Unsigned `amount` plus a `request_type` of `money_in` or `money_out`
Balance running total	`balance_after` per entry	Not returned
Fee breakdown	Not returned	`balance_detail.outgoing` / `total` / `fees`

The amount convention differs between versions. In v1, a refund appears as a negative amount; in v2 the same refund has a positive amount and request_type: "money_out". Summing v2 amounts without checking request_type will overstate your net position.

Understanding your balance

Use this endpoint to monitor your account health before initiating payouts or refunds:

Check available_balance before creating a payout to ensure sufficient funds.
Monitor incoming_balance to anticipate upcoming settlements.
Track outgoing_balance to understand funds currently committed to pending operations.
Contact support@helloclever.co to configure or adjust your rolling_reserve_balance.

Basics

Payment APIs

Card API

Cashback API

Balance API Reference

Balance types

Get Balance Details

Query parameters

Response fields

Get Balance History

Query parameters

Response fields

Status labels in the portal

Paginating through results

Migrating from v1 balance history

Understanding your balance

​Balance types

​Get Balance Details

​Query parameters

​Response fields

​Get Balance History

​Query parameters

​Response fields

​Status labels in the portal

​Paginating through results

​Migrating from v1 balance history

​Understanding your balance

Balance types

Get Balance Details

Query parameters

Response fields

Get Balance History

Query parameters

Response fields

Status labels in the portal

Paginating through results

Migrating from v1 balance history

Understanding your balance