Core Concepts And Terminology
Use these terms when reading the API, SDK, dashboard, and webhook docs.| Term | Meaning | Why it matters |
|---|---|---|
| Business | A PayChain tenant that owns API keys, invoices, balances, webhooks, and billing. | Most API calls are scoped to one business. |
| Customer | A reusable payer identity. | Helps group invoices and recurring payment addresses. |
| Invoice | A payment request with amount, token, chain, network, deposit address, and status. | Invoice state is the source of truth for customer payment fulfillment. |
| Deposit address | The address a payer sends funds to. | Some addresses are invoice-specific; some are reusable customer addresses. |
| Payment | A detected on-chain transfer related to an invoice or customer address. | Only qualifying payments should affect revenue or fulfillment. |
| Settlement | The confirmed state after required chain confirmations and asset matching. | Use settled invoice state before releasing value. |
| Payout route | An approved template for splitting an invoice after it is fully paid. | Use for repeat split patterns. |
| Dynamic payout recipient | One-time payout recipient supplied when creating an invoice. | Useful for on-ramp, off-ramp, marketplace, or order-specific receivers. |
| Withdrawal | A treasury movement from PayChain-controlled business funds to a destination. | Programmatic withdrawals require payout API keys. |
| Webhook | A signed event delivered to a merchant backend. | Verify every webhook with the raw body before acting. |
| Balance | A treasury-facing view of available or reserved funds. | Use balances for operations; use invoice state for payment truth. |
| Transaction | A chain or platform movement used for reconciliation. | Helps explain what happened, but may not equal invoice truth by itself. |
| Standard API key | Backend API key for reads, customers, invoices, webhooks, balances, transactions, networks, and tokens. | It cannot move funds. |
| Payout API key | Backend API key for constrained payout automation. | It can move funds only within policy. |
| Sandbox | Test environment. | Do not mix sandbox credentials with live credentials. |
| Live mode | Production environment. | Requires separate approval and production secret handling. |
| Chain / network / token | Asset routing fields, such as EVM, Base, USDC. | Invoice and payout route assets must match exactly. |
| Gas credits | USD-denominated allowance or prepaid balance used for sponsored outbound operations. | Gas exhaustion pauses eligible sponsored outbound actions, not receiving. |
| Gas-blocked operation | A sponsored outbound operation paused because gas credits are insufficient. | Top-up resumes queued operations oldest-first. |
Accounting note: Invoice state and signed webhook events are the payment source of truth. Balances and transactions are reconciliation surfaces, not customer fulfillment proof by themselves.