Payflux logoPayflux

Ledger API Overview

The Ledger API helps you record immutable, double-entry transactions in a consistent, auditable way. It draws from centuries-old accounting practices to build a modern foundation for FinTech systems.

Double-Entry Bookkeeping

Double-entry bookkeeping ensures financial accuracy by requiring every transaction to affect two or more accounts. For every debit, a corresponding credit must exist.

Accounting Formula

Accounting Formula

Assets = Liabilities + Equity

This equation keeps your ledger balanced and traceable. It’s the foundation for automated validation.

Mental Model

Debits increase what you own or spend (e.g., cash, expenses).
Credits increase what you owe or earn (e.g., liabilities, revenue).

Assets and expenses typically have debit balances. Liabilities, equity, and revenue typically have credit balances.

Account TypeDebit EffectCredit Effect
AssetIncreaseDecrease
LiabilityDecreaseIncrease
EquityDecreaseIncrease
Revenue—Increase
ExpenseIncrease—

Example: When cash is received, Cash (Asset) increases — a debit — and Revenue increases — a credit. Both grow, but affect opposite sides of the equation.

Use Case: Prepaid Charge Card

A prepaid virtual card system might include the following ledger events:

  • Fund via ACH — debit: Bank, credit: User Account
  • Authorize a charge — debit: Merchant Settlement, credit: User Account
  • Capture the charge — no-op if already fully matched

Each step results in a journal entry that mirrors real-world movement of funds.

Ledger flow: funding, authorization, and settlement of a virtual card.

Authentication & gRPC Access

All requests require an API key passed in the metadata using x-api-key.

Production Security

gRPC reflection is disabled in production. Download proto files or use the official proto reference to explore all services.

Visit the Ledger API Proto Reference for service definitions and ZIP downloads.

How to Call gRPC

Any gRPC-compatible client can be used as long as requests include a valid API key and conform to the service contracts.

Ledgers

A ledger is the primary container for all financial activity. It groups accounts and journal entries to form a complete, consistent view of your organization’s financial operations.

Each ledger is defined by a name and a base currency and enforces double-entry accounting within its scope.

Ledger Lifecycle

  • Create: Initialize with a name and currency.
  • Configure: Define its chart of accounts.
  • Operate: Post immutable journal entries.

You can create multiple ledgers to separate business units, currencies, or organizations.

Proto: ledger.proto
RPC: CreateLedger
Request
Response

Chart of Accounts

Every ledger defines a Chart of Accounts—a hierarchical tree that categorizes all balances and transactions.

  • Postable accounts: Leaf nodes that hold balances.
  • Group accounts: Organizational nodes that group postables.

Example Chart

Start with postables. Use groups to organize accounts for reporting or nesting.
├── Assets
│ ├── Bank
│ └── User Balance
├── Liabilities
│ └── Merchant Settlement
└── Equity
└── Retained Earnings

Define accounts using CreateAccount before posting journal entries.

Proto: account.proto
RPC: CreateAccount
Request
Response

Journal Entries

Journal entries record financial events by debiting and crediting one or more postable accounts. The system ensures each entry is balanced.

Entries are immutable. To change an entry, create a reversing entry. Each entry is cryptographically signed to preserve a tamper-proof audit trail.

Proto: journal.proto
RPC: CreateJournalEntry
Request
Response

Advanced Topics

Multitenancy & Orgs

Org-Aware Access

Every ledger belongs to an organisation_id. Users may be assigned to multiple orgs. Access is enforced through the authentication context.