Ledger System

Overview

The Zuba ledger system implements a robust double-entry bookkeeping system that tracks all financial movements across the platform. Every transaction is recorded as transfers between named accounts, providing complete audit trails and real-time balance tracking.

Core Concepts

Accounts

Accounts represent financial entities in the system and are identified by unique names with currency support. When querying your balances, you’ll see:

Account Balance Response

{
  "currency": "EUR",
  "balance": 1250.50,
  "pendingIn": 100.00,
  "pendingOut": 50.00,
  "totalBalance": 1300.50,
  "isActive": true,
  "lastTransactionAt": "2026-01-12T12:00:00Z"
}

Field	Description
`currency`	ISO 4217 currency code
`balance`	Available balance (funds you can use)
`pendingIn`	Incoming funds being processed
`pendingOut`	Outgoing funds being processed
`totalBalance`	Total balance including pending
`isActive`	Whether the account is active
`lastTransactionAt`	Timestamp of most recent transaction

Account Naming Convention

Accounts use hierarchical naming with colon (:) separators to organize different types of financial entities:

Pattern	Description	Example
`user:{clientId}`	Customer/client accounts	`user:cc82fa1d-fc7a-478c-a734-d3bce40464e7`
`zuba:{purpose}`	Platform system accounts	`zuba:deposits`, `zuba:payouts`, `zuba:fees:EUR`
`{provider}:{identifier}`	Provider accounts	`revolut:payouts`, `stripe:card`
`ext:{identifier}`	External beneficiary accounts	`ext:DE89370400440532013000`
`fx:{identifier}`	Foreign exchange accounts	`fx:partner`

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

{
  "id": "572e779e-6d71-4bd7-91f1-57109c562b56",
  "type": "debit",
  "amount": 0.95411814,
  "currency": "EUR",
  "balanceAfter": 87.57104914,
  "counterparty": "fx:partner",
  "status": "confirmed",
  "createdAt": "2026-01-12T12:50:48.792Z",
  "confirmedAt": "2026-01-12T12:50:48.791Z"
}

Field	Description
`id`	Unique transaction identifier
`type`	`debit` (money out) or `credit` (money in)
`amount`	Transaction amount
`currency`	ISO 4217 currency code
`balanceAfter`	Your account balance after this transaction
`counterparty`	The other account involved in the transaction
`status`	Transaction status (`pending`, `confirmed`, `failed`, `cancelled`)
`createdAt`	When the transaction was created
`confirmedAt`	When the transaction was confirmed

Transaction States

Status	Description	Actions Available
`pending`	Transaction created, awaiting confirmation	Confirm, Cancel
`confirmed`	Transaction successfully processed	View only
`failed`	Transaction failed during processing	Retry, Investigate
`cancelled`	Transaction cancelled before processing	View only

Balance Management

Real-time Balance Calculation

Account balances are calculated in real-time from confirmed transactions:

// Simplified balance calculation
const balance = confirmedCredits - confirmedDebits;

Multi-Currency Support

Each account maintains balances in a single currency. When querying all balances, you’ll receive a list of accounts for each currency:

Multi-Currency Response

{
  "userId": "auth0|123456",
  "clientId": "cc82fa1d-fc7a-478c-a734-d3bce40464e7",
  "balances": [
    { "currency": "EUR", "balance": 1000.00, "pendingIn": 0, "pendingOut": 0, "totalBalance": 1000.00 },
    { "currency": "USD", "balance": 1200.00, "pendingIn": 50.00, "pendingOut": 0, "totalBalance": 1250.00 }
  ],
  "totalValueEur": 2100.00,
  "primaryCurrency": "EUR"
}

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 customer makes a deposit, multiple ledger transactions are created automatically: Example flow for a €100 deposit:

ext:{payer_iban} → stripe:{merchant_iban} (€100.00) - External to provider
stripe:{merchant_iban} → zuba:deposits (€100.00) - Provider to platform
zuba:deposits → user:{clientId} (€100.00) - Platform to customer

You’ll see the final credit appear in your transaction history:

Credit Transaction

{
  "id": "572e779e-6d71-4bd7-91f1-57109c562b56",
  "type": "credit",
  "amount": 100.00,
  "currency": "EUR",
  "balanceAfter": 1100.00,
  "counterparty": "zuba:deposits",
  "status": "confirmed",
  "createdAt": "2026-01-12T12:00:00.000Z",
  "confirmedAt": "2026-01-12T12:00:00.000Z"
}

Payout Transaction Flow

For payouts, the system creates transaction chains including FX conversion when needed: Example flow for a €100 → $108 payout:

user:{clientId} → zuba:payouts (€100.00) - Debit customer
zuba:payouts → fx:partner (€100.00) - Send for conversion
fx:partner → revolut:payouts ($108.00) - Converted amount to provider
revolut:payouts → ext:{beneficiary_iban} ($108.00) - Final payout

You’ll see the debit in your transaction history:

Debit Transaction

