Authentication
Learn how to authenticate your requests to the ZenPay API and secure your integration.
Authentication Methods
ZenPay API endpoints use different authentication methods. Check each endpoint’s docs to see what’s required.
- API Keys: Used for endpoints like fetching bank lists.
- Secret Keys: Used to generate request signatures for secured endpoints such as payments, transaction queries, payouts, and manual callbacks.
HMAC-SHA256 Signature Authentication
The signature is generated by concatenating the request body with the secret key and then hashing it with SHA-256. Please refer to the Signature Generation page for more details on the request body.
X-Signature: {HMAC-SHA256-signature}
The signature is then included in the X-Signature header of the request.
API Keys
Some endpoints require an API key to be included in the X-API-Key header of your requests:
X-API-Key: {API-KEY}
The API key is included in the X-API-Key header of the request.
No Authentication
Some endpoints do not require authentication. e.g health check endpoints.
IP Whitelisting
ZenPay uses IP whitelisting to secure some endpoints.
To whitelist your IP address:
- ↳ Login to your merchant dashboard.
- ↳ Request IP whitelisting through your merchant dashboard under the Security > IP Whitelist section. Provide the IP addresses that would make API calls.
- ↳ Once approved, the IP addresses will be whitelisted and can be used to make API calls.
Important: Endpoints that require IP allowlisting will return a 403 Forbidden response if the request comes from a non-allowed IP..
Timestamp Validation
To ensure the integrity of the request, ZenPay validates the timestamp of the request. The timestamp is included in the request body. This parameter is required for all secured endpoints. Refer to each endpoint's documentation for the required timestamp parameter.
Valid Timestamp Format
The timestamp must be in UTC ISO 8601 format and include the 'Z' timezone indicator.
2025-01-15T10:30:00Z
The timestamp must be within 5 minutes of the current time.
Important: Request with timestamps older than 5 minutes will be rejected with a 400 Bad Request response.