Balance

The Contro Partner API uses a prefunded model - your partner account holds a balance that is debited when cards are used. Monitor your balance and review transactions to track fund movement.

Check balance

Retrieve your current balance:

curl https://api.contro.me/v1/partner/balance \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const balance = await contro.balance.retrieve();
console.log(`${balance.balance} ${balance.currency}`);

balance = contro.balance.retrieve()
print(f"{balance.balance} {balance.currency}")

const balance = await fetch(`${BASE_URL}/partner/balance`, {
  headers,
}).then((r) => r.json());

console.log(`${balance.balance} ${balance.currency}`);

Response

{
  "balance": 50000.00,
  "currency": "USD"
}

Field	Type	Description
`balance`	number	Current balance amount in the account’s currency. Example: `50000.00`
`currency`	string	ISO 4217 currency code. Example: `"USD"`

Balance transactions

View the history of credits and debits on your balance:

curl "https://api.contro.me/v1/partner/balance/transactions?limit=20" \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const txns = await contro.balance.listTransactions({ limit: 20 });

txns = contro.balance.list_transactions(limit=20)

const txns = await fetch(
  `${BASE_URL}/partner/balance/transactions?limit=20`,
  { headers }
).then((r) => r.json());

Query parameters

Parameter	Type	Description
`page`	integer	Page number (default `1`).
`limit`	integer	Items per page (1–100, default `20`).
`status`	string	Filter by transaction status. One of `pending`, `action_required`, `accepted`, `rejected`, `failed`, `void`.
`type`	string	Filter by transaction type (e.g. `card_issuance`, `card_funding`, `kyc`).
`from`	string	ISO 8601 start timestamp (inclusive).
`to`	string	ISO 8601 end timestamp (inclusive).

Response

{
  "data": [
    {
      "id": "btx_abc123",
      "amount": -42.50,
      "type": "card_debit",
      "status": "completed",
      "description": "Card transaction - Coffee Shop",
      "ref": "tx_def456",
      "timestamp": "2026-03-20T14:30:00Z",
      "createdAt": "2026-03-20T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Balance transaction fields

Field	Type	Description
`id`	string	Balance transaction ID. Example: `"btx_abc123"`
`amount`	number	Amount in the account’s currency. Positive = credit, negative = debit. Example: `-42.50`
`type`	string	Transaction type. One of `card_debit`, `card_refund`, `top_up`, `fee`
`status`	string	Transaction status. One of `pending`, `completed`, `failed`
`description`	string \| null	Human-readable description, or `null`. Example: `"Card transaction - Coffee Shop"`
`ref`	string \| null	ID of the related card transaction or top-up, or `null`. Example: `"tx_def456"`
`timestamp`	string	ISO 8601 timestamp of when the transaction occurred. Example: `"2026-03-20T14:30:00Z"`
`createdAt`	string	ISO 8601 timestamp of when the record was created. Example: `"2026-03-20T14:30:00Z"`

Transaction types

Type	Description
`card_debit`	Debit from a card transaction
`card_refund`	Refund credited back
`top_up`	Manual balance top-up
`fee`	Platform or service fee

Low balance alerts

Configure webhooks to receive notifications when your balance falls below a threshold, so you can top up before card transactions are declined.

Balance thresholds

Your account can have up to three balance thresholds, configured with Contro during onboarding. They are evaluated after every settlement and balance change, and each level acts exactly once per downward crossing — re-arming when your balance recovers above the threshold.

Threshold	What happens when your balance crosses below it
Alert	A `balance.alert` webhook fires immediately so you can top up.
Block issuance	New card issuance is rejected with an `ISSUANCE_BLOCKED` error while the balance stays at or below this level. Existing cards keep working. The block lifts automatically once you top up above the threshold.
Freeze	Spending is stopped at the freeze threshold. For cards on a program with real-time authorization, transactions are declined in real time while your balance stays at or below the threshold and resume automatically once you top up above it — no manual unfreeze. For cards on programs without real-time authorization, all active cards are frozen and are not unfrozen automatically — after topping up, unfreeze them via `POST /partner/cards/{id}/unfreeze` or contact support.

Settlements can take your balance negative (spend that was already authorized is still honored); thresholds exist so you can act before that happens. The sandbox evaluates the same thresholds against your sandbox balance, so you can rehearse the alert and recovery flow with simulate-transaction and reset-balance.

Getting started

Core resources

Platform

Check balance

Response

Balance transactions

Query parameters

Response

Balance transaction fields

Transaction types

Low balance alerts

Balance thresholds

​Check balance

​Response

​Balance transactions

​Query parameters

​Response

​Balance transaction fields

​Transaction types

​Low balance alerts

​Balance thresholds

Check balance

Response

Balance transactions

Query parameters

Response

Balance transaction fields

Transaction types

Low balance alerts

Balance thresholds