Core Resources
Merchant auth module
Authentication is the entry point to the ecosystem. To ensure data integrity and merchant isolation, every API interaction is protected by a short-lived JWT access token, derived from your unique merchant credentials.
Authentication and token lifecycle
Test & live API keys
Every merchant can hold two kinds of keys, created under VezmoPay → Developers → API keys:
Test key Sandbox
Runs your entire integration — sessions, checkout, webhooks, refunds — against an isolated sandbox. No real money ever moves, sandbox activity never appears in your live dashboard (flip the Test mode toggle in the VezmoPay console to see it), and it works before your account is approved. Webhooks for sandbox events carry livemode: false.
Live key
Moves real money. Requires an approved, charges-enabled VezmoPay account. Keys and data are mode-locked: a test key can never act on live payments (and vice versa) — crossing modes returns a 404, exactly as if the object didn't exist.
Both key types use the same base URL and the same authentication flow below — going live is just swapping the key.
Core security architecture
API key & secret pair
Your x-api-key (vzm_…) identifies the merchant, while thex-api-secret acts as the password. These are passed as custom headers to initiate a session.
JWT bearer authorization
The issued access token must be included in theAuthorization: Bearer header for all requests to protected resources like invoices, products, and proposals.
Refresh token mechanism
To minimize security risks, access tokens are short-lived. The refresh token allows your application to securely rotate and obtain new access tokens without re-sending raw API secrets.
Developer security tip
The application gateway will automatically invalidate all active sessions if an API secret is rotated in the dashboard. Always implement logic to handle 401 Unauthorized errors by attempting a token refresh.