Developer docs
PayChainHQ docs for payments and contract automation
Workflow-first documentation for external teams integrating PayChainHQ business APIs for invoices, contract interactions, on-chain settlement, treasury withdrawals, and reconciliation.
Start with the shortest successful path
Most external teams need the same sequence: open a sandbox business in the dashboard, provision an API key, create invoices for supported ERC-20 or SPL payments, optionally register contract surfaces for controlled reads and execution, confirm settlement with webhooks, then move treasury funds out safely.
1. Authenticate once
Create a sandbox business in the dashboard, then provision a business API key for server-side requests.
2. Create customers and invoices
Generate a deterministic deposit request with the right token, network, expiry, and tolerance settings.
3. Confirm by webhook first
Use signed webhook events for real-time updates and invoice reads as reconciliation fallback.
4. Quote and withdraw
Quote treasury availability first, then create withdrawals by dashboard step-up or a dedicated payout API key.
5. Register contract surfaces carefully
If your backend needs controlled contract reads or executions, register EVM ABIs or Solana Anchor IDLs first, then publish constrained actions.
6. Separate sandbox from live
Sandbox activation and live approval are different states. Treat them as separate operator workflows.
7. Store request IDs
Persist `requestId`, your own `clientReference`, webhook delivery IDs, and invoice / withdrawal IDs for support and auditability.
Recommended reading order
If you are onboarding a new engineering team, use this order.
Authentication & environments
Learn how API keys, public routes, sandbox, live, idempotency, and backend-only request patterns fit together.
Open page
Staging faucet
Seed Base Sepolia and Solana devnet wallets with public test assets before you rehearse invoice, settlement, and withdrawal flows.
Open page
Receive payments
Build invoice creation, customer mapping, hosted invoice links, and payer-side polling for supported-token payments.
Open page
Auto-detect payments
Use permanent customer addresses, auto-generated invoices, and webhooks when you do not want to pre-create every repeat payment.
Open page
Webhooks & events
Verify signatures, handle retries safely, and keep your system idempotent.
Open page
Withdraw funds
Understand requested amount vs payout amount, sweep behavior, and payout tracking.
Open page
Contract interactions
Register EVM contracts or Solana programs, publish constrained actions, and execute or query them safely from your backend.
Open page
Errors & edge cases
Handle tolerance-settled invoices, expiry, overpayment, replay, and `forceSweepAll` correctly.
Open page
Go-live guide
Checklist for production webhooks, secret management, environment promotion, and operator readiness.
Open page
Contract interactions are part of the supported surface
PayChainHQ does not stop at payment collection. You can also register chain-specific interfaces and expose a constrained automation surface to your backend.
EVM contracts
Register a contract address plus ABI, discover write and query operations, then publish only the actions you want your backend to execute.
Solana programs
Register a program ID plus Anchor IDL, query decoded accounts, simulate instructions, and publish single-business-signer actions with explicit account mappings.
Split responsibilities cleanly
Operators create integrations and publish actions in the dashboard. Your backend later queries, quotes, and executes the already-approved surface with API keys.
Machine-readable contract and written guidance serve different jobs
Use the docs pages for operational guidance, and the OpenAPI artifact for code generation or SDK scaffolding.
- The downloadable OpenAPI artifact is regenerated from backend Swagger annotations and filtered to the external business/public surface.
- The written docs remain richer than the contract: they include workflow ordering, reconciliation notes, environment warnings, and operational cautions.
- First-party dashboard/session routes are intentionally excluded from the external developer surface.
- If an endpoint appears on a reference page, it is part of the supported external docs inventory even if the machine-readable contract lags behind a newly added annotation.
Do not treat docs examples as accounting truth
All monetary values in real integrations are raw-first. Use `raw`, `decimals`, and immutable event-time metadata for reconciliation. Display strings are there for human readability.