API Keys And Permissions
API keys control what a backend can do with PayChain. Treat them like production payment credentials.
Important note: Never expose PayChain API keys in browser JavaScript, mobile apps, static sites, public repositories, support screenshots, analytics tools, or logs.
Key types
| Key type | Intended use | Fund movement |
|---|
| Standard API key | Customers, invoices, reads, balances, transactions, networks, tokens, and webhooks. | Cannot create programmatic withdrawals. |
| Payout API key | Programmatic withdrawals and approved payout automation from a trusted backend. | Can move funds within policy. |
Standard API keys
Use a standard API key for collection and reconciliation workflows:
- Create customers.
- Create invoices.
- Attach an approved payout route to an invoice.
- Read invoices, balances, transactions, networks, and tokens.
- Configure and inspect webhooks where supported.
Standard API keys should not be able to create withdrawals or mutate dashboard-only controls.
Payout API keys
Use a payout API key only from a backend service that owns payout approval logic.
Pricing note: Payout API keys can create withdrawals when the key policy, balance, and destination checks pass. Free plan businesses have 0 included payout API withdrawals, so the payout API fee applies from the first programmatic withdrawal instead of after included quota is used.
- Programmatic withdrawals.
- Dynamic payout recipients on invoices.
- Backend-controlled treasury movement.
Payout safety note: Validate payout destination, order status, amount, customer risk, and business limits in your own backend before sending payout instructions to PayChain.
Payout policy guardrails
Payout API keys should be created for a narrow job, not for broad account access. A payout key can be constrained by policy so that even trusted backend automation has clear limits.
| Policy dimension | What it controls | Example |
|---|
| Token | Which asset can move. | USDC only. |
| Chain and network | Which rail can be used. | evm on base-mainnet. |
| Destination policy | Whether destinations must be allowlisted or can be dynamic. | Allowlisted seller wallets, or dynamic receivers for an approved ramp service. |
| Per-withdrawal amount | Maximum amount for one payout. | No single payout above $500. |
| Daily cap | Maximum amount over a rolling day. | No more than $5,000 per day. |
| Source IP policy | Optional backend IP restriction. | Only requests from production backend IPs. |
Debugging payout policy rejections
When a payout API request is rejected:
- Check the HTTP status and error
code.
- Confirm the key type is a payout API key.
- Confirm token, chain, and
networkId.
- Confirm destination policy allows the receiver.
- Confirm amount and daily cap.
- Confirm source IP policy if configured.
- Log the PayChain
requestId without logging secrets.
Dynamic recipient note: Dynamic payout recipients are powerful because the receiver can change per invoice. They should only be created from a trusted backend after your system validates the order, receiver, limits, and fraud rules.
Recommended storage
- Store keys in a secret manager or protected environment variables.
- Use separate keys for sandbox and live.
- Use separate keys for collection and payout automation.
- Limit access to production payout keys.
- Rotate keys after suspected exposure or team access changes.
Logging rules
Do not log:
- API keys.
- Webhook secrets.
- Authorization headers.
- Raw webhook bodies containing sensitive metadata.
- Payout destination auth tokens.
- Full SDK client config.
Log instead:
- Request ID.
- PayChain resource ID.
- Your own order or customer reference.
- Status.
- Environment.
- Timestamp.
Common mistakes
- Using one production key in every service.
- Putting API keys into frontend code.
- Reusing sandbox webhook secrets in live mode.
- Letting a standard key perform payout-like work through a proxy service.
- Creating dynamic payout recipients from unvalidated client input.