Authentication

All API requests must include an API key. ZevPay uses a key pair model: each pair consists of a secret key and a public key.

API key types

Key Type	Prefix	Use on	Purpose
Secret key	sk_live_ or sk_test_	Server only	Full access — initialize sessions, verify payments, manage resources
Public key	pk_live_ or pk_test_	Client (browser)	Initialize sessions (inline checkout), load checkout UI, select payment methods

Never expose your secret key

Secret keys grant full access to your account. Never include them in frontend code, public repositories, or client-side bundles.

What each key can do

Endpoint	Secret key	Public key
Initialize session	Yes	Yes (with origin validation)
Select payment method	Yes	Yes (with origin validation)
Get session	Yes	Yes (with origin validation)
Verify session	Yes	Yes
All other endpoints	Yes	No

Public keys can initialize checkout sessions directly from the browser — this is how the Inline Checkout SDK works without requiring a backend. When allowedDomains is configured on the API key, the request's Origin header is validated against the whitelist.

Sending your API key

Include the key in the x-api-key header:

curl https://api.zevpaycheckout.com/v1/checkout/session/initialize \
  -H "x-api-key: sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100000, "email": "test@example.com"}'

Alternatively, use the Authorization header with a Bearer prefix:

Authorization: Bearer sk_test_your_secret_key

API key permissions

Each API key has a permissions array that controls which product APIs it can access. Permissions are managed from the Business Dashboard.

Available permissions

Permission	Products	Account type	Description
checkout	Checkout Sessions	All	Initialize and manage checkout payment sessions
invoices	Invoices	Business only	Create and manage programmable invoices
virtual_payid	Static PayID, Dynamic PayID	All	Create and manage virtual PayIDs
virtual_account	Virtual Accounts	All	Create temporary bank accounts for collecting payments
transfers	Transfers	Business only	Programmatically send money from a wallet

Legacy keys

API keys created before the permissions system was introduced have an empty permissions array. These keys retain access to all non-transfer products automatically. Only the transfers permission must be explicitly granted.

Permissions and account types

Some products are only available to business accounts:

Product	Personal account	Business account
Checkout Sessions	Yes	Yes
Virtual PayID	Yes	Yes
Virtual Accounts	Yes	Yes
Invoices	No	Yes
Transfers	No	Yes

How permissions are assigned

• Checkout, invoices, virtual_payid, virtual_account — Configured when creating or editing an API key in the Business Dashboard
• Transfers — Granted automatically when a programmable-debit wallet is linked to the API key from the wallet settings

Permission errors

If an API key lacks the required permission for an endpoint, the API returns:

{
  "statusCode": 403,
  "message": "API key does not have 'transfers' permission.",
  "error": "Forbidden"
}

Domain whitelisting

Public keys can be restricted to specific domains. When allowedDomains is configured on an API key, requests using the public key must include an Origin or Referer header matching one of the allowed domains.

Configure allowed domains in the Business Dashboard > Developers > API Keys section.

Matching rules

Pattern	Matches	Example
example.com	Exact domain only	https://example.com
*.example.com	Any subdomain + the domain itself	https://shop.example.com, https://example.com

Example configuration

If you set allowedDomains to ["mystore.com", "*.mystore.com"]:

✅ https://mystore.com           → allowed (exact match)
✅ https://shop.mystore.com      → allowed (wildcard match)
❌ https://evil-site.com         → rejected
❌ https://mystore.com.evil.com  → rejected

Recommendation

For production, always configure allowedDomains on your public keys to prevent unauthorized sites from using your API key.

Live vs test mode

Mode	Key prefix	Real money?	Purpose
Test	sk_test_ / pk_test_	No	Development and testing
Live	sk_live_ / pk_live_	Yes	Production payments

Both modes use the same API base URL:

https://api.zevpaycheckout.com

The mode is determined entirely by which key you use.

Key management

• Create, rotate, and deactivate keys from the Business Dashboard
• Each key pair shares a webhook secret for signature verification
• You can create multiple key pairs (e.g., one per environment or application)
• Configure permissions per key to follow the principle of least privilege