Skip to main content
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"

​
Response

{
  "balance": 50000.00,
  "currency": "USD",
  "ledgerId": "ledger_abc123"
}
FieldTypeDescription
balancenumberCurrent balance amount in the account’s currency. Example: 50000.00
currencystringISO 4217 currency code. Example: "USD"
ledgerIdstringInternal ledger identifier. Example: "ledger_abc123"

​
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"

​
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"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

​
Balance transaction fields

FieldTypeDescription
idstringBalance transaction ID. Example: "btx_abc123"
amountnumberAmount in the account’s currency. Positive = credit, negative = debit. Example: -42.50
typestringTransaction type. One of card_debit, card_refund, top_up, fee
statusstringTransaction status. One of pending, completed, failed
descriptionstring | nullHuman-readable description, or null. Example: "Card transaction - Coffee Shop"
refstring | nullID of the related card transaction or top-up, or null. Example: "tx_def456"
timestampstringISO 8601 timestamp of when the transaction occurred. Example: "2026-03-20T14:30:00Z"
createdAtstringISO 8601 timestamp of when the record was created. Example: "2026-03-20T14:30:00Z"

​
Transaction types

TypeDescription
card_debitDebit from a card transaction
card_refundRefund credited back
top_upManual balance top-up
feePlatform 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.