On this page
API Keys
Create Payment or Payout API keys, understand their scopes and prefixes, rotate credentials safely, and separate test from live access.
Paymos issues two key types per environment, each scoped to a fixed set of operations. A leaked Payment credential cannot move funds — scope is checked centrally on every request, so a Payment key can never reach a payout endpoint no matter which route it hits.
Key types
| Type | Prefix | Scope |
|---|---|---|
| Payment | pk_ |
Create invoices, read invoice status |
| Payout | rk_ |
Create withdrawals, cancel withdrawals, read balances |
API secrets use the sk_ prefix. Webhook signing secrets use whsec_.
Environments
Every credential is tied to one environment. The environment is encoded in the prefix:
| Environment | Prefix modifier | Example |
|---|---|---|
| Production | _live_ |
pk_live_…, rk_live_… |
| Sandbox | _test_ |
pk_test_…, rk_test_… |
A fully-configured merchant holds four API key IDs (pk_live_…, pk_test_…, rk_live_…, rk_test_…) and two webhook secrets (whsec_live_…, whsec_test_…).
Scope details
The scope split is enforced centrally, not per route: the access level is derived from the key type on every request, so a Payment key reaches only invoice endpoints and a Payout key only payout endpoints.
One extra guard applies to Payout. A Payout credential stays inactive until you add an IP whitelist — every request is rejected until at least one allowed IP is configured in the dashboard. A freshly generated Payout key cannot move funds on its own.
A Payout key can move funds out of your Paymos balance — treat it like your bank password. The IP whitelist is the wall between a stolen key and your money, so keep it as narrow as possible: list only the server IPs that actually call the payout API.
Lifecycle
| Status | Description |
|---|---|
| Active | Credential is operational and accepts requests |
| Revoked | Terminal state. Credential is permanently disabled and cannot be reactivated |
Security best practices
- —Never expose API secrets in client-side code
- —Rotate secrets periodically via the dashboard — a grace period keeps the previous secret valid during transition
- —Use separate credentials for production and sandbox
- —Restrict Payout credentials by IP address
- —Store API secrets only in environment variables or a secrets manager
See Authentication for the HMAC-SHA256 signing scheme that uses these credentials.