Skip to main content

​
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

​
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.
Payout keys are appropriate for:
  • 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. 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.
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.
  • 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.