Zenpay API Documentation

Overview

After payment completion, customers are redirected back to your merchant site with payment data via POST request. This ensures secure data transmission and allows you to update your system with the payment status.

Note: The payment flow shown here is for user experience only. Since the displayed status may change, your system must rely on the callback to determine and update the final order status.

Redirect Flow

The redirect flow is the final step in the payment process. It is the process of redirecting the customer to the return_url or decline_url with the POST data.

The redirect flow is as follows:

↳ Customer completes payment on FPX gateway.
↳ FPX sends payment response to ZenPay.
↳ ZenPay processes the response and prepares redirect data.
↳ Customer is redirected to your return_url or decline_url with POST data.

Redirect URLs

URL Type	When Used	Description
return_url	Successful payments (status_code = "00")	URL where customers are redirected after successful payment completion
decline_url	Failed payments (status_code ≠ "00")	URL where customers are redirected after failed or cancelled payment

POST Data Parameters

Parameter	Type	Description	Example
amount	string	Transaction amount in decimal format	100.00
appln_id	string	Application identifier ( "ZNS" for staging and "ZNN" for production)	ZNN
bank_id	string	Bank identifier code used for payment	MBB0227
bank_name	string	Bank name (same as bank_id)	MBB0227
biller_code	string	Your merchant biller code	202500039
fpx_id	string	FPX transaction identifier	FPX12345213126
fpx_mode	string	FPX processing mode (always "2")	2
order_id	string	Your original order reference ID	ORD-2024-001
payref_id	string	ZenPay payment reference ID	ZNN1231243232
process_mode	string	Processing mode (always "automatic")	automatic
status	string	Payment status (SUCCESSFUL/UNSUCCESSFUL)	SUCCESSFUL
status_code	string	FPX status code ("00" for success)	00
trx_datetime	string	Transaction datetime in YmdHis format	20240115103000
timestamp	string	Current timestamp in ISO 8601 format	2025-07-15T05:12:18Z
signature	string	HMAC-SHA256 signature for data verification	abc123...

Example Redirect Data

amount=100.00
appln_id=ZNN
bank_id=MBB0227
bank_name=MBB0227
biller_code=202500039
fpx_id=FPX12345213126
fpx_mode=2
order_id=ORD-2024-001
payref_id=ZNN1231243232
process_mode=automatic
status=SUCCESSFUL
status_code=00
trx_datetime=20240115103000
timestamp=2025-07-15T05:12:18Z
signature=abc123def456...

Implementation Example

<?php
// Handle redirect from ZenPay
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $receivedData = $_POST;
    $receivedSignature = $receivedData['signature'] ?? '';

    // Remove signature from data for verification
    unset($receivedData['signature']);

    // Generate expected signature
    $expectedSignature = hash_hmac('sha256', json_encode($receivedData), $merchantSecretKey);

    // Verify signature
    if (hash_equals($expectedSignature, $receivedSignature)) {
        // Signature is valid, process the payment
        $orderId = $receivedData['order_id'];
        $status = $receivedData['status'];
        $amount = $receivedData['amount'];

        if ($status === 'SUCCESSFUL') {
            updateOrderStatus($orderId, 'paid');
            header('Location: /success?order_id=' . $orderId);
        } else {
            updateOrderStatus($orderId, 'failed');
            header('Location: /failed?order_id=' . $orderId);
        }
    } else {
        error_log('Invalid signature received from ZenPay');
        header('Location: /error');
    }
}
?>

Important Notes

Redirects happen after redirect button is clicked
Data is sent via POST method to ensure security
Always verify the signature before processing the data
Handle both successful and failed payment scenarios
Update your order status based on the payment result
The data sent in this step is not final. The payment status may change. Please rely on the callback to update the order status.