Skip to main content
This page introduces Formance modules.

​
The Big Picture

Formance helps you track and move money. At its core:
  1. Ledger records where assets are and where they move
  2. Numscript expresses the intent for how assets should move
  3. Connectivity provides a normalized view of external providers like Stripe or bank accounts
  4. Reconciliation verifies your internal records match external reality
  5. Flows automates multi-step operations across modules
Let’s look at each one.

​
Ledger

The Ledger is your source of truth for money. It tracks:
  • Accounts: Named addresses that maintain a balance of assets received or sent (e.g., users:alice:wallet, platform:fees)
  • Transactions: Records of assets moving between accounts
  • Balances: The net result of all assets received and sent for each account

​
How it works

Every time money moves, the Ledger creates a transaction with one or more postings. A posting is simply: “Move X amount from account A to account B.” 
{
  "source": "users:alice:wallet",
  "destination": "merchants:coffee-shop",
  "amount": 450,
  "asset": "USD/2"
}
This moves $4.50 from Alice’s wallet to the coffee shop.

​
Key principles

  • Double-entry: Every transaction balances. Assets leaving one account equal assets entering another.
  • Immutable: Transactions cannot be edited or deleted. To cancel the effect of a transaction, you create a new transaction that offsets it. This can be a reversal or a more intentional corrective booking depending on your audit requirements.
  • Atomic: Multi-posting transactions succeed or fail together. No partial transfers.

​
Account naming

Accounts are identified by addresses like users:alice:wallet or orders:12345:pending. The colons create segments you can use to organize and filter accounts.
You don’t need to create accounts before using them. The first transaction involving an account creates it automatically.
Learn more about Ledger →

​
Numscript

Numscript is a domain-specific language for expressing the intent of money movements. Instead of writing code to calculate splits and handle edge cases, you describe what should happen and Numscript produces deterministic postings.

​
Why use it?

Consider paying out a rideshare driver: the rider pays $10, the platform takes 20%, and the driver gets the rest. In Numscript: 
send [USD/2 1000] (
  source = @rider:wallet
  destination = {
    20% to @platform:fees
    remaining to @driver:wallet
  }
)
Numscript captures your intent, ensures the transaction balances, and produces predictable, auditable postings every time.

​
Key features

  • Percentage splits: Divide payments automatically (50% to @a, remaining to @b)
  • Multiple sources: Pull from several accounts to fund a payment
  • Overdraft control: Express precisely how overdrafts should be handled. Accounts can be bounded (prevent negative balances), allowed a specific limit, or unbounded.
  • Metadata: Attach information to transactions for tracking
The @ symbol denotes an account. @world is a special account that is unbounded by default, useful for creating initial balances.
Learn more about Numscript →

​
Connectivity (Payments)

The Connectivity module is a separate system from the Ledger. It does not automatically write to your Ledger or affect balances there. Instead, it provides a normalized data store of your connections to external payment providers like Stripe, Wise, Adyen, and banks. Think of it as a unified view of:
  • Connectivity Accounts across all your providers
  • Balances for each external account
  • Transactions as they happen in those systems (via periodic polling)
The data in Connectivity and the data in your Ledger are independent. You use Flows (or your own application logic) to create Ledger transactions based on events from Connectivity when needed. Some providers also support write operations like initiating transfers or payouts. Check the Connector Capabilities table to see what each provider supports.

​
Connectivity Account types

  • Internal accounts: Accounts you control (e.g., your Stripe balance). You can see balances and potentially initiate transfers from these.
  • External accounts: Destination-only accounts (e.g., a customer’s bank account for payouts). You can send money to these but can’t see their balance.

​
Payment types

TypeDescription
PAY-INMoney coming in (e.g., customer payment)
PAYOUTMoney going out (e.g., paying a vendor)
TRANSFERMoving money between your own accounts

​
Cash pools

A cash pool groups accounts from different providers together. For example, you might pool your Stripe, PayPal, and bank accounts to see your total available funds across all of them. This is especially useful for reconciliation. Learn more about Connectivity →

​
Reconciliation

Reconciliation answers a critical question: Does the money in my ledger match the money in my actual accounts? Your Ledger tracks what should be true. Your payment providers track what is true. Reconciliation compares them and flags any differences.

​
How it works

  1. Create a policy: Define which ledger accounts to compare against which cash pool
  2. Run reconciliation: The system compares balances
  3. Review results: See if balances match or if there’s “drift” (a discrepancy)

​
Why it matters

  • Catch errors before they become problems
  • Prove to auditors that your records are accurate
  • Identify missing transactions or duplicate entries
Reconciliation is part of Formance Enterprise Edition.
Learn more about Reconciliation →

​
Flows (Orchestration)

Flows let you build automated, multi-step money operations. Instead of writing code to handle each step (and all the error cases), you define a workflow and Flows executes it.

​
When to use Flows

Use Flows when you need to:
  • Chain multiple operations: Move money in the ledger, then trigger a payout
  • Wait for events: Hold a transaction until a webhook confirms payment
  • Add delays: Release funds 7 days after purchase
  • Handle failures: Retry failed steps or run fallback logic

​
Example: Marketplace payout

A typical marketplace payout might:
  1. Wait for a “delivery confirmed” event
  2. Move funds from escrow to the seller’s account in the ledger
  3. Initiate a payout to the seller’s bank account
  4. Send a notification
With Flows, you define this once and the system handles timing, retries, and error cases.
Flows is part of Formance Enterprise Edition.
Learn more about Flows →

​
How They Work Together

Here’s an example of how the modules connect in a typical e-commerce marketplace:
  1. Customer pays via Stripe → Stripe processes the card payment
  2. Connectivity syncs the transaction → The Connectivity module polls Stripe’s API and picks up the new payment
  3. Flows reacts to the event → A workflow triggers when the payment is detected
  4. Ledger records the funds → The workflow creates a transaction moving funds from world to orders:123:pending
  5. Order ships → The workflow waits for the shipping confirmation event
  6. Funds released → Numscript splits the payment between seller (80%) and platform (20%)
  7. Payout initiated → Flows triggers a payout to the seller’s bank (for providers that support it)
  8. Reconciliation runs → Verifies your ledger balances match actual provider balances

​
The role of each module

  • Connectivity is a normalized data store of your external providers. It syncs connectivity accounts, balances, and transactions from providers like Stripe, Wise, and banks. It is separate from the Ledger and does not automatically create Ledger entries. Some providers also support initiating transfers and payouts. See the Connector Capabilities table for details.
  • Ledger is your internal source of truth: it tracks what assets exist and where they move within your system.
  • Flows is for orchestration: it reacts to events and coordinates multi-step operations across modules, including creating Ledger transactions based on Connectivity events.
  • Reconciliation is for verification: it compares your Ledger balances against your Connectivity data to catch discrepancies.

​
What’s Next?

Ledger Tutorial

Build your first ledger application step by step.

Numscript Guide

Learn to write transaction scripts.

Connect a Provider

Set up Stripe, Wise, or another payment provider.

API Reference

Explore the full Formance API.