Skip to main content

Balances

Read your collected balance on the Reporting API (https://api.tensorrail.com, bearer-token auth with your rail_* key).

GET /v1/balances reports three amounts for each currency you collect in. A collection lands in pending, moves to available once the payment is final and its fees are booked, and moves to settled once it is no longer counted as available on your account.

Scope​

GET /v1/balances needs settlements:read, which is part of the default key scopes — see the scope table.

Balances​

GET /v1/balances

curl "https://api.tensorrail.com/v1/balances" \
  -H "Authorization: Bearer rail_full_live_xxx"

Response 200 OK

{
  "merchant_id": 42,
  "currency": "USD",
  "available_balance_minor": 125000,
  "pending_balance_minor": 30000,
  "settled_balance_minor": 500000,
  "live_mode": true,
  "balances": [
    {
      "currency": "USD",
      "available_balance_minor": 125000,
      "pending_balance_minor": 30000,
      "settled_balance_minor": 500000,
      "live_mode": true
    }
  ]
}
FieldTypeDescription
balancesarrayOne entry per currency your account has collected in
available_balance_minorintegerAmount currently available, in minor units
pending_balance_minorintegerAmount collected but not yet available, in minor units
settled_balance_minorintegerAmount no longer counted as available, in minor units
currencystringISO currency code of the entry
live_modebooleantrue for production money, false for sandbox; omitted when unknown

The top-level fields are a snapshot of one currency: pass ?currency=EUR to pick which one. Left unset, the snapshot is the first currency alphabetically that has a row in the key's environment — a row, not necessarily a non-zero one — and falls back to the first row of any environment only when that environment has no rows at all. So an account with test EUR and live INR reads its rupees under a live key rather than an empty EUR row. Because the choice is alphabetical, do not read the snapshot as a statement about which currency matters to you: if you hold more than one, read the balances array, which carries every currency the key's environment may see. An account with no activity yet returns zeros and an empty balances array, not an error.

Test and live balances​

Your account holds separate balances per environment: money collected with test keys accrues to your test balance, live money to your live balance. The API key you call with decides which environment you see:

  • A rail_*_test_* key returns your test balances; a rail_*_live_* key returns your live balances. The snapshot and the balances array both contain only that environment's rows.
  • You never need a mode parameter with an API key. Passing ?mode= with a value that contradicts the key's environment is refused with ERR_3051 (mode_mismatch) rather than reinterpreted.
  • Dashboard sessions see both environments (the dashboard's environment toggle passes ?mode=live to read the live snapshot; the default is test).

What this endpoint does not cover​

/v1/settlements* and /v1/payouts return 404. This page covers reading your balance; anything beyond reading it is handled by your account manager under your agreement rather than requested here. A key can carry the payouts:* scopes so that keys would not need reissuing if that surface opens — see Reserved scopes.

Errors​

CodeHTTPCause
ERR_1001401No Authorization: Bearer <key> header
ERR_1002401The key is invalid, revoked or mistyped
ERR_1011401The Authorization header is present but unusable (wrong scheme, empty token)
ERR_1004403The key does not carry settlements:read
ERR_3051422?mode= contradicts the API key's environment