Formance Stack is a double-entry ledger, a payments API and a money DSL in one monorepo

Three components that can be used whole or one at a time

Formance is described as a highly modular developer platform to build and operate complex money flows of any size and shapes, and it comes with several components that can be used as a whole as the Formance Stack or separately as standalone micro-services and libraries.

The three are named in the README. Formance Ledger is a programmable double-entry, immutable source of truth to record internal financial transactions and money movements. Formance Payments is a unified API and data layer for payments processing. And Formance Numscript is a DSL and virtual machine for monetary computations and transactions modeling.

The order matters for understanding the design. The ledger is the foundation, and the word double-entry is the load bearing part. Every movement of money is recorded as a balanced pair of postings, and the immutability means posted entries are not edited afterwards. That gives you an audit trail that a payments API on its own does not have, because a payments API typically stores a transaction record that can be updated or reconciled.

Payments sits above that and provides the operational API. Numscript sits below the domain in a different sense: it is the language in which you describe what a transfer means, so that the same monetary intent can be expressed once and evaluated on the ledger rather than being hand-coded as a series of postings.

The primary language of the repository is Go, the module is github.com/formancehq/stack with go 1.22.0 and a toolchain of go1.22.7, and the homepage is www.formance.com. The recent releases are v3.2.11 from 2026-09-04, v3.2.10 from 2026-08-06 and v3.2.9 the same day, and the last push to the repository was on 2026-09-25.

Installing the CLI and standing up a sandbox

The getting started path is a hosted sandbox, and it starts with a Homebrew tap.

brew tap formancehq/tap
brew install fctl

The fctl binary is then the entry point to everything else. Logging in and creating a sandbox deployment is three more commands.

fctl login
fctl stack create foobar
fctl ledger send world foo 100 EUR/2 --ledger=demo
fctl ui

Two details in that sequence are worth reading carefully. The comment in the README notes that sandbox are made available for testing and not made for production usage, with a pointer to the new sandbox guide in the docs. A sandbox is a shared or throwaway deployment of the whole stack, and it is a development environment.

The ledger send command is the interesting one, because it shows the shape of the data model. You send 100 EUR/2 to the account world, from the account foo, on the ledger named demo. The account names, world and foo, are yours to choose, and the EUR/2 is an amount in euros with two decimal places. The ledger is a partition, so the same chart of accounts can be kept separately per ledger, which is how you run separate books for separate businesses on one deployment.

The last command, fctl ui, opens the control dashboard in a browser. So the same CLI that creates deployments and posts transactions also fronts the operational interface, which means the dashboard is a view over the same API rather than a separate product.

Cloud native deployment, and the three technologies everything rests on

The deployment story is that the Formance Stack is distributed as a collection of binaries, with optional packaging as Docker images and configuration support through command line options and environment variables.

The recommended, standard way to deploy the collection of services is to a Kubernetes cluster through the official Formance Helm charts, and the chart repository is at helm.formance.com.

That is a deliberately narrow recommendation, and it says something about the operational profile. The components are stateful services that talk to each other, so a single-binary distribution is not the target. The stack expects a cluster.

The three underpinning technologies are named in the README. PostgreSQL is the main storage backend. Kafka or NATS handle cross-services async communication. And Traefik is the main HTTP gateway.

Read together, that is the shape of the deployment. Traefik in front as the ingress, a set of Go services behind it, PostgreSQL holding the durable state including the ledger, and a message bus between services. The choice of either Kafka or NATS is worth noting, because the two have quite different operational profiles and choosing the wrong one is a decision you will live with.

The top level of the repository backs this up. There is a base.Dockerfile for the shared image layer, a Justfile as the task runner, a flake.nix and flake.lock for the Nix development environment, an .envrc for direnv, a libs/ directory, an events/ directory, a releases/ directory and a .speakeasy/ directory, which is the tooling for generating client SDKs from an OpenAPI description.

A monorepo that imports versioned services, which is the awkward part

