Wallets
Balances, reserves and holds per account and currency. Funding, payouts and settlement all change a wallet through the ledger, so available and reserved amounts stay consistent with what has actually been recorded.
Wallet & Ledger Production
A balance is not a number. It is the result of financial events.
Wallets give your product a financial position it can show and act on. The ledger is where that position comes from. Every balance is derived from recorded entries, so it can always be explained.
Problem
Balances drift when they are stored as numbers.
Many products keep a balance column and update it whenever something happens. It works until two updates race, a webhook arrives twice, a refund lands after a payout, or a provider settles less than expected. Then the number is wrong, and nothing in the system can say why.
- A wallet shows funds that are already committed to a pending payout.
- A duplicate provider notification credits the same deposit twice.
- A seller balance cannot be traced back to the orders, fees and refunds that produced it.
- Finance rebuilds balances from spreadsheets at month end because the product number cannot be trusted.
Principle
Financial events → Ledger entries → Authoritative balance.
Wallet: the product-facing financial position
What a customer, merchant or seller holds, what is available, and what is reserved. It is what your product displays and what your rules check before value moves.
Ledger: the authoritative financial state
A double-entry record of every financial event. The ledger is not a report generated afterwards. Wallet balances are read from it, never written around it.
How it works
Four parts of one model.
Ledger
Double-entry: every movement has a source and a destination, posted as a balanced journal. Posted amounts are not edited; refunds and reversals are new inverse entries that reference the original payment.
Lifecycle
Capture, refund, reversal, fee and adjustment are distinct financial events with their own entries. A refund does not delete a payment; it records a new movement linked to the original.
Hybrid value
Internal balances and external rails in one model. Value held with a provider or bank and value moving between internal wallets are recorded separately, so you can tell what is in transit from what has settled.
Architecture
The ledger changes only through execution.
Ledger entries are produced by governed financial execution, not by arbitrary writes from product code. That is what makes a balance explainable: each entry points back to the operation that produced it, and that operation has its own Proof of Record.
Postings balance
An entry that does not balance is rejected. Value is never created or lost inside the ledger.
Balances are derived
Available and reserved amounts are computed from entries, not maintained as a separate number.
Idempotent effects
A duplicate request or repeated provider notification maps to the same operation, not a second entry.
What the ledger does not do: it does not hold funds. Orangepill records financial positions and ledger state. Funds themselves remain with the banks, providers, custodians, or other licensed institutions used by the program. Comparing the ledger with what those external systems report is the job of verification and Resolve.
Examples
Four balance flows.
Wallet funding
The balance increases when the deposit is confirmed, not when the customer clicks pay.
- Pay-in initiated External provider
- Pending Recorded, not yet available
- Provider confirms Settlement evidence
- Ledger entry Funds become available
Wallet balance applied to a payment
The applied amount moves from available to reserved, so it cannot be spent twice while the payment is in flight.
- Balance applied To a checkout
- Reserve Available → reserved
- Payment outcome Completed, failed or expired
- Consume or release Journal posted either way
Marketplace seller balance
A seller balance is the sum of what happened to their orders, and it can be itemised.
- Buyer payment Captured
- Split Seller share, platform fee
- Hold Until fulfilment or dispute window
- Seller balance Released to available
- Payout
Refunds and reversals
Nothing is deleted. The correction is its own event, linked to the original.
- Original capture Ledger entry A
- Refund requested
- Refund executed Provider attempt
- Ledger entry B References entry A
Adoption
An operational ledger, not your accounting system.
Most teams already run a general ledger for accounting. The runtime ledger is not a replacement for it. It records the operational financial state your product acts on as operations execute. How the two connect is worked out during technical evaluation.
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.
Bring one balance you cannot fully explain today.
We will trace the events behind it and show how the ledger would record them.