Get started
Authentication
Every API call carries a short-lived access token. Get one by sending your API key and secret to Create token, then send it as Authorization: Bearer <token>.
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.
Paylinks, invoices and proposals work the same way: a test key's are sandbox ones, paid with test cards (a sandbox proposal's invoice too), and a test key can't see a live one (404). In test mode, emails go only to your team's addresses: a sandbox invoice, proposal, payment receipt or subscription email reaches only you and your team members (marked TEST MODE), never a real client.
Live key
Moves real money. Requires an approved, charges-enabled VezmoPay account: you can generate one in Developers once VezmoPay is approved, and until then the dashboard offers test keys only. Keys and data are mode-locked: a test key can never act on live payments (and vice versa) — crossing modes returns a 404. For an object your business has in the other mode, its message says so ("No such invoice: a similar object exists in live mode, but a test mode key was used to make this request.").
Both key types use the same base URL and the same authentication flow below — going live is just swapping the key.
Keys and tokens
API key and secret
The key is vzm_ followed by 16 characters, e.g. vzm_xxxxxxxxxxxxxxxx. The secret is 32 characters and is shown once, when you create the key. Send them only to Create token, in the x-api-key and x-api-secret headers. Create token allows 5 requests a minute from one IP address, so reuse the token it gives you.
Access token
Lasts 30 minutes. Send it as Authorization: Bearer <token> on every call to clients, products, invoices and the other endpoints. A token from a dashboard sign-in doesn't work here and returns 401.
Refresh token
Lasts 7 days from Create token. Refresh token trades it for a new access token without your secret. It is not replaced when you use it, so create a new token before the 7 days are up.
When you replace a key
Creating a new key replaces your active key of the same kind (test or live). Tokens from the old key stop working at once and return 401, and so does refreshing them. On a 401, try Refresh token first; if that also returns 401, create a new token with your current key and secret.