Concepts

Ledgers and balances

A ledger groups balances for your application's accounting model. A balance has a currency and may be linked to an identity. A transaction moves value from a source balance to a destination balance; split transactions use several sources or destinations. Model the external funding or settlement counterpart as a balance too, so value entering a wallet still has a debit and a credit.

balance = credit_balance - debit_balanceinflight_balance = inflight_credit_balance - inflight_debit_balance

A transfer increases the source's debit counter and the destination's credit counter by the same integer amount. Across a closed system, total credits equal total debits. Spendable funds normally subtract inflight debit reservations from the committed balance. Overdrafts must be explicit: allow_overdraft: true with no positive overdraft_limit permits an unbounded overdraft, so set a limit when your model needs one.

Precision and rounding

precision is a multiplier, not a count of decimal places. With precision 100, precise_amount: 1250 means 12.50. Use one multiplier per currency throughout your integration and send it with every transaction; an omitted precision defaults to 1 when no stored precision is available.

• precise_amountis a JSON integer. Don't quote it as a string. Clients must preserve large integers rather than decoding them through floating point.
• The compatibility field amount accepts a JSON number. Its decimal token is converted exactly, then rounded to the nearest unit with ties away from zero: 1.005at precision 100 is 101 units. Don't send both fields with a nonzero amount.
• Positive amounts that round to zero units are rejected, and so are precision or overdraft tokens that can't be decoded without changing their value.
• rate and currency_multiplierdon't perform currency conversion. Handle FX explicitly in your application.

Transactions and references

Submit transfers to POST /transactions with a source, destination, currency, amount and a unique reference. Keep the reference stable for one business operation. Duplicates are rejected with TXN_DUPLICATE_REFERENCE; after a timeout, use GET /transactions/reference/:reference to recover the original outcome instead of retrying with a new reference.

By default, workers process accepted transactions asynchronously. With skip_queue: true the request waits for execution. A response acknowledging a queued request is not evidence of settlement: read the status.

Bulk APIs offer explicit atomic and asynchronous options; check the reported outcomes rather than assuming every batch is atomic. Postings and accepted execution controls are immutable. Customer metadata can change, but reserved execution, lineage, policy and recovery keys can't be changed through the metadata API.

Inflight holds

Set inflight: true to reserve funds without a committed transfer. Update the hold with PUT /transactions/inflight/:txID and status: "commit" or status: "void". Commits may be partial; voiding releases what remains. Optional expiry and commit dates are handled by workers, so keep them running.

Refunds and previews

POST /refund-transaction/:idcreates a linked reversal with source and destination exchanged and the original's exact amount. Only APPLIED transactions are refundable, and a durable claim prevents concurrent retries from producing several reversals. Refunds queue by default; send skip_queue: true to wait.

Transaction, refund and inflight requests accept dry_run: true. A preview projects balance effects without persisting a posting, consuming the reference or sending a webhook. It observes current state; it is not a reservation or a promise that a later request will succeed.