OverviewAuthentication & environmentsStaging faucetCore conceptsReceive paymentsAuto-detect paymentsConfirm settlementWithdraw fundsContract interactionsReconcile balancesBusiness identitySettings & complianceCustomers & invoicesWithdrawals & treasuryContracts & automationReference data & billingWebhooks & eventsUse-case playbooksErrors & edge casesGo-live guideChangelog
Playbooks
Use-case playbooks
Concrete operating models for common integration patterns so your team knows which endpoints and cautions apply in practice.
Onramp
Accept a customer deposit and treat PayChainHQ as the crypto payment and confirmation layer.
- Create a customer if you want a reusable identity.
- Create the invoice with the token and network your customer is expected to pay.
- Render the public invoice payload or share the hosted link.
- Wait for `invoice.paid` webhook, then mark the fiat leg or internal ledger leg ready.
- Use balances and transactions endpoints for treasury reconciliation.
Offramp
Move funds out only after treasury and sweep feasibility are proven.
- Quote the withdrawal first and show the operator the recommended option.
- Create the withdrawal with `clientReference` mapped to your payout job.
- Poll or subscribe until the payout reaches a terminal state.
- Persist requested amount, payout amount, fee amount, and tx hash separately.
Recurring collection
When the same user pays multiple times, reuse customer identities and keep invoice-level settlement exact.
- Create one customer with your stable `externalRef`.
- Issue one invoice per receivable event when you need an explicit request up front.
- For permanent customer-address collection, let PayChainHQ auto-generate invoice records from detected receipts instead of pre-creating every repeat invoice.
- Use underpayment tolerance only when small quote drift is an accepted business rule.
- Do not infer future receivables from the customer address alone; invoices still remain the accounting primitive.