Security best practices

Protect your API keys, webhook secrets and terminals, and design your integration so a mistake cannot move money twice.

API keys

Server side only. A secret key never goes into a browser, a mobile app, a POS app or a public repository. Publishable keys cannot call the API today.
One key per system, minimal scopes. A reporting job needs payments:read, not refunds:write. A leaked read-only key cannot move money.
IP allowlist on every live key whose callers have fixed egress addresses.
Secrets manager, not environment files committed to a repository. ZyloPay keys start with zp_, so secret scanners such as GitHub push protection can flag a leak.
Rotate on a schedule and when people leave. Rotation keeps the old key alive for an overlap you choose, so it causes no downtime.
Expiry dates for keys given to contractors or temporary systems.
Watch the audit log (Developers → Audit log). It records who created, rotated, revoked or deleted a key or changed a webhook endpoint.

If a key leaks: rotate it with a zero overlap (or revoke it), check the audit log and your request logs, and tell ZyloPay support.

Verify every signature on the raw body, with a constant-time comparison and the 5-minute tolerance. See Verify signatures.
Deduplicate on the event ID. It stops replays and harmless duplicates alike.
Treat the payload as a notification. For high-value actions, re-read the object from the API before acting.
Keep the signing secret secret. Rotate it like a key. Each endpoint has its own.
Use https, required in live mode.

Idempotency keys from your own records on every payment intent and refund. A retry, a double click or a restarted worker then cannot create a second one.
Never retry a processing intent or a pending refund with a new key. ZyloPay resolves unknown outcomes itself and tells you.
Separate duties. Only the systems and people who must refund should hold refunds:write or the dashboard admin role.
Limits. Your account's daily refund limit and refund window cap the damage of a compromised refund path. Ask ZyloPay to lower them if your business allows.

Device keys are per terminal and per network. Deactivate a lost or stolen terminal at once from the dashboard; its key stops working immediately.
Staff roles and PINs. Use the POS app's owner, manager and cashier roles, and restrict refunds on the device to managers.
Nothing sensitive leaves the pass. The customer's pass carries a credential for that one pass, never keys or signatures. It is read by the terminal and never reaches your servers, so your systems stay out of scope for it.

Store IDs and amounts. Do not store more personal data than you need: payer is a wallet address, which can identify a person when combined with other data.
Do not put personal data or secrets in metadata or description: they are returned by the API and included in webhooks.
Keep request IDs in your logs, not API keys. Redact Authorization headers in any HTTP logging.

Send security reports to ZyloPay support with "Security" in the subject. Do not test against live accounts that are not yours.