Security best practices

Keys

• Secret keys stay on your server. Anyone with sk_live_… can create payouts from your balance. Never put a key in a website, a mobile app, a URL, a support ticket or a Git repository.
• Treat test keys as secrets too: they can create test objects and read test data in your account.
• If a key leaks, ask Xaalis for a new one immediately and remove the old one from your systems.
• Load keys from environment variables or a secret manager; keep them out of logs and error trackers.

Webhooks

• Verify every request’s Xaalis-Signature with your webhook secret before reading it, over the raw body, with a constant-time comparison, and reject timestamps older than 5 minutes. The Node SDK does all of this.
• Use a hard-to-guess path (/webhooks/xaalis-7f3a…) — not a replacement for the signature, but it cuts noise.
• Deduplicate on the event id, and re-read the object from the API when the order of events matters.

Payments and the customer

• Never mark an order paid from the browser or from the redirect to success_url — only from your server after a verified webhook or a server-side GET /v1/payments/{id}.
• The checkout_url contains a per-payment secret (cs=). Don’t log it, don’t send it to analytics, and don’t show it to anyone but that customer.
• Don’t put personal data you don’t need in metadata.

Payouts

• Protect the code path that creates payouts as strictly as your admin panel: authenticated staff only, with an audit trail on your side.
• Always send an Idempotency-Key so a retried withdrawal can never be sent twice.
• Double-check recipient numbers (+2217XXXXXXXX) — a payout that reaches the wrong wallet can’t be pulled back.

Reporting a vulnerability

Write to security@xaalis.org with what you found and how to reproduce it. Don’t test against other merchants’ data or real money, and don’t publish details until we’ve answered and fixed it. A leaked key of your own: roll it in the dashboard first (Développeurs & API → Clés d’API), then tell us.