Glossary
Key terms used throughout this documentation.
| Term | Definition |
|---|
| Tenant | Your PSP company. Logical isolation unit with its own configuration, branding, and merchant base. |
| Company | Legal entity within your tenant. Groups merchants under one legal umbrella. |
| Merchant | Business entity accepting payments from customers. Scoped to a company. |
| Terminal | Connection to a specific payment provider. Holds provider credentials securely in the vault. |
| Channel | Link between a merchant and a terminal. Defines which payment methods the merchant can use via that terminal. |
| Partner | Entity that brings merchants to the platform. Earns commission via PartnerAssignment. |
| Term | Definition |
|---|
| Payin | Incoming payment — a customer pays a merchant. |
| Payout | Merchant sends money to a third-party recipient (salary, winnings, etc.). This is a service product the merchant buys from the PSP. |
| Withdrawal | Request by an earning entity (merchant, tenant, or partner) to withdraw available balance to their own bank account. Merchant/partner withdrawals require operator approval. Tenant withdrawals are self-approved. Executed from tenant's FundingAccount. This is NOT a service product. |
| Settlement | Financial statement document summarizing transactions, fees, and net amounts for a period. States: draft, finalized. Does NOT trigger withdrawals. Settlement is NOT the T+N availability transition -- see Availability Transition. |
| Availability Transition | Automated T+N process: daily cron transitions funds from pending to available balance after N business days. This is separate from Settlement (which is a financial statement). |
| Refund | Return of funds to the customer, full or partial. |
| Dispute | Post-facto challenge to a transaction (chargeback). |
| Term | Definition |
|---|
| MoneyAmount | Canonical monetary value: { currency, valueMinor }. All amounts are in integer minor units (e.g., cents for USD, yen for JPY). No floating point. |
| Ledger | Immutable, double-entry system for tracking all money movement and positions. The single source of truth for balances. |
| Ledger Entry | Immutable record of a balance change. Always in debit/credit pairs. Sum of debits always equals sum of credits per operation. |
| Balance buckets | Balance is partitioned into six buckets: available (withdrawable now), pending (confirmed but awaiting T+N), reserved (held by policy such as rolling reserve or dispute hold), payable (reserved for approved withdrawal awaiting execution), collateral (guarantee deposits), operational (provider-side funds tracking). Merchant-visible: available, pending, reserved, payable. Internal only: collateral, operational. |
| T+N | Availability transition timing model. Funds become available N business days after the event (e.g., T+1 means available next business day). |
| Rolling Reserve | Temporary withholding of a percentage of merchant funds for risk coverage. Not a fee -- funds are released after the reserve period expires. |
| FeeSchedule | Named fee configuration template with rules. Can be assigned at multiple entity levels (tenant, company, merchant). |
| Fee decomposition | merchantFee = providerFee + platformFee + tenantFee + partnerCommission. The tenant fee is the residual after all other fees are subtracted. |
| FundingAccount | Tenant's real external account (bank account, crypto wallet) where money physically resides. Each has a corresponding ledger account tracking its balance. |
| Adjustment | Corrective ledger operation with mandatory reason and audit trail. Used to fix errors or make manual balance corrections. |
| Netting | Offset of incoming vs outgoing flows in settlement calculation. |
| Livemode | Production mode with real money. |
| Testmode | Sandbox mode for testing without real money. |
| Term | Definition |
|---|
| Transaction | Business-level operation container with a single final outcome. Holds one or more attempts. |
| TransactionAttempt | Technical execution attempt through a specific channel/terminal. A transaction may have multiple attempts (e.g., after cascading). |
| PaymentStatus | Canonical payment status: processing, requires_action, requires_capture, captured, succeeded, failed, canceled, refunded, partially_refunded. |
| Routing | Rule-based selection of terminal/channel for a transaction. |
| Cascading | Automatic retry through alternative channels on soft decline. |
| CheckoutSession | Payer-facing payment session created for HPP/widget flows. |
| Idempotency key | Client-provided key to prevent duplicate payment creation. Required on POST/PATCH/DELETE requests. |
| 3DS | 3-D Secure -- payer authentication protocol. Decision point in the payment pipeline. |
| Term | Definition |
|---|
| RBAC | Role-Based Access Control. Permissions formatted as domain:resource:action. |
| API Key | Machine-to-machine authentication. Three tiers: sk_ (server, full API), pk_ (client, tokenization only), clientSecret (session-scoped). |
| User layer | Interface context determining UI and permissions: merchant, operator, owner, partner. Immutable per user. |
| Impersonation | Operator/owner "sign-in as merchant" with full audit trail. |
| Term | Definition |
|---|
| Reconciliation | Automated matching of platform transaction records against provider records. Two-level verification: summary check (count + amount), then detail matching (per-transaction). Runs per terminal. |
| Audit event | Canonical log entry for all significant actions (financial, config, UI, API, system). Immutable -- insert only. |
| Webhook | Asynchronous HTTP notification to merchant endpoint on status changes. At-least-once delivery. |
| HPP | Hosted Payment Page -- payer-facing UI for payment collection. |
Payout vs. Withdrawal
A payout is when a merchant sends money to a third party -- this is a service the merchant uses. A withdrawal is when an entity (merchant, tenant, or partner) takes their own earned money out to their bank account. Merchant/partner withdrawals require operator approval; tenant withdrawals are self-approved.
Settlement vs. Availability Transition
Settlement is a financial statement document summarizing transactions, fees, and net amounts for a period. It does NOT move money or change balances. Availability Transition is the separate automated T+N process that moves funds from pending to available. These are two distinct operations.
Settlement vs. Payout
Settlement generates financial statements -- it does NOT automatically send money anywhere. To actually move funds out, a separate withdrawal or payout must be initiated.