Ledger clarity
Merchant ledger system for crypto payment operations
A merchant ledger system in crypto payment infrastructure is the operational record finance and support can audit: how balances move, how lifecycle events post, and how exceptions resolve. Kobbopay emphasizes explicit transitions—not opaque aggregate balances.
Technical alignment: Discuss integration · Explore operational model
01
Operational overview
Ledgers answer what changed, when, and under which policy—not only what the UI shows merchants today.
Lifecycle events from verified webhooks and API reads should map to ledger transitions your finance team can explain during audits.
Payout state, holds, and releases must be vocabulary finance signs off on before production traffic scales.
02
Integration concepts
Engineering should treat ledger writes as policy-governed side effects—often downstream of idempotent webhook processing.
Stable external references on payment creation simplify joins between commerce, provider events, and ledger lines.
Separate read models for support tooling from authoritative posting paths to reduce accidental mutations.
03
Per-rail ledger considerations
Fees, confirmations, and internal sweeps affect ledger lines differently per rail.
Wrong-asset deposits should create exception ledger states—not silent adjustments.
Use merchant ledger transitions reference when designing internal enums.
04
Reconciliation and auditability
Reconciliation matchers compare commerce, provider, and finance planes—ledger is often the finance plane output.
Audit trails should include operator decisions on exceptions with payment_id context.
See payment reconciliation system page for three-plane framing and exception queues.
05
Control-plane integrity
Ledger corruption often starts at unverified webhooks. Verify raw bytes before any posting logic runs.
Idempotency prevents duplicate ledger lines during webhook retries.
Webhook signature verification page documents public patterns; signing contracts are environment-specific after approval.
- Retries are normal. Webhook delivery is at-least-once. Design consumers to tolerate duplicates and out-of-order arrivals where possible.
- Asynchronous by design. Payers, chains, and your servers operate on different clocks. UI and finance should not assume synchronous finality.
- Eventual consistency. API reads, webhooks, and portal views may briefly diverge during transitions. Reconciliation jobs exist to converge truth.
Walkthroughs: /operations
- Reviewed merchant onboarding
- Server-side API keys only
- Signed webhook verification on raw bytes
- Explicit lifecycle states
- Operational reconciliation model
- No client-side secrets
If this model matches your B2B program, align engineering and treasury on lifecycle semantics, complete reviewed merchant onboarding preparation, run webhook verification tests in the first environment you receive, then submit a structured access request with required rails and use case context.
Frequently asked questions
- Does Kobbopay replace our general ledger?
- No. Kobbopay provides payment infrastructure semantics. Your accounting system of record remains yours.
- Should support staff edit ledger rows directly?
- Edits should follow policy with audit trails—avoid ad hoc production database changes without finance approval.
- How do payouts appear on the ledger?
- As policy-governed outbound transitions—see settlement vs payout guide and payout infrastructure page.
- What evidence should period close retain?
- Lifecycle history, exception resolutions, and webhook delivery context—not explorer screenshots alone.