Skip to main content

Documentation Index

Fetch the complete documentation index at: https://partner-docs.contro.dev/llms.txt

Use this file to discover all available pages before exploring further.

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"

​
Query parameters

ParameterTypeDescription
pageintegerPage number (default 1).
limitintegerItems per page (1–100, default 20).
statusstringFilter by transaction status. One of pending, action_required, accepted, rejected, failed, void.
typestringFilter by transaction type (e.g. card_issuance, card_funding, kyc).
fromstringISO 8601 start timestamp (inclusive).
tostringISO 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

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.