Authentication
Every ZyraPay API request authenticates with a project API key sent in the x-api-key header. This page covers where the key comes from, how it's stored, how to rotate it, and how to make requests safely idempotent.
All requests target https://api.zyrapay.net/v1 and carry your project's API key. There is a single credential for the integration — no tokens to mint, no OAuth dance.
Account management lives in the dashboard
Creating projects, viewing transaction history, and managing payouts are done in the ZyraPay dashboard, which runs on its own signed-in session. You never handle that session in your server code — your integration only ever uses the API key below.Your API key
The API key identifies a single project. Send it on every request in the x-api-key header (the header apikey is accepted as an alias).
curl https://api.zyrapay.net/v1/checkout \
-H "x-api-key: $ZYRA_API_KEY"Routes that authenticate with the API key:
POST /v1/checkout,GET /v1/checkout,GET /v1/checkout/:checkoutId,DELETE /v1/checkout/:checkoutIdPOST /v1/wallets
A missing key returns 401 { "message": "API key is required" }; an unknown key returns 401 (or 403 on the wallet route).
Where to get your key
Sign in to the dashboard and create a payment project (for hosted checkouts) or a wallet project (for deposit addresses). Each project has its own API key, shown when the project is created. Use a separate project per store or per environment to keep keys isolated.
Keys are shown once, then hashed
Copy the key immediately — it is never shown again
The plaintext API key is shown exactly once, when the project is created. ZyraPay never stores it in plaintext, so it cannot be displayed again. Keep it server-side — never embed it in browser or mobile code.Your key is a 64-character random string. ZyraPay stores only a hash of it (never the key itself), plus a short non-secret prefix shown in the dashboard so you can tell keys apart. If the key is ever exposed, rotate it — the old one stops working immediately.
Rotating a key
Rotate a key from the project's settings in the dashboard. Rotation generates a fresh key and immediately invalidates the old one — there is no separate "revoke" step, because rotating kills the previous key.
Rotation is a hard cutover
The moment you rotate, the old key stops working. Deploy the new key to every service that uses it before (or immediately after) rotating to avoid a gap in service.Idempotency
Create and money-moving requests accept an Idempotency-Key header: send a unique value and a retried request replays the original response instead of acting twice. Pass it on POST /v1/checkout, POST /v1/wallets, and the gateway /v1/payment routes. Full replay semantics (including the 24-hour window) and a safe-retry loop are in Advanced.
Next step
Harden your integration with safe retries, refunds, and error handling in Advanced.