Hello Clever Developer Docs

The Balance endpoints give you real-time visibility into your Hello Clever account funds. Use the balance details endpoint to see a current snapshot across all balance types, and the balance history endpoint to audit how your balance has changed over a specified period, including payments received, refunds issued, and top-ups.

These endpoints support AUD balances only. To query balances or balance history in any other currency, use the v2 Balance API, which covers every currency configured on your account.

Get balance details

GET /v1/balances/detail

Retrieve a real-time breakdown of all balance types in your account.

Balance types

Balance type	Description
`available_balance`	Funds immediately available for transactions.
`incoming_balance`	Funds credited from successful payments but not yet settled by the third-party provider (e.g. card processor).
`outgoing_balance`	Funds set aside to process pending actions such as refunds, disputes, or payouts.
`rolling_reserve_balance`	Reserved funds held as a security buffer against chargebacks or liabilities. Contact technical support to enable this feature.
`withdrawable_balance`	The portion of your available balance that can be withdrawn (excludes rolling reserve funds).

Response fields

string

Currency code (AUD).

number

Funds available immediately for any transaction, in AUD.

number

Funds pending credit from successful payments, in AUD.

number

Funds reserved for pending refunds, disputes, or payouts, in AUD.

number

Reserved funds held as a security buffer, in AUD.

number

Available balance excluding rolling reserve funds, in AUD.

string

ISO 8601 timestamp of when the balance snapshot was taken.

Code example

curl --request GET \
  --url https://api-merchant.helloclever.co/api/v1/balances/detail \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "currency": "AUD",
  "available_balance": 12450.75,
  "incoming_balance": 3200.00,
  "outgoing_balance": 500.00,
  "rolling_reserve_balance": 1000.00,
  "withdrawable_balance": 11450.75,
  "retrieved_at": "2026-04-17T10:00:00Z"
}

{
  "error": "Unauthorized",
  "message": "Invalid app-id or secret-key."
}

Get balance history

GET /v1/balances/history

Access a detailed history of all balance changes within a specified date range. This includes incoming payments, refunds, top-ups, payouts, and any other activity that affects your account balance.

For multi-currency balance history, use GET /v2/balances/history instead. It returns records across every currency on your account and includes a per-transaction fee breakdown. See migrating from v1 balance history for the parameter and response differences.

Query parameters

string

required

Start of the date range in ISO 8601 format (e.g. 2026-01-01).

string

required

End of the date range in ISO 8601 format (e.g. 2026-04-17).

number

default:"1"

Page number for paginated results.

number

default:"20"

Number of records per page.

Response fields

array

List of balance history entries.

Show properties

string

Unique identifier for the balance history entry.

string

Type of balance change (e.g. payment_received, refund_issued, top_up, payout).

number

Amount of the balance change in AUD. Positive values indicate credits; negative values indicate debits.

number

Available balance after this transaction, in AUD.

string

Identifier of the associated transaction (e.g. payment request ID or payout ID).

string

Human-readable description of the balance change.

string

ISO 8601 timestamp of when the balance change occurred.

number

Total number of balance history entries matching the query.

number

Current page number.

Code example

curl --request GET \
  --url 'https://api-merchant.helloclever.co/api/v1/balances/history?from_date=2026-04-01&to_date=2026-04-17&page=1' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "data": [
    {
      "id": "bh_entry_001",
      "type": "payment_received",
      "amount": 99.95,
      "balance_after": 12450.75,
      "reference_id": "pr_abc123",
      "description": "Payment received for Order #1042",
      "created_at": "2026-04-17T10:15:00Z"
    },
    {
      "id": "bh_entry_002",
      "type": "refund_issued",
      "amount": -250.00,
      "balance_after": 12200.75,
      "reference_id": "ref_jkl012",
      "description": "Refund issued for Invoice #5021",
      "created_at": "2026-04-17T11:00:00Z"
    }
  ],
  "total": 2,
  "page": 1
}

{
  "error": "UnprocessableEntity",
  "message": "from_date and to_date are required."
}

Basics

Payment APIs

Card API

Cashback API

AUD Balance API Reference

Get balance details

Balance types

Response fields

Code example

Get balance history

Query parameters

Response fields

Code example

​Get balance details

​Balance types

​Response fields

​Code example

​Get balance history

​Query parameters

​Response fields

​Code example

Get balance details

Balance types

Response fields

Code example

Get balance history

Query parameters

Response fields

Code example