Authentication

All merchant API endpoints require an API key passed in the x-api-key request header. Unauthenticated endpoints (GET /v1/status, GET /v1/currencies, GET /v1/estimate) do not require the header.

The x-api-key header

curl -X POST "$PAYZUM_BASE/v1/payment" \
  -H "x-api-key: $PAYZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

The header name is case-insensitive. The key must be at least 32 characters long. Keys are randomly generated 32-byte hex strings — a valid key is 64 hex characters.

How keys are stored

payzum stores only the SHA-256 hash of your API key alongside the last 4 characters (the "preview") for identification in the dashboard. The plaintext key is shown once at creation and cannot be retrieved afterwards.

Store your API key in a secrets manager or environment variable immediately after copying it from the dashboard. If you lose the plaintext key you must rotate it — the old key will stop working as soon as rotation completes.

Key lifecycle

Issuance

A key is generated automatically when you create a merchant via the dashboard (Merchants → New merchant). The reveal page shows the plaintext key once. Copy it before leaving the page.

Rotation

To rotate your key, navigate to Merchants → [your merchant] → API key and click Rotate key. A fresh key is generated immediately. The old key is invalidated immediately — rotation takes effect on the next request. Allow a few seconds for the change to propagate fully across all active connections.

Rotation is the only recovery path if a key is lost or compromised.

Revocation (account suspension)

There is no standalone "revoke" action. To permanently block a key, suspend the merchant account via the admin panel. A suspended merchant returns 403 MERCHANT_SUSPENDED on every authenticated request. Existing open invoices continue to receive payments and webhooks, but no new invoices can be created.

Authentication errors

| HTTP | Error code | Cause | |------|------------|-------| | 401 | API_KEY_MISSING | The x-api-key header was not sent. | | 401 | API_KEY_MALFORMED | The key is not a 64-character lowercase hex string. | | 401 | API_KEY_NOT_FOUND | The key format is valid but no merchant matches the hash. | | 403 | MERCHANT_SUSPENDED | The merchant account has been suspended. |

Error responses follow the shape { "statusCode": 401, "code": "API_KEY_MISSING", "message": "..." }.

Rate limiting

After a successful auth check, a per-merchant rate limit is enforced. The limit is 60 requests per 60 seconds. When exceeded, the server responds with:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Back off for at least the number of seconds in the Retry-After header before retrying. The rate limit counter is keyed to the merchant, not the calling IP, so all requests sharing the same API key share the same quota.