See the architecture yourself
Explore the open-source Formance Ledger on GitHub and the Formance documentation to see the architecture yourself.
On September 7, 2023, Square went offline for roughly nine hours during a business day. Merchants running Square as their only processor had no fallback path; one ice cream shop, Urban Churn, lost $8,000–$10,000 in revenue during the outage window. For fintechs routing every transaction through a single provider, single-provider architecture loses revenue every day, one declined transaction at a time, with no second acquirer to try.
A payment orchestration layer is the control plane that routes each transaction across multiple PSPs, handles failover, and hands off confirmed outcomes to a core ledger for immutable recording. It matters for fintechs, embedded finance platforms, and SaaS teams that run more than one PSP to keep payments available and lift authorization rates. For engineering and finance leaders, the stakes are revenue continuity and knowing whether routed payments actually settled.
Most significantly, a payment orchestration layer addresses the routing layer. However, it does not tell you where the money actually is at any moment; that is a separate problem, and the architecture keeps routing control and financial state apart. Call it the route/record split: the routing plane decides where a payment goes, the record plane proves where it landed.
Start with where the orchestration layer actually sits in the stack, then work through its four components, the ledger layer underneath, and the build-versus-integrate decision that follows.
The payment orchestration layer sits between your product and your processors, governing provider selection and routing logic across multiple payment rails with transaction lifecycle control built into the same layer, such as retries, state transitions and timeout handling. Each transaction is routed based on rules such as cost, geography, payment method, performance, or availability.
The payment orchestration layer replaces direct point-to-point PSP integrations, where each provider forces custom logic, webhook handling, and reconciliation scripts maintained outside the core flow.
However, this layer handles provider selection and failover, while the ledger records the resulting postings and maintains authoritative balance state. In this case, the Formance Ledger remains a distinct system from the payment orchestration layer.
The payment intent moves from the application to the orchestration API, then to ledger postings after PSP selection and exception handling. The core ledger records the resulting double-entry postings and holds authoritative balance state independently of what any individual provider reports back.
The four components of a payment orchestration layer are the routing and failover engine, the normalized provider connector layer, the network token vault, and the settlement and reconciliation output. Each component stays architecturally separate but coordinated through a shared internal schema.
The routing engine evaluates every incoming payment against configurable rules, including card BIN, issuer country, currency, amount, and MCC. It compares those inputs across each PSP's fee schedule and historic success rate, with latency folded into the same decision. The engine picks a provider for each transaction.
Timeouts and hard errors trigger provider degradation, which is the same failover when health probes show three or more consecutive errors within a 60-second window (tune to your traffic). Health probes track each PSP's availability, and a circuit breaker pulls a provider out of rotation after those errors clear a threshold. For debit transactions, routing can also choose between eligible networks where local network rules and issuer coverage permit network selection.
Routing is also where authorization-rate lift comes from. Matching each transaction cohort (defined by BIN range and issuer geography) to the acquirer with the highest historic approval rate for that cohort delivers meaningful lift.
Retry-with-routing extends the same mechanic to soft declines because an orchestration layer resubmits eligible soft declines to a different acquirer whose issuer relationships approve at a higher rate, recovering revenue that a single-provider architecture loses permanently.
The connector layer translates one internal schema to and from each PSP's API, so routing logic never touches provider-specific formats. When a PSP changes its API, only the PSP's adapter changes; the routing engine is unaffected.
Payment rails differ in ways no single status model absorbs, so connector schemas need versioning. A stablecoin transfer settles with cryptographic finality, but bank and real-time payment rails carry different return rules, finality constraints, and network-availability windows.
Practitioner reports consistently place gateway connector and routing maintenance among the top two ongoing engineering costs in multi-PSP stacks, because PSPs change formats on independent release schedules.
The token vault stores and synchronizes network tokens across your acquirers. Each token is randomized and individualized to a specific merchant.
The merchant-token binding is what your routing logic must preserve. Mastercard's gateway documentation explicitly exposes the token requestor and merchant relationship through the tokenRequestorId and relationshipId fields, tying a token repository to a specific merchant account.
When token lifecycle data falls out of sync across acquirers, the transaction returns a token-related decline that a synced vault would have avoided.
The payment orchestration layer produces a consolidated view of approvals, declines, and fees across every payment channel, and this consolidated view is not your system of record. A settlement often arrives as a single net figure, with provider reports holding fee detail and reserve movements, and separate currency-conversion records arrive in formats your finance team did not design.
Each provider returns settlement data in a different schema. Transaction IDs get truncated between systems, and authorization and settlement can land on different days at different FX rates. The payment orchestrator records what it routed and what came back. The acquirer's settlement file records what actually happened to the money, and the two records regularly disagree.
Payment orchestration needs an immutable ledger layer because routing alone cannot prove where the money is; without a separate, append-only record of every attempt and settlement, the records drift the moment two providers disagree.
The route/record split lives or dies here because routing decisions belong in the orchestration layer. Still, financial state belongs in an immutable core ledger, and most orchestration architectures skip the ledger design, collapsing the split and leaving the record plane implicit.
When routing and record-keeping are conflated, the system ends up inferring money movement from provider webhooks, and that inference breaks under multi-provider load. PSP webhooks arrive under at-least-once delivery semantics, so duplicate events are a design condition rather than an edge case.
The moment two providers disagree (one reports a settled payment while the other retries the same event), the figures drift. There is no independent record to arbitrate which version is true.
An immutable ledger fixes this by recording every attempt, failover, and confirmed settlement as a discrete double-entry event, independent of what any single provider reports.
Double-entry postings capture financial state atomically. Both legs of a transaction commit or neither does, and the ledger keeps the full attempt history so balances reflect confirmed settlement events once provider outcomes are reconciled.
Build in-house payment orchestration layer only if you run three or more active PSPs, employ dedicated payments-platform engineers, and need corridor-specific routing your vendor cannot inspect or extend. Integrate a payment orchestration layer (or self-host an open-source stack) when you're running one or two PSPs, processing under roughly $10M/month, or lack a dedicated payments-platform team to own connectors and reconciliation long-term.
| Dimension | Build in-house | Integrate a vendor |
| Volume fit | $50M+/month, 3+ active PSPs, dedicated payments-platform engineers | Under ~$10M/month, 1–2 active PSPs, and no payments-platform team |
| Routing control | Full corridor-specific rules, and custom ML-assisted selection | Constrained by vendor roadmap; advanced rules gated behind higher tiers |
| Connector coverage | Every PSP you commit to maintain, on their release schedule | Broad but incomplete; niche PSPs and regional acquirers force hybrid direct connectors |
| Maintenance surface | Six permanent obligations (connectors, routing rules, token vault, idempotency, fraud, and settlement normalization) | Vendor absorbs core maintenance; you still normalize their settlement schema |
| Cost curve | High up-front build cost, and flat marginal cost | Low entry cost; pricing tiers re-open at $50M/month volume |
| Governance breakpoint | Rational default once you cross five active providers | Rational default at one or two PSPs where basis points don't justify the risk |
Building in-house means committing to six durable engineering obligations,
The build cost is paid up front because the maintenance cost is permanent, and because PSPs change APIs and networks change retry rules on independent schedules.
Integrating a vendor trades that maintenance for a different set of constraints. Vendor routing engines are typically proprietary, so corridor-specific optimizations stall at the vendor's roadmap.
Connector coverage rarely spans every niche PSP or regional acquirer, which forces a hybrid architecture where your team still maintains direct connectors alongside the platform.
Advanced routing rules sit behind add-ons or higher pricing tiers. The vendor's settlement reporting also becomes one more schema your core ledger has to normalize, adding a reconciliation surface rather than removing one.
The volume threshold makes the choice concrete. Teams processing under roughly $10M/month with one or two active PSPs rarely justify a custom build. Engineering focus is the scarcest resource, and the risk of getting vaulting, state, and reconciliation wrong outweighs the basis points available from routing.
Once you cross five active providers, the bottleneck shifts from connectivity to governance regardless of volume, and self-hosted architectures on an open-source ledger core become the rational default. Whichever path you pick, the ledger stays yours, which is where the architecture principles in the next section apply.
The four architecture principles are: enforce idempotency at the routing layer, record every attempt as a discrete ledger event, separate routing configuration from execution, and version connector schemas independently. Apply all four whether you build or integrate:
A composite unique key on (caller_id, idempotency_key), backed by a UNIQUE constraint at the SQL level, blocks network-layer retries and application replays from producing duplicate postings downstream.
2. Record every payment attempt (including soft declines and timeouts) as a discrete event in the core ledger
When an acquirer times out, the payment sits in an AUTH_UNKNOWN state; the orchestrator queries the acquirer's status endpoint before any retry, and failed attempts remain available for reconciliation against settlement files.
Once the outcome is confirmed, the reallocation itself is a discrete double-entry event. A $185,000 settlement reattributed from the primary PSP counterparty to the secondary PSP counterparty after failover, expressed in Numscript as a single atomic send:
// PSP_SETTLEMENT_REALLOCATION
// Reattribute a confirmed $185,000.00 settlement from the primary PSP
// to the secondary PSP after failover reconciliation
send [USD/2 18500000] (
source = @counterparties:psps:primary
destination = @counterparties:psps:secondary
)
set_tx_meta("event_type", "psp_settlement_reallocation")
set_tx_meta("settlement_id", "stl001")
PSP additions and BIN-routing shifts should deploy as configuration changes that never touch the transaction processing path. Cost-threshold adjustments should follow the same path, and each connector remains testable and swappable.
A PSP API deprecation should change one adapter without forcing a routing engine rebuild; coupling the two makes both failure surfaces cascade together.
Together, the four invariants above keep routing changes from corrupting financial state.
Building a payment orchestration layer that holds up in production means enforcing the route/record split: from day one. It means routing decisions live in the payment orchestration plane, and every attempt, failover, and settlement lands as a discrete event in an immutable ledger underneath.
Whether you build in-house or integrate a vendor, the ledger is the part you cannot outsource. An immutable, double-entry core that records every attempt independently of what any single provider reports is what turns routing from a revenue lever into a system your finance team can actually close the books on.
That's the foundation Formance is built to provide, so your team can focus engineering effort on the routing logic that differentiates your product rather than rebuilding the record plane underneath it.