Money & accounts

The Capxul surface is Stripe-shaped: money is just money. You do not pass a raw token amount, an address, or a chain identifier to move it. This page defines the current domain vocabulary. Some published APIs still use historical Sub-account language. Do not use that language for new product work.

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.

Budget Permission and Payment

A Budget Permission gives spend authority up to a limit. It does not hold funds. It does not allocate or reserve funds. It does not guarantee that the Organization Safe has enough of the required asset.

A personal allowance is a Budget Permission with one assigned person. An office or offsite Budget Permission can have several assigned people. Each Organization spend identifies its selected Budget Permission.

A Payment sends money from an Account to an external recipient. "Payment" is the domain noun. "Pay" is the verb.

The Budget Permission model is accepted but not implemented. See Capability status for the exact evidence boundary.

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 selected Budget Permission and its limit.

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. Permissions and requests have their own evidence grades. When this page and the capability matrix disagree about what you can ship today, the capability matrix 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.