{
  "id": "683f880f-7e82-5ce8-b202-68210d673c67",
  "type": "debit",
  "amount": 100.00,
  "currency": "EUR",
  "balanceAfter": 900.00,
  "counterparty": "zuba:payouts",
  "status": "confirmed",
  "createdAt": "2026-01-12T14:30:00.000Z",
  "confirmedAt": "2026-01-12T14:30:00.000Z"
}

Querying the Ledger

Account Balance

curl -X GET "https://api-test.zuba.com/ledger/balances/EUR" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Transaction History

curl -X GET "https://api-test.zuba.com/ledger/transactions?currency=EUR&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Audit & Compliance

Audit Trail

Every transaction maintains a complete audit trail:

Immutable Records: Transactions cannot be modified once confirmed
Timestamps: All operations are timestamped with precision
Metadata: Additional context stored with each transaction
Reference IDs: Link to external provider transactions

Compliance Features

Financial Reconciliation

Daily balance reconciliation across all accounts
Provider settlement matching and verification
Automated discrepancy detection and alerts
Historical balance reconstruction capabilities

Regulatory Reporting

Transaction history export for audits
Real-time balance monitoring and limits
Suspicious activity pattern detection
Automated regulatory filing support

Data Integrity

Double-entry validation on every transaction
Balance consistency checks across all accounts
Automated reconciliation with external providers
Immutable transaction records with cryptographic hashing

Advanced Features

Currency Conversion Tracking

When FX conversion occurs during a payout, you’ll see multiple transactions in your history representing the conversion:

FX Debit Transaction

{
  "id": "572e779e-6d71-4bd7-91f1-57109c562b56",
  "type": "debit",
  "amount": 100.00,
  "currency": "EUR",
  "balanceAfter": 900.00,
  "counterparty": "fx:partner",
  "status": "confirmed",
  "createdAt": "2026-01-12T12:50:48.792Z",
  "confirmedAt": "2026-01-12T12:50:48.791Z"
}

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:

curl -X GET "https://api-test.zuba.com/ledger/statement/EUR?startDate=2026-01-01&endDate=2026-01-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Statement Response:

Account Statement

{
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "accountName": "user:cc82fa1d-fc7a-478c-a734-d3bce40464e7",
  "currency": "EUR",
  "periodStart": "2026-01-01",
  "periodEnd": "2026-01-31",
  "openingBalance": "1000.00",
  "closingBalance": "1500.50",
  "totalCredits": "600.50",
  "totalDebits": "100.00",
  "transactions": [
    {
      "date": "2026-01-15T10:00:00Z",
      "credit": "500.00",
      "balanceAfter": "1500.00",
      "reference": "DEPOSIT-001",
      "transactionId": "abc123..."
    }
  ],
  "generatedAt": "2026-01-31T12:00:00Z"
}

Error Handling

Transaction Failures

When a payout or deposit fails, you may see a failed transaction in your history:

Failed Transaction

{
  "id": "572e779e-6d71-4bd7-91f1-57109c562b56",
  "type": "debit",
  "amount": 100.00,
  "currency": "EUR",
  "balanceAfter": 1000.00,
  "counterparty": "zuba:payouts",
  "status": "failed",
  "createdAt": "2026-01-12T12:50:48.792Z"
}

Failed transactions do not affect your available balance. The platform automatically handles any necessary reversals.

Common Error Scenarios

Error	Description	Resolution
Insufficient funds	Not enough balance to complete payout	Add funds to your account
Invalid beneficiary	Beneficiary details are incorrect	Update beneficiary information
Provider error	External provider issue	Retry or contact support

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

Check balances before initiating payouts to avoid failures
Set up webhooks for real-time balance notifications
Use the statement endpoint for reconciliation
Monitor pending amounts for cash flow planning

Reconciliation

Generate statements periodically for your records
Match ledger transactions with your internal systems
Keep track of pending transactions for accurate cash positions
Export transaction history for accounting integration

API Usage

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

Documentation Index

​Overview

​Core Concepts

​Accounts

​Account Naming Convention

​Transactions

​Transaction States

​Balance Management

​Real-time Balance Calculation

​Multi-Currency Support

​Payment Flow Integration

​Payin Transaction Flow

​Payout Transaction Flow

​Querying the Ledger

​Account Balance

​Transaction History

​Audit & Compliance

​Audit Trail

​Compliance Features

​Advanced Features

​Currency Conversion Tracking

​Account Statements

​Error Handling

​Transaction Failures

​Common Error Scenarios

​Integration Guidelines

​Best Practices

​Next Steps

First Payout Guide

Webhooks

Batch Payouts

API Reference

Overview

Core Concepts

Accounts

Account Naming Convention

Transactions

Transaction States

Balance Management

Real-time Balance Calculation

Multi-Currency Support

Payment Flow Integration

Payin Transaction Flow

Payout Transaction Flow

Querying the Ledger

Account Balance

Transaction History

Audit & Compliance

Audit Trail

Compliance Features

Advanced Features

Currency Conversion Tracking

Account Statements

Error Handling

Transaction Failures

Common Error Scenarios

Integration Guidelines

Best Practices

Next Steps