Money & accounts

The Capxul surface is Stripe-shaped: money is just money. You will never pass a raw token amount, an address, or a chain identifier to move it. This page is the vocabulary that replaces those things — every hook and client method speaks it, so it is worth learning precisely.

Money

Money is a consumer-facing amount: a currency, a decimal value, and a precision.

{ currency: "USD", value: "25.00", decimals: 2 }

It is the only monetary value any caller sees — never wei, never a raw token integer. The precision travels with the value so amounts round-trip exactly.

Account

An Account is a person's or organization's logical pot of money, identified by an opaque account_-shaped id — not an address. An Account has a balance and an available balance. Every Capxul user has a personal Account; every organization has a treasury Account.

Transfer vs. Payment

The first distinction the domain draws is whether money leaves the Account.

• A Transfer moves money within a single Account — between the main balance and a named envelope (sub-account), or between envelopes. A Transfer never reaches an external party. A Transfer is not a Payment.
• A Payment sends money from an Account to an external recipient — someone outside your own Account. "Payment" is the domain noun; "pay" is the verb.

The kinds of Payment

Payment is the genus. Its two species differ only in who authorizes the outflow:

• A direct payment is paid from a personal Account; the person authorizes it themselves.
• An org payment is paid from an organization's Account, authorized under the payer's role and its spending limits.

Two familiar product shapes are kinds of Payment, not separate mechanisms:

• Payroll — paying many people at once from an organization (salaries).
• A batch payment — one Payment instruction that pays several recipients together as a single settled act.

This is a deliberately small taxonomy. New product surfaces do not get new money-movement primitives; they compose Payments.

Time-based payments are Commitments

Two more Payment shapes release money by the clock instead of instantly:

• A scheduled payment releases in full at a chosen future time — nothing before, everything after.
• A stream releases continuously over a window (a salary over a month), optionally with a cliff — a point before which nothing has released.

Both are backed by the same object: a Commitment. When a Commitment is created, the payer's money is escrowed in the settlement layer. It then vests by the clock (Capxul uses straight-line release between start and end; a scheduled payment is simply a Commitment whose cliff and end are the same instant). The recipient takes possession by claiming the vested funds.

The payer keeps two safety valves until the money is claimed:

• Cancel — reclaim the unvested remainder. Vested-but-unclaimed money stays the recipient's.
• Redirect — point the not-yet-claimed Payment at a different recipient (paid the wrong person, or the original never claimed) without cancelling and re-creating it.

Recoverability is the trade-off that makes Commitments central: escrow costs the payer liquidity up front, but it means a time-based or not-yet-claimable payment is never irreversibly gone.

Payment documents

A payment document is the human-meaningful record of why a Payment happened — one of four kinds: invoice, payslip, receipt, or memo (free-text, the minimal document). The full document lives off the settlement layer; the Payment itself carries only a tamper-proof fingerprint of it (the document hash), so the reason for a payment stays verifiable long after the fact.

Recipients, validation, and the instant-send guardrail

A recipient is always a typed reference — a Capxul user (by id or email), an organization, an email that is not yet a Capxul user, or a saved Payee — never a raw address in the caller's hands.

A recipient is validated once they have activated their own Capxul account, so money sent to them lands somewhere they already control. That distinction drives the single most important settlement rule:

An instant, irreversible Payment is only permitted to a validated recipient. Paying anyone not yet validated always goes through a recoverable Commitment.

The SDK enforces this — a bare irreversible send to an unvalidated recipient is never offered. If a payment you expected to be instant comes back as escrowed, this guardrail is why; it is not a bug to work around.

Claimable payments

The guardrail's most visible product shape is the claimable payment (payment link): a Payment to someone who is not yet a validated Capxul user, named by email. It is simply a Commitment addressed to the account reserved for that email — the account the recipient takes control of once they activate. The money escrows now; the recipient validates and claims. "You've got money on Capxul" is a real escrowed Commitment, not a notification about a promise — and if the recipient never shows up, the payer cancels or redirects it. There is no separate held-money machinery.

Where the model meets today's alpha

The vocabulary above is the platform's domain model; not every corner of it has a fully proven product surface in the published alpha. Payments to typed recipients are live with the constraints listed on Capability status; payroll, requests, and sub-account primitives are published but at varying grades. When this page and that one disagree about what you can ship today, that one wins.

The bigger picture

Notice what the whole vocabulary refuses to mention: addresses, tokens, chains. Accounts are opaque ids; recipients are typed references; amounts are decimal Money. If you find yourself needing a raw address or a token integer to express something, you have left the intended surface — go back and find the domain word for what you actually mean. Who holds these Accounts and who may move money from them is the subject of Identity & organizations.