Start here
Authentication, environments, and request hygiene
PayChainHQ external integrations should use standard or payout API keys from your backend and treat sandbox and live as distinct operational environments.
Auth model
External integrators should keep API credentials on the server and call the documented APIs from backend services.
| Auth mode | Use it for | Do not use it for |
|---|---|---|
| Standard `x-api-key` | Server-to-server invoice, customer, balance, billing, webhook, and reference-data calls. | Browser-based calls, API-key management, contract signing, or withdrawal creation. |
| Payout `x-api-key` | Programmatic withdrawal creation and payout polling, constrained by destination policy, token, network, spend, and optional IP policy. | Invoice creation, dashboard sessions, API-key management, or arbitrary treasury movement. |
| Dashboard session + step-up | Creating, rotating, revoking, and reviewing standard or payout API keys; operator-initiated withdrawals. | Long-lived server-to-server integration secrets. |
| Public routes | Hosted invoice reads and public reference-data endpoints. | Any mutating business operation or authenticated balance flow. |
Recommended pattern
Your application backend should call PayChainHQ with API keys stored in a server-side secret manager. Human operators sign into the dashboard separately to create standard keys, issue payout keys with guardrails, and revoke credentials.
Standard keys do not move funds
A standard API key cannot create withdrawals even if an older key once had wildcard or payment scopes. Programmatic withdrawals require a payout API key created with destination policy and spend limits.
CORS is not the integration path
CORS matters only for browser-origin traffic. External API-key integrations should not call PayChainHQ directly from the browser. If you are testing first-party or embedded browser flows, allowed origins must be coordinated separately.
Sandbox vs live
The biggest integration mistakes usually come from mixing these two up.
Sandbox
Use for setup, test invoices, webhook verification, and payout workflow rehearsal. Sandbox activation does not imply live access.
Live
Requires separate approval. Live credentials, balances, notifications, and approval state should be treated as distinct from sandbox.
Switching
Do not reuse environment assumptions. A business may be fully active in sandbox while still locked in live.
Environment caution
Never share a live API key or webhook secret into sandbox tooling, and never assume sandbox invoice behavior is proof that live access is approved.
Idempotency and traceability
Mutating financial calls should always be replay-safe on your side.
- Send `Idempotency-Key` on every `POST`, `PATCH`, and `DELETE` that can create or mutate financial state.
- Persist PayChainHQ resource IDs plus your own `clientReference` / `externalRef` so you can reconcile retries cleanly.
- Log the `x-request-id` value for every failed request. Support and incident analysis depend on it.