Skip to main content

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 available balance 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
The response also includes a 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 no counterparty 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 no counterparty 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

  • 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
  • Transaction history export for audits
  • Account statements for any period
  • End-of-day closing balances for daily reconciliation
  • 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 the sourceAmount/sourceCurrency and payoutAmount/payoutCurrency fields. Internal FX accounts are not surfaced, so no counterparty is present:
FX Payout Debit
The FX rate applied to your transaction is visible in the payout details, not the ledger transaction itself.

Account Statements

For detailed reconciliation, you can generate account statements for a specific period:
Statement Response:
Account Statement
Statement amounts (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
Accounts created after the requested date are excluded, so a missing currency means the account did not exist yet, not a zero balance.

Error Handling

Transaction Failures

When a payout fails, the ledger does not rewrite history. The original debit stays confirmed (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
The net balance impact is zero, and both entries remain in your history for auditability.

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

  • 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/balances on receipt
  • Use the statement and closing-balances endpoints for reconciliation
  • Monitor pending amounts for cash flow planning
  • 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
  • Use pagination (limit and offset) 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