API And SDK Reference Guide
The SDK is the recommended starting point for Node.js and TypeScript backends. Raw REST remains available for teams that need direct HTTP integrations.
Important note: The SDK is server-side only. It intentionally excludes admin routes, dashboard session flows, route-template mutation, internal gas controls, signer details, and provider-specific infrastructure.
How to use these docs
- Use SDK guide when you are integrating from a Node.js or TypeScript backend.
- Use REST API guide when you need direct HTTPS examples or are not using the SDK.
- Use Payment flows when choosing between fixed amount invoices, auto-detected payments, payout routes, dynamic recipients, and programmatic withdrawals.
- Use OpenAPI reference when you need exact endpoint paths, schemas, and parameters.
- Use Webhooks, Status lifecycles, Errors, rate limits, and idempotency, and Reconciliation for production integration behavior.
- Use this page as the high-level reference index for auth, environments, key separation, webhooks, and reconciliation.
Environments
| Environment | Purpose |
|---|
| Sandbox | Test invoices, webhook verification, payout workflow rehearsal, and integration development. |
| Live | Production payments, balances, withdrawals, billing, and usage. |
Authentication
- Standard API keys are sent as
x-api-key.
- Mutating requests should send
Idempotency-Key.
- Payout operations require a payout API key where supported.
- Dashboard-only actions require dashboard session auth and may require step-up.
Key separation
| Key type | Can do | Cannot do |
|---|
| Standard API key | Customers, invoices, reads, balances, transactions, networks, tokens, webhooks. | Move funds, create payout routes, create API keys, admin actions. |
| Payout API key | Programmatic withdrawals and approved dynamic payout recipient flows within policy. | Admin routes, dashboard-session routes, route-template mutation, billing mutation. |
Developer essentials
- Base URLs.
- Authentication headers.
- Request and response examples.
- Error codes and request IDs.
- Idempotency behavior.
- Webhook signature verification.
- Retry behavior and delivery limits.
- Rate limits.
- SDK install and usage.
- Production readiness checklist.
- Billing usage endpoints for showing plan, quota, gas balance, top-up state, and blocked operations.
Webhook verification language
PayChain sends webhooks when an invoice, withdrawal, or routing event changes state. Your backend should verify every webhook before acting on it. Verification must use the raw request body, not parsed and re-stringified JSON. After verification, fetch the canonical invoice or withdrawal record before crediting a user, releasing an order, or marking a payout complete.
Raw body note: Verification must use the exact raw request body. Parsed JSON, pretty-printed JSON, or re-stringified JSON can produce a different signature input.
Reconciliation language
Use balances to understand treasury availability, transactions to reconcile invoice and withdrawal activity, networks to discover supported rails, and tokens to confirm which assets can be accepted or withdrawn. Do not treat raw wallet balances as invoice truth. Invoice state and signed webhook events remain the source of truth for customer payments.