Help / Support

To get started with the ZenPay API, follow these essential steps:

1. Contact ZenPay support to get a merchant account and obtain your biller code, API key, and secret key
2. Request IP whitelisting through your merchant dashboard for payment and payout operations
3. Test the health check endpoint: GET /v1/health
4. Learn the HMAC-SHA256 signature process for secure authentication
5. Retrieve available bank lists before initiating payments

All API requests should be made to: https://api.thezenpay.com

Most of the endpoints require the following credentials:

• Biller Code: Your merchant identifier
• API Key: For basic authentication on certain endpoints
• Secret Key: For generating HMAC-SHA256 signatures on secured endpoints

Contact ZenPay support to obtain these credentials for both development and production environments.

Yes, IP whitelisting is mandatory for payment and payout operations. You can request IP whitelisting through your merchant dashboard under the Security → IP Whitelist section. Provide the IP addresses that will make API calls. Once approved, those IP addresses will be able to access secured endpoints.

The X-Signature header is generated using HMAC-SHA256. Follow these steps:

1. Sort all request parameters alphabetically by parameter name
2. Build a query string: key1=value1&key2=value2
3. URL-encode the values
4. Generate HMAC-SHA256 signature using your secret key and the query string
5. Include the signature in the X-Signature header

Refer to the Signature Generation documentation for detailed examples.

Requests with timestamps older than 5 minutes will be rejected with a 400 Bad Request response. Ensure your system clock is synchronized with UTC and use the ISO8601 format with 'Z' timezone indicator (e.g., "2024-01-15T10:30:00Z").

The following endpoints require HMAC-SHA256 signature authentication:

• Payment initiation endpoints
• Transaction query endpoints
• Payout endpoints
• Manual callback endpoints

Bank list endpoints will use API key authentication instead.

For 401 Unauthorized errors, check the following:

• Verify your signature generation process
• Check that you're using the correct secret key
• Ensure parameter sorting is alphabetical
• Confirm URL encoding is applied correctly
• Verify the timestamp format and freshness
• Check that your IP address is whitelisted

You can retrieve bank codes using the bank list endpoints. There are separate endpoints for retail banks: /v1/banks/retail and corporate banks: /v1/banks/corporate. Refer to the Retail or Corporate bank list documentation for details.

Bank type "01" is for retail/individual customers (B2C payments), while bank type "02" is for corporate customers (B2B payments). Choose the appropriate type based on your target customer segment and use the corresponding bank list endpoint.

After payment completion, customers are redirected to your return_url (success) or decline_url (failure) with payment data via POST request. You should also implement webhook handling via callback_url for reliable payment status updates. Refer to Payment Operations → Redirect Handling for detailed information about the redirect flow and data parameters.

This is expected behavior. The FPX payment flow requires a full-page form submission to function correctly. It does not support popup windows or AJAX-based redirections.

If your webhook is not receiving notifications, check:

• The callback_url is accessible from the internet
• Your server accepts POST requests
• SSL certificate is valid (HTTPS required)
• No firewall blocking the requests
• The endpoint responds with HTTP 200 status

Test your webhook endpoint with external tools before going live.

Start with the health check endpoint to verify connectivity. Use your development credentials and ensure your development server's IP is whitelisted. Test with small amounts first and verify that both success and failure scenarios work correctly. Always test webhook handling thoroughly before going to production.