Economic intent
Your product states what should happen in economic terms: deliver this amount to this beneficiary. The intent stays the same even if the way it is executed changes.
Execution Production
Financial operations need a lifecycle, not a chain of API calls.
When a payout, transfer or capture is a sequence of requests and callbacks, your system can only guess whether money moved. Orangepill executes each operation as one governed lifecycle, so its state is known, its attempts are recorded, and its next step is decided from evidence.
Problem
An API response is not a financial outcome.
Most integrations treat a provider call as the operation. Send the request, wait for a response or a webhook, update a status column. That works until the response does not arrive, arrives twice, or arrives with a state that changes later.
- A request times out. The provider may still be processing it.
- A retry creates a second payment because the first one was never marked as possibly in flight.
- A status says "completed", but no ledger entry explains where the money went.
- Recovery logic lives in scattered job handlers that nobody can reason about as a whole.
Principle
A timeout does not mean the payment failed. Retrying blindly can move value twice. Execution state has to be known before anything happens next.
How it works
One operation, one lifecycle, every attempt accounted for.
Strategy
The runtime decides how to fulfil the intent: which provider or rail, in what order, under which limits and policy. Strategy can change between attempts; the intent does not.
Execution attempts
Each interaction with a provider is a separate, recorded attempt. An execution can have several, and the runtime knows which ones could still produce an effect.
Idempotency
Duplicate requests from your product, and retries inside the runtime, are recognised as the same operation rather than new ones.
Finality
The runtime tracks whether an attempt's outcome is final, pending, or unknown. "Unknown" is a real, explicit state, not an error to be retried away.
Ledger effects
Value movement is recorded in the double-entry ledger as the lifecycle progresses, so balances reflect what the execution actually did.
Example
A payout times out.
The product requests a payout. The runtime calls the provider, and the request times out. The provider may have received it, may be processing it, or may never have seen it.
- Payout requested Economic intent recorded
- Provider called Attempt recorded
- Request times out Execution state becomes uncertain
- No blind retry The first attempt may still settle
- Observe and reconcile Query the provider, compare with the ledger
- Continue Outcome established; lifecycle proceeds
- Resolve Evidence still unclear; governed case
The payout does not get sent twice because a timer fired. It either continues on established evidence, or it becomes a Resolve case with the full history attached.
Architecture
Execution moves value. Orchestration decides around it.
Flows coordinate journeys, approvals, KYC and risk steps. They hand financial work to execution; they do not move money themselves. That boundary is what lets retries, failover and recovery be decided by something that knows the financial state.
Inside the runtime, state transitions are deterministic. Outside it, providers and rails are not, which is why uncertainty is modelled explicitly and handed to verification and Resolve rather than hidden.
Read the technical architecture: lifecycle, idempotency, ledger authority, tenant isolation →
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.
Show us the operation you are least sure about.
A payout that times out, a capture that arrives late, a refund that reverses. We will walk through how its lifecycle would be governed.