Overview
The Zuba ledger is a double-entry bookkeeping system that tracks every money movement on the platform. Each transaction is recorded as a transfer between accounts, giving you a complete audit trail and real-time balances.Core Concepts
Accounts
Each currency you hold is tracked in its own account. When querying your balances, you’ll see:Account Balance Response
GET /v1/ledger/balances lists the balance for every currency you hold, GET /v1/ledger/balances/{currency} returns a single currency, and GET /v1/ledger/accounts lists every account. Pass includeInactive=true to include closed accounts.
All monetary values are returned as decimal strings to preserve precision.
Balance endpoints return normalized values with trailing zeros stripped
(
"1250.5", "100"), while transaction and statement amounts carry eight
decimal places ("100.00000000"). Parse amounts with a decimal library:
never parse them as floats or compare them as fixed-format text.Transactions
All financial movements are recorded as double-entry transactions. When querying transactions, you’ll see them from your account’s perspective as debits (money out) or credits (money in):Transaction Structure
Optional fields are omitted when not applicable. Fee entries appear as separate debits with
isFee: true; they are internal transfers, so no counterparty is present.
A payout’s ledger transaction is
confirmed as soon as the funds are debited
from your balance. It does not mean the beneficiary has been paid. Slow
rails (e.g. SWIFT) can remain in flight for days after the debit confirms.
Use payoutStatus to track delivery; paid means the funds arrived. See
payout statuses for the full lifecycle.Transaction States
These transitions are managed entirely by the platform. There is no API call to confirm, cancel, or retry a ledger transaction. Failed payouts are handled with reversal entries (see Transaction Failures).
Balance Management
Real-time Balance Calculation
Your availablebalance is a stored running balance, updated as each transaction confirms. Pending amounts are computed at query time, so every balance response satisfies:
Multi-Currency Support
Each account maintains a balance in a single currency. When querying all balances, you’ll receive one entry per currency:Multi-Currency Response
totalValueEur field: an indicative total of all balances converted to EUR at the latest stored mid rates, with stablecoins valued at their fiat peg. It is omitted when no rate is available to value one of your held currencies. Treat it as a display convenience, not an accounting figure: derive reconciliation totals from the per-currency balances.
Payment Flow Integration
Ledger transactions are created automatically by the platform when processing deposits and payouts. You cannot create transactions directly. They are generated as a result of your payment operations.
Payin Transaction Flow
When a deposit settles, the platform moves the funds internally and credits your account automatically. From your perspective it lands as a single credit: You’ll see the credit appear in your transaction history. The internal account that funded it is omitted, so nocounterparty is present:
Credit Transaction
Payout Transaction Flow
For payouts, the system creates transaction chains including FX conversion when needed: You’ll see the debit in your transaction history. The internal accounts used to route and convert the payout are omitted, so nocounterparty is present:
Debit Transaction
Querying the Ledger
Account Balance
Transaction History
GET /v1/ledger/transactions returns a JSON array of transactions, newest first. Filter with currency, and paginate with limit (1–500) and offset:
Audit & Compliance
Audit Trail
Every transaction maintains a complete audit trail:- Immutable Records: Transactions cannot be modified once confirmed
- Timestamps: Every entry carries creation and confirmation timestamps
- Metadata: Additional context stored with each transaction
- Reference IDs: Link each entry to the originating payout, deposit, or order
Compliance Features
Financial Reconciliation
Financial Reconciliation
- Daily balance reconciliation across all accounts
- Settlement matching and verification on every rail
- Automated discrepancy detection and alerts
- Historical balance reconstruction for any past date
Reporting
Reporting
- Transaction history export for audits
- Account statements for any period
- End-of-day closing balances for daily reconciliation
Data Integrity
Data Integrity
- Double-entry validation on every transaction
- Balance consistency checks across all accounts
- Immutable transaction records with cryptographic hash chaining
Advanced Features
Currency Conversion Tracking
When a payout converts currency, you still see a single debit on your account. It carries both the amount debited from your balance and the amount sent to the beneficiary, via thesourceAmount/sourceCurrency and payoutAmount/payoutCurrency fields. Internal FX accounts are not surfaced, so no counterparty is present:
FX Payout Debit
Account Statements
For detailed reconciliation, you can generate account statements for a specific period:Account Statement
openingBalance, closingBalance, totalCredits, totalDebits, and per-transaction debit/credit) are fixed to eight decimal places.
Closing Balances
For day-level reconciliation,GET /v1/ledger/closing-balances returns the end-of-day balance of every account for a past UTC calendar date. The date must be yesterday or earlier. Today and future dates are rejected because today is not yet closed:
curl
Closing Balances Response
Error Handling
Transaction Failures
When a payout fails, the ledger does not rewrite history. The original debit staysconfirmed (the funds left your balance when the payout was created), and the platform posts a matching reversal credit that restores them. The debit’s payoutStatus becomes failed; the reversal credit carries the same payoutId:
Failed Payout: Debit and Reversal Credit
Common Error Scenarios
Integration Guidelines
Ledger transactions are created automatically by the platform when you create payouts or receive deposits. You cannot create transactions directly. Use the Payouts API to initiate transfers.
Best Practices
Balance Monitoring
Balance Monitoring
- Check balances before initiating payouts to avoid failures
- Subscribe to webhooks for payout and order lifecycle events that affect your balance, then re-query
/v1/ledger/balanceson receipt - Use the statement and closing-balances endpoints for reconciliation
- Monitor pending amounts for cash flow planning
Reconciliation
Reconciliation
- Generate statements periodically for your records
- Verify end-of-day positions with
/v1/ledger/closing-balances - Match ledger transactions with your internal systems
- Export transaction history for accounting integration
API Usage
API Usage
- Use pagination (
limitandoffset) for large transaction histories - Filter by currency when querying specific account activity
- Cache balance responses where real-time accuracy isn’t required
- Handle rate limits gracefully with exponential backoff
Next Steps
First Payout Guide
Send your first payout with the Zuba API
Webhooks
Set up real-time notifications for payment events
Batch Payouts
Process multiple payouts efficiently
API Reference
Complete API documentation