insimbi
Docs · Concepts
Core concepts
Transaction, rails, record. Access, rules, mandates.
- 01 · transaction
Who pays whom, for what, under which mandate.
- 02 · rails
The network, bank rail, chain or venue that carries it.
- 03 · record
A ledger entry with fee lines, the rule and its reconciliation.
A payment, end to end
Authenticate, check the rules and the agent's mandate, ask a person above your threshold, let the rail rule choose the rail, then write the ledger entry, fee lines and ticket. The sequence diagram is with the endpoint, on the API reference (/docs/api/#flow-payment).
Access and the audit record
Every API call carries a short-lived token, and every protected read is checked against the grants for its organization. The decision, allowed or denied, gets a decision ID and is written to the audit record before the response is released. If the decision can't be recorded, the response isn't sent.
| Access decisions | authorization.allowed, authorization.denied, authentication.failed |
|---|---|
| Tokens and rejections | token.issued, security.rejected, security.unavailable, security.capacity_rejected |
| Clients | principal.created, principal.suspended |
| Credentials | credential.issued, credential.rotated, credential.compromised, credential.revoked |
| Roles and grants | role.created, grant.created, grant.revoked |
| Approvals | approval.proposed, approval.approved |
Widening access is a change that is proposed and then approved by a person. The approval is bound to that exact change and can't be reused for another.
Rules
A rule chooses the rail. Rules are versioned code. You can diff, test in the sandbox and roll back any rule in one step.
Tickets and the decision trace
Every payment has a ticket: its fee lines, each cited to a rule in the rules register, plus references to the decisions and events behind it. Ask why a payment took its rail, was priced or was declined and you get the answer line by line, with citations.
Mandates and perimeters
A mandate is the set of bounds an operator approves for an agent: scopes, caps, recipients and finality rules. In the designed API it is a perimeter, versioned and expiring. Every request is checked against it before anything reaches a network. Outside it, the request is denied and the denial is recorded. The access layer already works this way: grants decide what each client may do, every denial is recorded, and widening a grant needs an approved change.
Agent of record
Every agent-initiated payment carries an agent of record: the verified legal entity that answers for it. Agents authenticate as registered clients with their own signing keys, never with a shared secret.
Accounts
Organizations hold legal entities. Legal entities hold merchant accounts. Each has its own read permission (organization.read, legal_entity.read, merchant_account.read), and credentials and grants are scoped along that hierarchy.
The record
One double-entry ledger for fiat, stablecoins, market funding, token cash legs and agent payments. Fee lines are entries, not footnotes.
Idempotency and versions
Designed payment writes take an Idempotency-Key header. Money amounts are decimal strings with an explicit currency. Objects carry the rule and perimeter versions that produced them.