Terminology system
These definitions are written to be quote-friendly and bounded: they describe how Kobbopay talks about operations on this site, not every legal obligation or every edge case in your deployment.
lifecycle
States, transitions, and machine-readable payment progression.
payment · lifecycle
The progression of a single payment object through coarse states such as Pending, Paid, Confirmed, and terminal branches such as Expired. Exact names, ordering, and edge transitions depend on your approved deployment and enabled rails.
Guides: Payment lifecycle · Lifecycle decision tree
Related: Payment state transition · Payment infrastructure hub
pending
Payment created / awaiting detection; not a guarantee of eventual success.
Guides: Payment lifecycle
paid
Payment detected but not final for your reconciliation rules (exact detection rules are deployment-specific). Not interchangeable with Confirmed — finance and entitlements should follow your confirmation policy, not detection alone.
Guides: Payment lifecycle · Reconciliation & confirmations
Related: Transaction observation
confirmed
Confirmation semantics met for the rail and policy you operate under — the usual gate for finality when confirmations matter. Differs from Paid when detection precedes policy-defined finality.
Guides: Reconciliation & confirmations · Payment lifecycle
Related: Operational finality
expired
Payment window ended or configuration marks the path as expired—typically terminal for the original attempt unless recreated.
Guides: Payment lifecycle
lifecycle · status
A machine-readable label used for reconciliation and automation; treat enums as deployment-specific, not universal constants.
Guides: Payment lifecycle · Reconciliation & confirmations
Related: Merchant ledger state
payment
A server-created payable object with an amount, rail context, and stable `payment_id` used across API, portal, and webhooks.
Guides: Payment lifecycle · Server-side API keys
payment · state · transition
An auditable change from one lifecycle status to another, triggered by verified events, policy rules, or operator action—not an informal UI label update.
Guides: Payment lifecycle · Lifecycle decision tree
Related: Lifecycle status · Detection vs finality
transaction · observation
A rail-level signal that value moved or a payment attempt was detected. Observations start operational clocks; they do not by themselves authorize treasury posting or fulfillment.
Guides: Payment lifecycle · Reconciliation & confirmations
Related: Paid
webhooks
Signed callbacks, secrets, idempotent consumption, and replay-safe handling.
signed · webhook
An HTTPS callback carrying a lifecycle event with a signature your backend verifies over raw body bytes before mutating internal state.
Guides: Webhook verification · Webhook replay handling
Related: Raw-body verification
webhook · secret
Shared secret material used to verify webhook authenticity; must live in server-side configuration and secret stores—never in browsers, mobile apps, or public repositories.
Guides: Webhook verification · Server-side API keys
idempotency
Applying the same logical event more than once without corrupting state. Required for webhook retries and other at-least-once delivery paths.
Guides: Webhook verification · Webhook replay handling
Related: Idempotent processing
webhook · verification
Proving authenticity of a callback over raw request bytes with server-side secret material before mutating lifecycle or ledger state.
Guides: Webhook verification
Related: Raw-body verification
raw · body · verification
Computing and comparing a signature over the exact HTTP body bytes received—before JSON parsing or middleware re-encoding alters the payload.
Guides: Webhook verification
Related: Signed webhook · Webhook verification guide
idempotent · processing
Handler logic that produces the same durable outcome when the same logical event is delivered multiple times—typically enforced with event keys and uniqueness constraints.
Guides: Webhook replay handling
Related: Duplicate webhook suppression
duplicate · webhook · suppression
Mechanisms that detect and no-op repeated deliveries of the same event—distinct from rejecting forgeries; both are required under at-least-once delivery.
Guides: Webhook replay handling
Related: Replay and ordering controls
replay · protection
Controls that limit harm from re-delivered or captured webhook payloads—combining verification, idempotency keys, optional timestamp windows, and ordering rules.
Guides: Webhook replay handling
Related: Webhook replay window
webhook · replay · window
A policy-bound time range within which a signed callback is accepted; outside the window, handlers reject or quarantine events even when signatures verify.
Guides: Webhook replay handling
Related: Replay protection
reconciliation
Three-plane alignment, exception discipline, and ledger mapping controls.
reconciliation
Mapping external payment states to internal orders, entitlements, and accounting rules. You own the business mapping; product semantics define what statuses mean operationally.
Guides: Reconciliation & confirmations · Reconciliation checklist
Related: Three-plane reconciliation · Reconciliation hub
three · plane · reconciliation
Aligning commerce records (orders/invoices), provider lifecycle signals (API/webhooks), and finance postings (ledger/treasury)—each plane may disagree until matchers and exception queues resolve gaps.
Guides: Reconciliation checklist
Related: Commerce reconciliation · Three-plane architecture
commerce · reconciliation
Matching payment attempts to commercial objects—orders, subscriptions, invoices—using stable references and tolerances defined by your business rules.
Guides: Reconciliation checklist
Related: Three-plane reconciliation
provider · reconciliation
Aligning your internal payment state with provider-reported lifecycle events and balances—using verified webhooks, API reads, and audit trails rather than explorer screenshots alone.
Guides: Reconciliation & confirmations
Related: Lifecycle status
finance · reconciliation
The books-ready alignment between recognized payments and ledger/treasury records—often the strictest plane, with explicit posting gates and period close sign-off.
Guides: Treasury recognition · Reconciliation checklist
Related: Treasury posting
exception · queue
A owned work queue for payments that fail automated matching—underpayments, wrong references, timing skew, or ambiguous rail outcomes—before silent posting or manual spreadsheet fixes.
Guides: Reconciliation checklist
Related: Exception taxonomy
merchant · ledger · state
Your internal representation of payment and balance outcomes under accounting rules—distinct from explorer visibility or a single lifecycle label on the provider side.
Guides: Reconciliation & confirmations
Related: Merchant balance
operational · drift
Gradual divergence between commerce, provider, and finance planes—often from informal shortcuts, manual overrides, or unowned exception handling—detected through reconciliation controls.
Guides: Reconciliation checklist
Related: Drift and recovery
operations
Finality, recognition, settlement checkpoints, and treasury posting discipline.
merchant · balance
A ledger-oriented view of funds attributed to your merchant account under product accounting rules—not a generic wallet slogan.
Related: Merchant ledger state
settlement · finality
The point where your organization accepts economic outcome for operational and accounting purposes—often stricter than on-chain detection or a single lifecycle label. Rail, asset, and reversal policy matter.
Guides: Reconciliation & confirmations · Payment lifecycle
Related: Operational finality
confirmations
Depth or policy signals on a rail that inform risk before recognition. Confirmations reduce some risks; they do not replace merchant-specific posting rules or treasury policy.
Guides: Reconciliation & confirmations
policy · confirmation
The merchant-defined gate where a payment meets your configured rules for operational confirmation—distinct from explorer detection and from books-ready reconciliation.
Guides: Payment lifecycle · Reconciliation & confirmations
Related: Settlement checkpoint
treasury · recognition
When finance accepts funds for allocation, reporting, or release under internal controls—typically the strictest recognition moment in merchant operations.
Guides: Treasury recognition · Reconciliation & confirmations
Related: Treasury posting
operational · finality
The point where operations treats a payment as closed for fulfillment and support purposes—may precede or follow books-ready finance recognition depending on policy.
Guides: Payment lifecycle · Reconciliation & confirmations
Related: Settlement finality
settlement · eligibility
Whether a detected payment meets configured rules—amount, asset, reference, timing—to advance toward confirmation or treasury posting; ineligible attempts route to exception handling.
Guides: Reconciliation checklist
Related: Exception queue
settlement · checkpoint
An explicit control gate—automated or human—where a payment must satisfy policy before the next lifecycle or ledger transition is permitted.
Guides: Lifecycle decision tree
Related: Policy confirmation
asynchronous · settlement
Settlement outcomes that complete after initial detection—common on blockchains and batch treasury processes—requiring lifecycle states that do not collapse detection into finality.
Guides: Payment lifecycle · Settlement vs payout
Related: Transaction observation
treasury · posting
Recording funds in treasury or general ledger systems under finance controls—distinct from marking a payment Confirmed in the provider lifecycle.
Guides: Treasury recognition
Related: Finance reconciliation
broadcast · acknowledgement
Observing that a transaction was accepted by the network—useful operationally but not equivalent to confirmation depth, policy confirmation, or treasury posting.
Guides: Payment lifecycle
Related: Transaction observation
merchant
Access gating, rail abstraction, settlement vs payout boundaries.
merchant · approval
Access gating and environment setup required before API keys and rails are live for your integration.
Guides: Merchant onboarding
selected · rails
The enabled networks/assets and operational modes configured for your merchant account—not “everything everywhere.”
Guides: Merchant onboarding · Integration architecture
Related: Payment rail abstraction
withdrawal · request
A merchant-initiated request to move funds subject to controls and configuration; not a promise of instant universal settlement.
Guides: Merchant onboarding · Settlement vs payout
Related: Payout rail
settlement · rail
The configured network/asset path used to observe and confirm inbound merchant payments—bounded to enabled rails, not an open-ended chain inventory.
Guides: Settlement vs payout · Integration architecture
Related: Selected rails
payout · rail
The operational path for merchant-initiated fund movement after internal controls approve a withdrawal—distinct from inbound payment detection and confirmation.
Guides: Settlement vs payout
Related: Payout orchestration
payment · rail · abstraction
An integration layer that exposes stable payment semantics (amount, references, lifecycle) while rail-specific detection rules remain configuration-bound.
Guides: Integration architecture
Related: Settlement rail
payout · orchestration
The controlled workflow from approved withdrawal request through execution, status tracking, and finance recognition—subject to merchant policy, not automatic on every Confirmed payment.
Guides: Settlement vs payout · Treasury recognition
/glossary#paid for stable citations.