How to authenticate
Send your key as an HTTP header on every request:
X-API-KEY: your-key-here
That's it. No other headers, no signature, no timestamp. Any request missing the header — or carrying a key that doesn't match — comes back 401.
Sandbox vs live
Both environments share the same base URL. The key you send decides where the request lands:
- Sandbox keysroute to a test payment gateway. Test cards work, real cards don't. Webhooks fire the same way as production. Use these for every stage of development up to pre-launch sign-off.
- Live keysroute to a production payment gateway. Real cards, real money, real PCI-DSS controls. Issued when you're onboarding as a customer.
Your integration code is identical across both — only the key value changes. Store the key in an environment variable, never in source control.
IP whitelisting
Live keys can be locked to a set of source IPs. Tell us the CIDR ranges your servers call from and we'll scope the key. A request from any other IP comes back 401 even if the key is otherwise valid. Strongly recommended for any server-to-server integration.
Rotating a key
If a key leaks, rotate it. We issue a new key, you deploy it to your environment variables, then we revoke the old one. Keys can overlap for as long as you need during deployment — there's no forced switchover window.
Browser safety
API keys must not end up in browser code. The try-it explorer on these docs pages sends your key to a Paytia-hosted proxy over HTTPS and never stores it; that's fine for testing. But for your production integration, all calls should originate from your server or a trusted backend.
Getting a key
Sandbox keys are free and issued on request — no commitment, no sales call needed. Live keys are issued during onboarding. Request API access →