Documentation Payment Operations/initiate Payment

Payment Operations - Initiate Payment

Process payments securely with our payment API endpoints

Overview

The initiate payment endpoint allows you to create a new payment initiation to collect payment from customers. This endpoint creates a payment request and returns an HTML form that redirects users to the FPX payment gateway.

This endpoint requires Signature Authentication, IP Whitelisting, and is subject to Rate Limiting.

Request

Http Method & URL

POST /v1/payments/initiate

Headers

Header	Type	Required	Description
Content-Type	string	Yes	application/json
X-Signature	string	Yes	HMAC-SHA256 signature for request authentication

Signature Generation: Refer to the Signature Generation section for detailed steps on generating the X-Signature header value.

Timestamp Validation: Requests with timestamps older than 5 minutes will be rejected. Ensure your system clock is synchronized with UTC.

Parameters

Parameter	Type	Required	Description
biller_code	string	Yes	Merchant identifier code
order_id	string	Yes	Unique order identifier from merchant system
amount	string	Yes	Payment amount (string with 2 decimal places) e.g. "100.00"
currency	string	Yes	Currency code (e.g., "MYR")
bank_code	string	Yes	Bank code for payment processing
bank_type	string	Yes	Bank type: Either "01" or "02" (Retail - 01 / Corporate - 02)
email	string	Yes	Customer email address
return_url	string	No	URL to redirect after successful payment with POST data
decline_url	string	No	URL to redirect after failed payment with POST data
callback_url	string	Yes	Webhook URL for payment notifications
timestamp	string	Yes	Request timestamp in ISO8601 UTC format (e.g., "2024-01-15T10:30:00Z")

Bank Code: Refer to the Retail or Corporate bank list for parameter bank_code values.

Request Body Example

{
  "biller_code": "MERCHANT001",
  "order_id": "ORD-2024-001",
  "amount": "100.00",
  "currency": "MYR",
  "bank_code": "BIMB0340",
  "bank_type": "01",
  "email": "customer@example.com",
  "return_url": "https://merchant.com/success",
  "callback_url": "https://merchant.com/webhook",
  "decline_url": "https://merchant.com/failed",
  "timestamp": "2024-01-15T10:30:00Z"
}

Response

Success Response (200)

The response returns an HTML form that automatically redirects to the FPX payment gateway. This must be opened in a new full page or current page - popup windows or ajax submissions will not work with the FPX payment flow.

<html>
<body>
    <form id="fpxForm" action="https://www.mepsfpx.com.my/FPXMain/seller2DReceiver.jsp" method="POST">
        <input type="hidden" name="fpx_buyerAccNo" value="">
        <input type="hidden" name="fpx_buyerBankBranch" value="">
        <input type="hidden" name="fpx_buyerBankId" value="RHB0218">
        <input type="hidden" name="fpx_buyerEmail" value="customer@example.com">
        <input type="hidden" name="fpx_buyerIban" value="">
        <input type="hidden" name="fpx_buyerId" value="">
        <input type="hidden" name="fpx_buyerName" value="">
        <input type="hidden" name="fpx_checkSum" value="272357ABB198B7D7...">
        <input type="hidden" name="fpx_makerName" value="">
        <input type="hidden" name="fpx_msgToken" value="01">
        <input type="hidden" name="fpx_msgType" value="AR">
        <input type="hidden" name="fpx_productDesc" value="ZNS250715038036">
        <input type="hidden" name="fpx_sellerBankCode" value="01">
        <input type="hidden" name="fpx_sellerExId" value="EX00013275">
        <input type="hidden" name="fpx_sellerExOrderNo" value="ZNS250715038036">
        <input type="hidden" name="fpx_sellerId" value="SE00075393">
        <input type="hidden" name="fpx_sellerOrderNo" value="ZNS250715038036">
        <input type="hidden" name="fpx_sellerTxnTime" value="20250715113936">
        <input type="hidden" name="fpx_txnAmount" value="122.22">
        <input type="hidden" name="fpx_txnCurrency" value="MYR">
        <input type="hidden" name="fpx_version" value="7.0">
    </form>
    <script>
        document.getElementById("fpxForm").submit();
    </script>
</body>
</html>

Redirect Handling: After payment completion, customers are redirected to your return_url or decline_url with payment data via POST request. See Redirect Handling for detailed information about the redirect flow and data parameters. The data sent in this step is not final..

Authentication Error Response (401)

{
    "success": false,
    "message": "Authentication failed",
    "errors": [
        {
            "field": "signature",
            "message": "Invalid signature"
        }
    ]
}

Validation Error Response (400)

{
    "success": false,
    "message": "Validation failed",
    "errors": [
        {
            "field": "bank_type",
            "message": "bank_type must be one of the allowed values"
        },
        {
            "field": "amount",
            "message": "amount must be a decimal number with exactly 2 decimal places"
        }
    ]
}

Was this helpful?

Corporate

Hosted Payment Page