Authentication

Every request to the NamibraPay API is authenticated with a key pair sent as two HTTP headers.

API keys

NamibraPay authenticates server-to-server requests with a public key and a secret pair, created per environment from the dashboard (Settings → API Keys). The public key identifies your merchant account; the secret authorizes it.

X-API-Key — your public key, e.g. pk_test_… or pk_live_…
X-API-Secret — the matching secret, e.g. sk_test_… or sk_live_…

Both headers are required on every request. A missing, inactive or mismatched pair returns 401 with error code AUTH_001.

Making authenticated requests

curl "https://api.namibrapay.com/api/v1/transactions/ORDER-12345" \
  -H "X-API-Key: pk_test_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: sk_test_xxxxxxxxxxxxxxxx"

Test vs live mode

The key pair you use decides the environment — there is no separate base URL or flag. Test and live data are fully isolated from each other.

Environment	Keys	Behaviour
Test	pk_test_… / sk_test_…	Simulated money. Available immediately, no compliance approval needed.
Live	pk_live_… / sk_live_…	Real money. Unlocked once your KYC application is approved.

Live keys are denied until approval

Using a live key pair before your compliance status is approved returns 403 with error code BIZ_003 (“Merchant not approved for live transactions”). The attempt is audited. Complete your Compliance application in the dashboard first.

Rate limits

Transaction endpoints are limited to 100 requests per minute per API key. Exceeding the limit returns 429 Too Many Requests — back off and retry with exponential spacing. Webhook deliveries to your endpoint should respond within 10 seconds; slower responses are treated as failures and retried.

Keeping keys safe

Only call the API from your server. Never ship keys in mobile apps, browsers or public repos.
Load keys from environment variables or a secrets manager, not hard-coded strings.
Rotate a compromised pair immediately from the dashboard — regeneration deactivates the old pair.
Use the test pair in staging and CI so a bug can never move real money.