API keys and modes
One key per mode, sent as a bearer token. The key decides whether money is real.
Every request to the payments API carries a secret key in the Authorization header:
curl https://api.paywithvolume.com/v1/account \
-H "Authorization: Bearer vk_test_..."A missing, wrong or revoked key is 401 invalid_api_key.
Test and live
The key's prefix is its mode:
| Key | Mode | Money |
|---|---|---|
vk_test_… | Test | Simulated. Nothing moves, and payers are never emailed. |
vk_live_… | Live | Real. |
Both use the same base URL, https://api.paywithvolume.com. The two modes share
nothing: an invoice, a checkout, a webhook endpoint or a balance made with a test key
does not exist for a live key, and asking a live key for a test invoice is 404. Every
object carries livemode, so your code can tell which it holds.
Moving from test to live is a change of key, not of code.
Getting keys
Keys are made in the dashboard, under Developers, by a person who is logged in. Name each one for where it will live ("Monierate server"), then copy it: Volume stores only a hash, so it shows the key this once. If a key is lost, revoke it and make another. Revoking stops it at once.
An API key cannot make or revoke keys, so a leaked key can never mint itself a replacement. The same goes for payout accounts and withdrawals: they are managed while logged in, never with a key. A leaked key can create invoices and read your payments; it cannot send your money anywhere.
Making keys from code
The dashboard runs on the same API. To script it, log in with POST /v1/auth/login
(your email and password); its session.token (vss_…) is the bearer for the next
call. Then POST /v1/api_keys with an Idempotency-Key and
{ "mode": "test", "name": "Monierate server" }. A live key also needs a fresh code
from your authenticator app: send { "code": "123456" } to POST /v1/auth/step_up
with the same token first. These are login routes, not API-key routes, so the
reference here does not list them.
Live access
New accounts are pending: they can use test mode only, while Volume reviews the
business. Once Volume activates the account, GET /v1/account shows
"status": "active" and "live_access": true, and live keys can be made. Until then a
live request is refused with 403 live_access_required.
Making a live key asks for a code from an authenticator app, set up under Settings in the dashboard. See going live.
Keep keys on your server
A key is a password for your account. Keep it in your server's environment, never in a browser, a mobile app or a repository. The hosted checkout means the payer's browser never needs one: it talks to Volume, not to your key.
The playground on each reference page takes test keys only.