Start here
Core concepts and lifecycle states
External teams integrate more reliably when they treat PayChainHQ objects as state machines instead of one-off HTTP responses.
Key objects
Business
Your tenant. It owns API keys, webhook settings, balances, invoices, withdrawals, and approval state.
Customer
Optional reusable identity that keeps invoices grouped by a stable external reference and reusable deposit addresses.
Invoice
A payable request with token, chain, network, amount, expiry, deposit address, and settlement lifecycle.
Withdrawal
An asynchronous treasury payout request with quote, fees, retries, sweep orchestration, and completion status.
Webhook event
A signed delivery envelope used for realtime notification of invoice, withdrawal, and billing lifecycle changes.
Balance
A treasury-facing projection of what is currently available, reserved, or still dependent on sweeps and confirmations.
Invoice states
Always model invoice handling as stateful.
| State | Meaning | Your likely action |
|---|---|---|
| `pending` | Invoice exists but no confirmed payment yet. | Show address, amount, expiry, and countdown. |
| `confirming` | Matching payment detected but required confirmations are not complete. | Keep the order pending but display visible progress. |
| `paid` | Invoice settled exactly or within configured underpayment tolerance. | Release the product / service and record the settled amount. |
| `partially_paid` | Payment arrived but is still short of the required amount and outside tolerance. | Wait for top-up until expiry or route to manual support. |
| `overpaid` | More than the expected asset amount arrived. | Fulfill the invoice, then follow your overpayment support workflow. |
| `expired` / `expired (partial)` | Invoice lifetime ended before full settlement. | Stop treating it as open and decide whether to refund, keep, or manually resolve residual payment. |
Withdrawal states
| State | Meaning | What to do |
|---|---|---|
| `pending` | Accepted and queued for processing. | Keep the payout visible to operators. |
| `sweeping` | Funds are being consolidated before payout. | Do not create duplicate payouts for the same customer obligation. |
| `processing` | Broadcast or final settlement work is in progress. | Wait for terminal state or retry metadata. |
| `retrying` | A transient condition delayed completion. | Inspect `nextRetryAt` and keep the payout non-terminal. |
| `completed` | The payout is done and should include a tx hash. | Mark your internal payout request complete. |
| `failed` / `cancelled` | The payout stopped permanently or was operator-cancelled. | Route to support or operator re-decision. |