Authentication
HTTP Basic API key pairs, key prefixes, rotation, and operational hygiene.
Every Merchant API request authenticates with an API key pair using HTTP Basic.
Authorization: Basic <base64(publicKey:secretKey)>The username is the public key (pk_test_… / pk_live_…); the password is the secret key (sk_test_… / sk_live_…). Bearer tokens are not accepted: secret keys are stored only as a salted one-way hash, so the public key identifies the key pair and the secret key is verified against that stored hash.
# curl encodes Basic for you:
curl -u "$API_PUBLIC_KEY:$API_SECRET_KEY" https://api.voltzpay.co/meThere is no other auth scheme. There is no cookie, no session, no signed query parameter.
Key prefixes
The public key prefix is the environment stamp. The merchant id and the live or test environment are bound to the key pair at creation; the API trusts the key, never the request.
| Public prefix | Secret prefix | Environment | Behaviour |
|---|---|---|---|
pk_live_* | sk_live_* | Live | Creates real-money orders; routes to live PSP credentials. |
pk_test_* | sk_test_* | Test | Creates test orders; routes to test PSP credentials only. |
The same key never crosses environments. There is no body or query field that can override it. See Environments for the full isolation model.
Rotation
Both pairs stay valid until you revoke the old one. The overlap is intentional: a deploy never races a revoke.
Create a replacement
Create a new key pair in the same environment from the dashboard.
Roll it out
Deploy the new pair to every running instance.
Verify
Confirm with GET /me from a rolled instance. A 200 with the expected environment means the new pair is live.
Revoke the old pair
Revoke the previous key pair from the dashboard. A revoked key returns 401 api_key_revoked on its next request.
What never to do
The Merchant API is server-to-server. A secret key in a browser bundle, a URL, or a committed file is a compromised key. Rotate it immediately.
- Do not log raw secret keys. Redact to the prefix and last four characters at most. Public keys are safe to log.
- Do not put a key in a URL, a query string, or a referrer-leakable header.
- Do not embed a secret key in a frontend bundle. The API is server-to-server.
- Do not commit a secret key to a repository. Use the secret manager your platform provides.
- Do not share a single key pair across unrelated services. One pair per integration makes revocation surgical.
Errors
| Code | HTTP | Meaning |
|---|---|---|
api_key_missing | 401 | No Authorization header on the request. |
api_key_malformed | 401 | Header present but not a valid Basic credential pair. |
api_key_invalid | 401 | Key pair not found or secret mismatch. |
api_key_revoked | 401 | Key pair was valid but has been revoked. |
merchant_inactive | 401 | Merchant disabled, soft-deleted, or unreachable. |
See Error codes for the full closed union.