The Codebase section of the README explains the repository structure, and it does so candidly. Formance is transitioning to a unified public facing monorepo, this one, that imports versioned services submodules and provides a common infrastructure layer. As we are finalizing this transition, this monorepo is structured as below.

Then the list of technologies, and nothing else, which is the tell. The README does not enumerate the directories of the monorepo for the reader.

So the structure is: an outer repository that pulls in the individual services as versioned submodules, and a common infrastructure layer beneath them. The individual services, the ledger, the payments API, Numscript, live in their own repositories and are consumed at a pinned version. That means a bug fix in the ledger service does not automatically appear in the stack repository; it appears when the submodule pointer moves and the outer repo is updated.

This has a real consequence for operators. The stack is versioned as a whole, v3.2.11 and so on, but the components inside it are versioned independently, and a stack release is where those pins are decided. When you upgrade the stack, you are upgrading a set of coordinated versions, and the release notes of the outer repository are the place to look.

For a team evaluating this, it is worth asking how the pieces you actually want to run are released. If you only need the ledger, running it standalone as a service rather than through the stack is the path the README explicitly offers, and that path has fewer moving parts.

Numscript, and why a DSL for money is worth learning

Numscript is the component with the most unusual shape, and it is the one that will cost the most time to understand.

The README describes it as a DSL and virtual machine for monetary computations and transactions modeling. That is a compressed description of a real idea. A domain specific language for money lets you write a transaction as a set of sources, destinations and a transfer amount, and have the platform compute the balanced postings. The instruction fctl ledger send world foo 100 EUR/2 --ledger=demo is the simplest possible instance of that.

The reason this exists is that double-entry is precise and unforgiving, and hand-writing postings for every business transaction is error prone. If your product has complex money flows, of the sort the README calls complex money flows of any size and shapes, then modelling them as Numscript programs means the model is written once, reviewed as code, and evaluated consistently.

The cost is that you are learning a language and its virtual machine rather than calling an API. There is no documentation of Numscript in this README, so the language reference lives in docs.formance.com along with the rest of the platform documentation.

That documentation split is worth flagging generally. The full documentation for the Formance Stack can be found at docs.formance.com, and the repository README is an overview plus a quickstart, which is the right shape for a project this size but means you will be reading the docs site rather than the repository for most of the detail.

Where Formance Stack is the wrong choice

Three cases, and the third is the one that gives a team the most trouble.

First, if you need a hosted payment gateway rather than a platform for building one. Formance Payments is a unified API and data layer for payments processing, and the ledger is the accounting substrate. Neither of those is a checkout page, a set of payment method integrations and a dashboard for merchants. If the requirement is to start taking cards next week, this is infrastructure to build on, not a service to sign up for.

Second, if your operation does not need double-entry. If you are recording a small volume of simple transfers and the accounting is a spreadsheet, the immutability and the balanced-posting model of the ledger bring constraints you do not yet need, and Numscript is a cost with no payoff.

Third, the licence. The repository records a custom licence that GitHub cannot classify, and the terms are in the LICENSE file. That is a specific thing to check and it is not a formality. The README carries an MIT badge, but that badge links to the ledger repository's LICENSE, which is a different repository from this one. For a component that holds financial records, the difference between what the badge suggests and what the licence file in this repository says is exactly the kind of thing that needs a lawyer rather than a guess.

On maintenance, the shape is a working platform with releases every few weeks, v3.2.11 on 2026-09-04 and two releases on 2026-08-06, and a last push on 2026-09-25. The releases directory in the repository and the Justfile task runner are where a self-hosted operator would look for the version-specific instructions.

Editorial conclusion

Adopt Formance if you are building money movement and need double-entry accounting as the source of truth rather than as a reporting afterthought, and you are prepared to read the Numscript DSL and the licence. Do not adopt it as a general payment gateway, because it is a developer platform for building one, and check the licence file before you commit, since the repository records a custom licence rather than MIT or Apache. Verify first which of the three components you actually need, since the ledger, the payments layer and Numscript are separately deployable and separately versioned.

Frequently asked questions

Official sources

1. formancehq/stack on GitHub
2. Issues
3. Project website
4. README
5. Releases