Security
Best practices and compliance for secure integrations with the ePay Business API.
API Key Security
Your secret API key grants full access to your account. Treat it like a password.
Never expose your secret key in client-side code, public repositories, or logs. If a key is compromised, rotate it immediately from the dashboard under Developers → API Keys.
Key hygiene rules:
- Store keys in environment variables or a secrets manager — never hardcoded in source files
- Use
sk_test_…keys in all development and CI environments — they carry no financial risk - Use
sk_live_…keys only in production server-side code - Rotate keys periodically and always after team member offboarding
- Create separate keys per integration so you can revoke one without affecting others
IP Whitelisting
Restrict API access to a fixed set of IP addresses from the dashboard under Settings → IP Whitelist. When a whitelist is configured, any request from an unlisted IP is rejected with 403 Forbidden regardless of whether the API key is valid.
Whitelisting is enforced at the account level and applies to all keys under that account. ePay reads the client IP from forwarded headers (proxy-aware) — spoofed headers cannot bypass this check.
Use whitelisting for production server-to-server integrations where your egress IPs are stable.
Rate Limiting
All endpoints are rate-limited per API key at 100 requests per 60 seconds. Exceeding the limit returns 429 Too Many Requests. Implement exponential backoff rather than retrying immediately.
HTTPS
All API requests must use HTTPS. HTTP requests are rejected. Your webhook callback URL must also be served over HTTPS — ePay will not deliver events to plaintext HTTP endpoints.
Webhook Signature Verification
Every webhook is signed with HMAC-SHA256. See the Webhooks page for the full verification guide and code examples in Node.js, Python, and Go.
Data Collected by ePay
When your customers interact with an ePay-powered checkout, ePay collects the minimum data necessary to process and record the payment.
| Data | When collected | Purpose |
|---|---|---|
| Mobile phone number | Required at transaction initialization | Route payment through the selected provider |
| Email address | Optional at initialization | Receipt delivery and customer identification |
| First name / Last name | Optional at initialization | Display on checkout and receipt |
| Payment amount & currency | Required | Process and record the transaction |
| IP address | Every API request | Fraud detection and IP whitelist enforcement |
| Transaction timestamps | Automatically | Audit trail and reconciliation |
Retention: Transaction records and associated personal data are retained in accordance with ePay's data retention policy and applicable financial regulations. Data is not sold or shared with third parties outside of what is necessary to complete the payment.
Your responsibility: As the merchant, you are the data controller for personal data you collect before passing it to ePay. Ensure your privacy policy covers the data you share during transaction initialization.
Cookies
ePay uses cookies on the hosted checkout page only. No tracking or advertising cookies are set.
| Cookie | Type | Purpose |
|---|---|---|
| Session | Strictly necessary | Maintains the payment session. Stores an opaque session token — no personal data. |
| Security | Strictly necessary | CSRF protection on checkout form submissions. |
| Preference | Functional | Remembers the customer's selected payment method within the session to reduce friction. |
Checklist before going live
Secret key in environment variables
Store your live key in a secrets manager or environment variable — never hardcode it.
Webhook signature verified
Verify X-Epay-Signature on every incoming webhook using timingSafeEqual or hmac.Equal, not string equality.
Webhook endpoint is idempotent
Handle duplicate deliveries safely by deduplicating on the reference field.
Callback URL on HTTPS
Your webhook callback URL must be served over HTTPS — HTTP endpoints are not supported.
IP whitelist configured
If your server has a fixed egress IP, restrict API access from Settings → IP Whitelist.
Test key removed from production
Ensure no sk_test_… key is present in your production environment or CI pipeline.