finscale Docs

Balance

Your balance is one number per currency — available plus pending — netted across every provider that processed your volume. This page explains what each bucket means, what moves money between them, and why the number can go negative.

Available vs pending

Every captured payment passes through two buckets on its way to your bank account:

capture pending +4900 gross provider settles · fee −64 available +4836 net payout bank captured — provider hasn't settled yet settled — ready for payout
BucketMeaningEnters whenLeaves when
pending Captured funds the providers haven't settled to Finscale yet — a claim, not cash. A payment is captured (gross amount). The provider settles the line — net of fees, it moves to available.
available Settled funds ready for payout. A settlement batch lands (see reconciliation). A payout sends it to your bank — or a refund / dispute debits it.

The split already absorbs per-provider settlement timing. Cards from one provider may settle a day before direct debits from another — you never see four provider statements, just money that has settled and money that hasn't. How long each method sits in pending is a property of its rail: see the funding schedule.

GET /v1/balance

One read-only endpoint, no parameters. Amounts are integer minor units; one array entry per currency you've processed:

GET /v1/balance 
curl https://api.finscale.dev/v1/balance \
  -H "Authorization: Bearer sk_test_51FinscaleDemo…"

{
  "object": "balance",
  "available": [
    { "amount": 1914190, "currency": "EUR" },
    { "amount": 402100, "currency": "USD" }
  ],
  "pending": [
    { "amount": 68400, "currency": "EUR" }
  ],
  "livemode": false
}

Reading this account: €19,141.90 has settled in EUR and will leave with the next payout; €684.00 more is captured but still with the providers; $4,021.00 is available in USD and pays out separately — payouts never mix currencies (unless you've opted into consolidation, per multicurrency). Test mode (sk_test_) has its own balance, marked "livemode": false, funded by test payments.

Balance is derived, not stored Both buckets are sums over the ledger's postings. That's why the balance always agrees with your settlement reports and payouts — they are the same postings, viewed differently.

What moves the balance

MovementBucketDirectionSignal
Capture succeedspending+ grosspayment.succeeded
Provider settles a linepending → availablenet of feessettlement.report.ready
Refundavailable− amountrefund.succeeded
Dispute opensavailable− disputed amount (held)dispute.created
Dispute wonavailable+ held amount returneddispute.closed
Reserve hold / releaseoutside availablesee reservesdashboard
Payoutavailable− payout amountGET /v1/payouts

Two things are deliberately not in the balance: authorized-but-uncaptured amounts (an authorization hold is the issuer's earmark, not your money yet) and reserved funds (settled, but held under your reserve terms — they rejoin available when released).

Negative balances

available can go below zero. Refunds and dispute debits don't bounce — if you refund more than you've settled (a heavy refund day, a young account with most funds still pending), the debit lands and the bucket goes negative.

What happens then:

  • Payouts pause. There is nothing to pay out; the next payout runs when available is positive again on a payout day.
  • Incoming settlements net against it. New captures settle into the negative bucket and pull it back up — no action needed in the common case.
  • Refunds keep working. Finscale doesn't block refunds on a temporarily negative balance; sustained negative balances are a conversation with your Finscale representative, not an API error.

Error scenarios

GET /v1/balance itself can only fail in the standard ways — authentication_error (401) for a bad key, rate_limit_error (429) if you poll too hard. The interesting failures are downstream:

SituationWhat you observeWhat to do
Payout fails (closed account, rejected transfer) Payout status: failed; funds return to available — never lost in transit. Fix the bank details; the payout retries. See payouts.
Balance looks "wrong" intraday pending and available move at settlement boundaries, not continuously. Reconcile against the day's settlement batch, not against a live snapshot.
Currency missing from an array No activity in that currency yet — empty buckets are omitted, not zero-filled. Treat absence as zero in your code.
  • Settlement & payouts — the schedule that turns available into a bank transfer.
  • Ledger — the postings both buckets are sums over.
  • Reconciliation — proving the movements line by line.
  • Refunds — the most common reason available dips.