Core Concepts
Understand the public treasury, reconciliation, fraud, compliance, and tax resources and the ledger underneath them.
Participants
A participant is the treasury identity for a person or business on your platform. Participants receive balances, can accrue holds, and can be paid out.
- They map to ledger-backed accounts.
- They carry payout preferences and split defaults.
- They are the anchor resource for wallets, holds, and payouts.
Wallets and Holds
Wallet balances show what a participant has accrued. Holds represent funds that exist in the ledger but are not yet releasable.
| State | Meaning |
|---|---|
wallet.balance | Current ledger-backed balance attributed to the participant |
hold | Funds withheld until release conditions are satisfied |
available_balance | Wallet balance minus active held amounts |
Checkout and Payout Lifecycle
The public resource lifecycle is explicit rather than hidden inside command handlers.
participant -> checkout_session -> wallet balance -> hold (optional) -> payout -> refund -> reconciliation -> fraud evaluation -> compliance review -> tax summary / document
Operational Resources
Soledgic also exposes ledger-scoped operational resources once money starts moving.
reconciliations/*tracks unmatched transactions, matches, and frozen snapshots.fraud/*evaluates proposed transactions and manages policy rules.compliance/*summarizes ledger-scoped access, security, and financial monitoring signals.tax/*exposes calculations, summaries, generated documents, and exports.
Shared Identity and Ecosystems
Soledgic also has a higher-level operator model for shared user identity and multi-platform ecosystems. That layer sits above the public treasury resources.
- Identity is global to the signed-in user.
- Participants and wallets remain ledger-scoped.
- Ecosystems group related platforms for visibility, not pooled balances.
- These routes are dashboard-only and are not part of the public `/v1` API contract.
Double-Entry Ledger
Soledgic uses double-entry accounting underneath the resource API. Every state-changing write resolves to balanced debits and credits.
Example: a $29.99 checkout with an 80/20 split
| Account | Debit | Credit |
|---|---|---|
| Cash | $29.99 | - |
| Platform Revenue | - | $6.00 |
| Participant Balance | - | $23.99 |
The ledger is the source of truth. Resources are the developer-facing model layered on top of it.
Architecture
The system is intentionally layered so developer ergonomics and financial correctness can evolve independently.
Resource Layer
Public endpoints expose participants, wallets, holds, transfers, checkout sessions, payouts, refunds, reconciliations, fraud evaluations, compliance monitoring, and tax operations.
Operator Control Plane
Shared identity, ecosystem management, and internal verification tooling live behind authenticated dashboard routes, not the public API-key surface.
Shared Services
Shared treasury services centralize validation, orchestration, and response shaping across the public surface.
Ledger RPCs
Money-moving writes commit through PostgreSQL RPCs with row locks and atomic transactions.
Replay Safety
Direct checkouts and refunds support explicit idempotency keys. Transfers and payouts are currently replay-safe by unique reference_id checks.
If an API worker fails mid-request, the ledger write either committed fully or rolled back. The gateway does not own the financial state machine.