How to Develop a Crypto Payment Gateway for Multi-Rail Payments
To see how Formance fits your multi-rail crypto payment gateway.
Getting a crypto payment architecture wrong has concrete consequences.
Weak controls over wallet migration and deposit routing in Prime Trust’s payment gateway meant the system continued to direct inbound funds to legacy wallets the firm could no longer access, contributing to unrecoverable deposits and a later shortfall. It resulted in receivership in June 2023, with Prime Trust owing clients $85.67 million in fiat crypto but holding only $2.9 million on hand.
As payment infrastructure expands, each new rail or asset typically adds custom integration logic, a new data format, a new settlement timeline, and a new reconciliation gap. Teams now have to build across multiple chains, stablecoins, fiat rails, geographies, and regulatory regimes.
Crypto payment gateway development is about designing a multi-rail payment architecture on those terms to accommodate new assets and payment rails without having to rewrite money-movement logic each time.
This guide starts with the core components a multi‑rail crypto gateway needs, then walks through eight steps for developing this architecture.
A multi‑rail crypto payment gateway is the layer that lets merchants and platforms accept crypto and stablecoin payments while routing them over different settlement channels such as blockchains and stablecoins, bank transfers, card networks, and local methods. It keeps the product experience consistent while selecting the appropriate rail for each transaction.
Each rail has its own messaging formats, settlement model, timing, and failure modes. Traditional rails and stablecoin transfers differ in how messages are routed, how finality is achieved, and how exceptions are handled. A multi‑rail architecture isolates this rail‑specific logic behind a shared orchestration and core ledger layer, with the ledger as the system of record.
Crypto gateways handle details that card and bank gateways typically don’t handle directly: address generation, transaction broadcasting, confirmation tracking, gas and fee management, and chain reorganization handling.Finality is probabilistic and cost varies with gas and network conditions.
Gateways can be non‑custodial, routing funds directly to merchant‑controlled addresses, or custodial, holding funds during settlement and falling under regimes such as MiCA, FCA crypto‑asset rules, or equivalent local frameworks. In both cases, each blockchain or stablecoin behaves like a rail alongside fiat settlement rails.
A production-grade, multi-rail crypto gateway is a full payments platform. In practice, it typically includes six core components:
The primary build challenges are regulatory compliance, banking partnerships for fiat settlements, cryptocurrency price volatility, high-availability infrastructure, and a development team with expertise in both blockchain and payment systems. The eight steps below walk through how to assemble the six components into an architecture that scales with each new rail.
Clarifying product and compliance scope means defining who is paying whom, which currencies and regions you support, and which regulatory regimes apply before any code gets written. Scope also covers the settlement model across crypto and fiat, as well as whether the product is merchant-facing, treasury-focused, or both.
Next, map regulatory and compliance constraints that directly affect how you can hold or move value. Under Article 14 of the EU's Transfer of Funds Regulation (TFR), every CASP-to-CASP transfer requires full originator and beneficiary data at zero threshold.
Under the FATF's Travel Rule, originator and beneficiary data must be transmitted between counterparties for covered transfers, so many VASPs implement the Travel Rule as a pre‑transfer or in‑flight compliance gate. Compliance controls such as KYB, sanctions screening, transaction monitoring, approvals, and reporting still need to work across rails, and licensing (EMI, MTL, and MiCA CASP authorization) plus fund safeguarding rules can shape what your system can do at a data model level.
Decide compliance constraints early. Retrofitting compliance into a non-compliant custody model after launch is significantly harder than building for compliance from the start, because it forces data-model changes, custody migrations, and often re-licensing on top of an already-live system.
Core payment and settlement flows cover payment initiation, address or invoice generation, on-chain confirmation, settlement, refunds, and exception handling. Plan each flow explicitly before implementation.
Use a payment state machine to track each payment through the cycle. The definitive payment state at any stage of the cycle determines whether a failure triggers a retry or a refund. Persist payment state in an append-only table. Route retryable errors to a retry queue; route repeatedly failing messages to a dead letter queue for manual inspection.
Decide how much on-chain complexity you abstract from merchants. Confirmations, gas fees, network fees, and failed transactions all need to be handled. On some chains, a failed transaction can still consume gas even if no asset transfer completes, so fee handling needs its own accounting path.
If you need to settle in fiat, decide where conversion happens: an instant swap at payment time, periodic batch conversion, a separate treasury process, or a mix. Each option produces different ledger postings and different reconciliation patterns.
Your multi-rail model defines which rails you support, their priority, and how routing logic chooses among them for each transaction. A scannable decision table makes routing logic explicit:
| Rail | When to use | Fallback |
| USDC on Ethereum | Example default for higher-value stablecoin payments | USDC on Base |
| USDC on Base | Example lower-fee or congestion fallback | USDC on Solana |
| USDT on Tron | Example regional or asset-preference route | USDC on Ethereum |
| ACH | US fiat settlement, non-urgent | Wire |
| Wire | High-value fiat settlement, same-day required | ACH |
| SEPA | EU fiat settlement | SEPA Instant |
Store routing rules in configuration. The engine can evaluate customer geography, asset type, transaction size, and charge type against routing rules in order of priority, then select a matching connector.
Compliance checks must execute before optimization logic. Geography-based and stablecoin-type compliance checks gate which chains appear in the eligible candidate set before any optimization runs.
Keep routing logic separate from provider integration code. When a provider updates an API or deprecates an endpoint, the orchestration layer absorbs the change without touching routing rules. Routing and provider integration evolve independently.
Routing decides where money goes; the ledger and orchestration layer record what actually happened.
A multi-rail gateway is architected around two layers: a core ledger that records every movement, and an orchestration layer that drives state across rails. Every incoming payment, settlement, fee, and conversion across every rail posts to the ledger.
For a ledger, the double-entry model should be treated as non-negotiable. Every debit has an equal credit, balances are derived from an immutable log, and the ledger structures financial events into verifiable postings rather than overwriteable balances.
The orchestration layer handles payment intents, state machines, webhooks, retries, and idempotency for each rail. Idempotency keys prevent duplicate transactions during mempool delays or network rebroadcasts; for Bitcoin payments, keys should be retained long enough to outlast any possible confirmation delay, usually 24 hours or more. For example, six confirmations at ~10 minutes per block, plus margin for reorgs and node propagation lag.
Treat external rails (blockchains, custodians, payment processors, and banks) as connectors behind the core. Your internal ledger remains the source of truth, while the orchestration layer triggers movement through connected providers; the ledger records what happened. Formance Ledger is one example of a programmable core ledger designed to serve as a single source of truth for multi-rail payments, rather than relying on each rail's own records.
Your custody model shapes how keys are managed and what security posture and UX you can offer. Four options exist, each with distinct engineering properties:
Whichever model you choose, each provider integration must emit events and data that reconcile back to your internal ledger. Every deposit detection, confirmation, and settlement broadcast produces a corresponding internal posting.
On-chain reconciliation means transforming raw blockchain execution data into accounting-consistent records by identifying transactions, interpreting economic meaning, valuing transactions, and matching them against your internal ledger.
Matching wallet balances alone is insufficient because balances don't capture timing, fee splits, or per-payment attribution. They only show a net position.
A production reconciliation engine must handle four matching patterns:
The Formance Reconciliation module runs policy-based matching at configurable intervals, supports temporal reconciliation for cut-off handling, and compares ledger and external records to detect drift across connected financial systems.
A customer sends 1,000.00 USDC on Ethereum to a deposit address for invoice #4052.
set_tx_meta("invoice_id", "4052")
set_tx_meta("rail", "ethereum")
set_tx_meta("quoted_rate", "0.9995")
send [USDC/6 1000000000] (
source = @world
destination = @payments:4052:pending
)send [USDC/6 1000000000] (
source = @payments:4052:pending
destination = @conversion:usdc-usd
)send [USD/2 99950] (
source = @conversion:usdc-usd
destination = @payments:4052:settled
)send [USD/2 50] (
source = @conversion:usdc-usd
destination = @fees:conversion
)send [USD/2 1499] (
source = @payments:4052:settled
destination = @platform:fees
)Status: PENDING_CONFIRMATION. Any network fee should be recorded as a separate expense posting against a fee account such as @fees:gas:eth.
Net merchant settlement: $984.51. The merchant's settled account holds $984.51, the conversion fee account holds $0.50, and the platform fee account holds $14.99. Total: $999.50, plus the gas expense recorded separately.
If the conversion provider's settlement report shows $998.00 instead of $999.50, the reconciliation engine flags a $1.50 drift on @conversion:usdc-usd. The three-way reference chain (internal_transaction_id to provider reference ID to on-chain transaction hash) pinpoints whether the discrepancy originated in the conversion rate, the provider's fee calculation, or a timing mismatch.
Plan operational reporting for finance and compliance teams: outstanding payments, settlements in flight, failed or stuck transactions, and fee breakdowns, sliceable by customer, rail, asset, and geography.
A gateway is only as usable as its developer APIs and operator tools. For developers, they must design clean APIs and webhooks for payment initiation, status tracking, refund handling, and cross-rail events. A payment lifecycle should expose consistent status values (PENDING, CONFIRMED, SETTLED, FAILED) regardless of which rail processed the transaction.
Operators must provide internal tooling for monitoring fund flows, investigating exceptions, pausing rails, and safely changing routing rules. Finance teams need control over how transactions are ingested, transformed, and reported; automation should never mean losing oversight.
Keep developer and operator surfaces rail-agnostic where possible. Teams should reason about payments and settlements across providers, not per-rail.
Treat the chain or rail as a parameter in the integration model. Adding a new chain should reuse the existing API path and integration model, with updated routing and support logic underneath.
Define a clear process for adding rails without impacting existing flows. Isolate configuration, including routing rules, limits, and supported assets, from code so you can respond quickly to new opportunities and regulatory changes. A new stablecoin means a new issuer adapter; a new fiat corridor means a new off-ramp connector. Neither should require changing the ledger model or reconciliation infrastructure.
Include testing and rollout patterns to reduce risk. One practical approach is to activate a new chain in a limited operational scope first, validate its characteristics at a limited scale, and only then expand.
Every rail bolted onto a single-rail gateway adds reconciliation risk to the next settlement window. Every custom script written to match on-chain transfers against payment service provider payouts becomes ongoing maintenance work. A core ledger serves as the foundation and single source of financial truth, alongside normalized connector events, orchestrated workflows, and automated reconciliation.
Formance Ledger is an open-source ledger for fiat and digital assets, licensed under the MIT license. Numscript, Formance's purpose-built language for money, describes flows of funds in terms both engineers and finance teams can read.
Formance does not hold or move funds itself; it triggers payouts and transfers through connected PSPs, banks, exchanges, and custodians. Engineering teams typically start with the open-source ledger, then layer in Connectivity, Flows, and Reconciliation as the gateway adds rails.
A practical guide to money movement architecture for fintechs running multiple payment rails. Learn how a ledger-first design absorbs new rails without compounding technical debt.
Learn how regulated fintechs should architect stablecoin payments, including on-ramp, off-ramp, and reconciliation infrastructure.
FedNow makes settlement instant and irrevocable. Learn how to handle retry logic, ledger design, reconciliation, and fraud controls on real-time rails.