Customer / Merchant
The parties on whose behalf value moves. Every operation is scoped to them and to a tenant.
Financial Runtime · Architecture
Value moves through governed lifecycles. The ledger records what is true.
This is the technical view of the runtime: how an operation is modelled, where the boundary between orchestration and financial execution sits, how state is recorded, and what happens when external systems do not behave predictably.
Why it is built this way
External rails are not deterministic. The runtime around them has to be.
Providers time out, notify late, notify twice, settle partially, and occasionally contradict themselves. A system that treats each provider response as the truth inherits all of that. The runtime takes the opposite position: it owns the lifecycle of each operation, records internal state under its own rules, and treats provider responses as evidence to be evaluated.
- Orchestrate Flow: journeys and decisions
- Economic Intent What should happen
- Execute Lifecycle and provider attempts
- Ledger Authoritative state
- Verify Against provider reality
- Resolve When evidence is unclear
Lifecycle execution
An operation is a state machine, not a sequence of calls.
Each financial operation has an explicit lifecycle. It moves between defined states only through defined transitions, and each transition has preconditions: an authorization must exist before value is committed; an outcome must be established before ledger effects become final.
The important states are not only success and failure. An operation can be pending at a provider, or uncertain: a request was sent and no reliable answer came back. Uncertain is a first-class state, not an error code. Treating it explicitly is what prevents the most expensive mistakes, such as paying a beneficiary twice because a timeout was read as a failure.
State transitions are deterministic: given the same recorded state and the same input, the runtime makes the same decision. That does not make external rails deterministic. It means the runtime's own behaviour is reproducible and explainable when they are not.
Flows and financial execution
Workflows decide. Execution moves value.
A flow orchestrates the journey around a financial operation. It does not move money. When a flow reaches the point of moving value, it hands an economic intent to financial execution, which owns everything from provider selection to ledger effects. This boundary keeps business logic changeable without touching the part of the system that must be conservative.
| Flow orchestrates | Financial execution handles |
|---|---|
| Customer, merchant, operator and agent journeys | Value movement across providers and rails |
| Business decisions and routing intent | Provider selection and execution attempts |
| KYC and risk steps | Finality: is the outcome established? |
| Approvals and waiting on people | Ledger effects and wallet changes |
| Notifications and interaction | Financial remediation: retry, compensate, reverse |
The commercial view of execution is on the Execution page.
Financial primitives
The objects the runtime reasons about.
These are the platform concepts that appear in the API and documentation. They are deliberately few, and each has one job.
Economic Intent
What should happen in financial terms: pay this seller, fund this wallet, deliver this amount abroad.
Flow
The journey and decision logic around the intent: checks, approvals, customer interaction.
Execution
The governed lifecycle that carries an intent to a financial outcome.
Provider Attempt
One interaction with one external rail. An execution may contain several.
Wallet
A product-facing financial position, derived from the ledger.
Ledger Entry
One side of a balanced journal recording a financial effect.
Proof of Record
Structured evidence of how an execution unfolded.
Resolve Case
A governed process for an operation that cannot safely continue on its own.
Ledger authority
The ledger is the authority, not a report.
Internal financial state lives in a double-entry ledger. The ledger service posts balanced journals: every movement has a debit and a matching credit. Posted amounts are not edited. Refunds and reversals are posted as new inverse entries that reference the original payment. Each journal references the operation that produced it.
The architecture is designed so that financial execution, not product workflows, produces ledger effects. That separation is what lets reconciliation compare the ledger with provider reality and get a meaningful answer. Tightening it into a single, enforced write path is ongoing work.
Wallets
Wallets live inside the settlement boundary.
A wallet is a product-facing view of ledger state: available, reserved and pending amounts per currency. Operations that use wallet value, such as a balance applied to a checkout, move it from available to reserved and then consume or release it when the outcome is established. Holding them for as long as an outcome is uncertain, however long that takes, is part of the Resolve work currently in development.
Wallets can be funded from external payments, pay out to external rails, or move value between each other internally. Hybrid flows that combine internal balances with external rails are modelled as one operation, so a partial outcome on the external side is visible as such on the wallet. Wallets record positions; funds themselves are held by the banks and providers involved.
More on balance models: Wallet & Ledger.
Provider orchestration
An operation can have many attempts. Only one outcome.
Providers connect the runtime to banks, processors and settlement networks. Each interaction with a provider is recorded as a separate attempt under the parent operation, with its own request, responses and observed state.
Routing chooses an eligible provider for the intent based on capability, destination and health. Failover to another provider is permitted only when the previous attempt is known not to have produced, and not to be able to still produce, an economic effect. Pay-ins and payouts differ here: a duplicated pay-in is usually refundable; a duplicated payout often is not.
More on routing and failover: Multi-Rail Orchestration.
Idempotency and finality
Duplicates are expected. Duplicate effects are not acceptable.
Inbound
Payout requests require an idempotency key, unique per tenant. Payment and refund requests accept one. A repeated request with the same key resolves to the existing operation instead of creating a new one.
Outbound
Provider notifications are deduplicated on receipt. On the pay-in path, ledger journals are unique per operation, so a repeated notification does not post a second effect.
Idempotency limits what the runtime itself can duplicate. It cannot make an external rail exactly-once. Where a rail offers no safe way to ask "did this already happen?", the runtime keeps the operation in an explicit uncertain state and recovers based on finality evidence, rather than retrying on a timer.
Proof of Record
Evidence is produced as a side effect of execution.
Because the runtime owns the lifecycle, it can record the intent, authorization, state transitions, provider attempts, wallet effects and ledger entries for each operation as they happen. That record is the Proof of Record. It explains how the ledger state was reached; it does not replace the ledger as the authority on what that state is.
More: Proof of Record.
Verification and Resolve
Reconciliation before remediation.
Verification compares the ledger and execution record with what providers report. Most operations match. Those that do not, and those whose outcome cannot be established, are designed to become Resolve cases. Resolve works through Investigate → Establish → Decide → Verify and ends in an authoritative disposition: Continue, Wait, Remediate or Escalate. Remediation itself is carried out by financial execution, under the same lifecycle rules.
Status: Resolve is in development. Today, uncertain outcomes surface as explicit non-terminal statuses with timelines and attempt history.
- Ledger and Proof of Record Expected state
- Verify Compared with provider reality
- Match Verified outcome
- Mismatch or uncertain Resolve case
More: Resolve.
Tenant isolation
Each tenant has its own financial state.
Every operation, wallet, ledger entry and permission carries a tenant, and tenant scoping is enforced in the application layer on every request. For platforms that serve their own customers, such as BaaS programs or marketplaces, this scoping is what keeps one program's balances and evidence separate from the next.
Agents
Agents submit intents. They do not bypass execution.
Software agents interact with the runtime through scoped tools and an identity of their own. Their requests become economic intents and go through the same execution lifecycle and ledger as any other operation. Per-agent policy checks apply where a policy has been configured for the agent. Agent-specific controls are still being extended; see Agent Runtime for current status.
For developers
Inspect how to integrate it.
The v4 API is described by an OpenAPI contract. Start with the quickstart, then the parts that matter in production: errors, webhooks and the sandbox.
- Quickstart Authenticate, choose an environment, create a payout.
- API reference Representative v4 routes, objects and lifecycle statuses.
- Errors Errors versus unknown outcomes, and when retrying is safe.
- Webhooks Signatures, at-least-once delivery, retries and ordering.
- Sandbox Deterministic test provider, including failure outcomes.
- Integrations Providers, rails and channels in the catalog.
Review the architecture against your own stack.
Talk to an infrastructure engineer about where the boundaries would sit in your system.