Customer / Merchant
The party on whose behalf the operation happens, and whose balances and permissions apply.
Financial Execution Runtime
A financial operation is not finished when the API call returns.
Commercially, Orangepill is a financial execution control plane. Underneath, the Orangepill Financial Execution Runtime owns the lifecycle from economic intent through execution, authoritative state, verification, and governed resolution: from the intent your product expresses, to an outcome that has been checked against external reality.
Problem
The lifecycle of a payment is spread across systems that do not share state.
A checkout service decides. A processor executes. A ledger records. A reconciliation job compares, days later. An operations team decides what to do about the differences. Each part can work correctly while the operation as a whole is still unexplained.
- The product believes the payout failed. The provider later settles it.
- A retry is sent because nobody recorded whether the first attempt could still complete.
- A balance is correct, but nobody can show which events produced it.
Principle
Intent, execution, state, verification and resolution belong to one lifecycle. Separate them and every gap becomes manual work.
How it works
From intent to verified outcome, with Resolve when needed.
- Intent What your product wants to happen
- Orchestrate Journeys, policy and decisions
- Execute Authorized movement of value
- Verify Internal state vs. provider reality
- Verified outcome Internal and external state agree
- Resolve Evidence incomplete, contradictory or unsafe
Explicit about what is not known
Operations move through recorded states, and payouts are idempotent on their key. External rails are not
deterministic, so the runtime does not pretend they are: a payout send that may or may not have reached the
provider is paused for review instead of being sent again. (One current exception: when status checks run
out, a payout is marked failed with RETRY_EXHAUSTED even without a provider answer.)
Verification is a step, not a report
An operation is not treated as done because a provider said so. The ledger's expected state is compared with observed provider reality. Agreement produces a verified outcome. Disagreement goes to Resolve.
What exists in the platform
Nine objects describe an operation from intent to outcome.
These are the concepts you work with when you build on the runtime. Detailed semantics are in Core Concepts.
Economic Intent
What should happen in economic terms, such as "deliver this amount to this beneficiary", independent of any provider.
Flow
The journey around the intent: steps, approvals, KYC and risk checks, decisions. It coordinates; it does not move money.
Execution
The governed lifecycle that carries an intent to a financial outcome, with explicit state at every step.
Provider Attempt
One interaction with one external provider or rail. An execution may have several; each is recorded separately.
Wallet
A balance holder for a customer, merchant or program, whose balance is derived from ledger entries.
Ledger Entry
A double-entry record of a financial effect. The ledger is the authoritative internal state.
Proof of Record
Structured evidence explaining how an execution unfolded. It explains the ledger; it does not replace it.
Resolve Case
A governed case opened when an outcome is uncertain or contradictory, ending in an authoritative disposition.
A typical chain: Economic Intent → Execution → Provider Attempt → Ledger Entry → Proof of Record. A Resolve Case is opened only when that chain cannot be confirmed.
Composition
Specialists provide capabilities. The runtime controls the operation.
Build where Orangepill must own financial execution semantics. Integrate where specialists provide a capability better. Banks, local rails, PSPs, orchestrators, ledgers, identity providers, FX venues, messaging networks, commerce systems and AI models can sit underneath in this model; Orangepill composes native and external capabilities inside the same governed economic operation. Which providers are connected today is listed on the integrations page.
Context
Customers, merchants, identity, orders, products, forms and channels that an operation carries with it.
Authority
Policies, approvals, actors, agents and budgets that decide whether an operation may proceed.
Execution
Flows, payments, payouts, FX, rails and cross-border movement.
Financial state
Wallets, ledger, balances, settlement and treasury.
Control
Observe, explain, reconcile, verify, recover and resolve.
What Orangepill owns
The responsibilities that stay with the runtime, whoever executes underneath.
Where the architecture is ahead of the implementation, the table says so.
| Responsibility | Where it stands today |
|---|---|
| Economic intent | Payment intents over the API. Economic intents for agents through MCP tools. |
| Durable operation identity | Remittance intents link the pay-in and payout legs of a transfer. Not yet generalized to every multi-step operation. |
| Execution authority and policy | Scoped credentials, agent policies and human approval queues. Per-agent policy applies where configured. |
| Cross-system lifecycle | Payments and payouts run as governed lifecycles with attempts and statuses in production. |
| Financial state integration | Wallet balances derived from double-entry ledger journals in production. |
| Evidence and finality semantics | Provider events and attempts kept apart from operation status; payout finality checked with the provider. A complete Proof of Record is in development. |
| Reconciliation and Resolve | Reconciliation views in Console. Resolve is in development. |
| Execution observability | Timelines, attempts and the financial explain graph. |
| Blueprint composition | Blueprints package flows, agents, required integrations and configuration, and can be installed by tenants from Console. |
How it differs
Adjacent categories are strong at what they do. The runtime connects them.
Payment platforms, payment orchestration and financial control infrastructure each solve a real part of the problem, and many teams use more than one of them. Orangepill is not a replacement for processing, and it is not a payment service provider. Its focus is the lifecycle that runs across all of them.
| Category | Where it is strong | Where Orangepill focuses |
|---|---|---|
| Payment platforms | Processing, acceptance and integrated financial products, often at large scale and across many methods. | Governing operations that span several of these platforms and other rails, with one authoritative state across them. |
| Payment orchestration | Routing, optimisation, provider abstraction and the payment lifecycle across processors. | Carrying the lifecycle past the payment: ledger effects, wallets, payouts, verification and governed resolution when a provider outcome is unclear. |
| Financial control infrastructure | Ledgering, money movement, workflows and reconciliation. | Connecting that authoritative state to the product intent and the execution that produced it, and governing what happens after reconciliation finds a divergence. |
| Orangepill | Product intent → orchestration → financial execution → authoritative state → verification → governed resolution, as one lifecycle. | |
Compared with payment orchestration
Orchestration answers "which provider should handle this?" The runtime also answers "is it safe to ask another provider?", which depends on whether the previous attempt can still settle. Routing is one input to execution, not the whole of it. Multi-Rail Orchestration →
Compared with ledger and reconciliation infrastructure
A ledger records authoritative state, and reconciliation detects where it diverges from external reality. The runtime ties each ledger entry to the intent and provider attempt that caused it, and Resolve governs what happens after a divergence is found. Resolve →
Capabilities
Six capabilities implement the lifecycle.
Execution
A chain of API calls cannot tell you whether money moved. Execution governs each operation as one lifecycle.
Explore Execution →Multi-Rail Orchestration
Adding providers is easy. Knowing when it is safe to try another one is not.
Explore Multi-Rail Orchestration →Wallet & Ledger
Balances drift when they are stored as numbers. Here they are derived from recorded financial events.
Explore Wallet & Ledger →Proof of Record
Logs record what systems said. Proof of Record explains how a financial outcome was produced.
Explore Proof of Record →Resolve
When systems disagree or evidence is incomplete, Resolve determines what can safely happen next.
Explore Resolve →Agent Runtime
External or native agents need bounded financial authority and verifiable execution, not raw provider credentials.
Explore Agent Runtime →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.
See where the lifecycle breaks in your current stack.
We will map one of your financial operations across the systems it touches today, and show which parts the runtime would own.