> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paychainhq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Api keys

# API Keys And Permissions

API keys control what a backend can do with PayChain. Treat them like production payment credentials.

<Warning>
  **Important note:** Never expose PayChain API keys in browser JavaScript, mobile apps, static sites, public repositories, support screenshots, analytics tools, or logs.
</Warning>

## 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.

<Warning>
  **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.
</Warning>

Payout keys are appropriate for:

* Programmatic withdrawals.
* Dynamic payout recipients on invoices.
* Backend-controlled treasury movement.

<Warning>
  **Payout safety note:** Validate payout destination, order status, amount, customer risk, and business limits in your own backend before sending payout instructions to PayChain.
</Warning>

## 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.                                     |

If a payout request violates policy, PayChain rejects it before fund movement. Your backend should treat the rejection as a failed business action, show a human-readable reason, and avoid blind retries.

### Debugging payout policy rejections

When a payout API request is rejected:

1. Check the HTTP status and error `code`.
2. Confirm the key type is a payout API key.
3. Confirm token, chain, and `networkId`.
4. Confirm destination policy allows the receiver.
5. Confirm amount and daily cap.
6. Confirm source IP policy if configured.
7. Log the PayChain `requestId` without logging secrets.

<Info>
  **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.
</Info>

## 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.