Introduction

Welcome to the Herepay Payment API. The Herepay Payment API allows your website or application to accept FPX online banking payments from individual and corporate bank accounts. You can initiate payments, redirect customers to their selected bank, receive payment notifications, and verify transaction statuses. Follow the integration guide below to get started.

1. Environments

Always complete your integration and testing in UAT before switching to Production.

Environment	Base URL	Purpose
UAT (Testing)	https://uat.herepay.org	Integration and testing. No real money is charged.
Production (Live)	https://app.herepay.org	Live transactions involving real customers and money.

UAT testing

• Start your integration using the UAT environment.
• Use the test banks available in the UAT bank list.
• Verify the complete payment flow, including payment initiation, bank redirection, callback handling, customer return, and transaction status verification.

Production deployment

UAT and Production credentials are environment-specific. Use the credentials issued for the corresponding environment, including the Secret Key, API Key, and Private Key where applicable.

Do not use UAT credentials for Production or vice versa.

Move to Production only after your integration has been tested successfully in UAT. When going live, update the API base URL and the corresponding environment credentials.

2. How FPX Payment Initiation Works

The Initiate Payment endpoint uses an HTTP POST request with application/x-www-form-urlencoded form data. It also requires the authentication headers specified in the endpoint documentation.

Unlike a typical JSON API, the Initiate Payment endpoint returns a response intended to continue the customer's payment journey. It does not simply return a payment URL or a JSON success message.

Payment flow

1. Customer initiates payment. Your website or application collects the required payment details.
2. Your server sends the request. Your backend sends the form-encoded POST request to Herepay with the required authentication headers.
3. Herepay returns the payment response. Your integration passes the response to the customer's browser as required by the endpoint's response format.
4. Customer completes payment. The customer is redirected to the selected bank to authenticate and authorize the payment.
5. Herepay notifies your server. Your system receives the payment result through the configured callback.
6. Customer returns to your website. The customer is redirected to your configured return URL, where you can display the appropriate payment status.

Important implementation notes

• Do not submit the Initiate Payment request directly from a standard HTML form in the customer's browser. The request requires authentication headers that a regular HTML form cannot set.
• Send the authenticated request from your backend server.
• Handle the response according to the endpoint's documented format. If it contains HTML intended for browser navigation, return or relay it to the browser correctly rather than displaying the raw HTML as text.
• A customer returning to your website does not, by itself, confirm that payment was successful.
• Use the callback and the transaction status endpoint to verify the final payment status before fulfilling an order or marking an invoice as paid.

For implementation details, refer to the Initiate Payment, callback, and transaction status endpoint documentation.

3. Secure Your Credentials

Keep all API credentials secure and process authenticated API requests on your backend server.

• Secret Key and API Key: Send these only through the authentication headers required by the relevant endpoint.
• Private Key: Keep your Private Key confidential. It is used for checksum generation and verification where required.
• Never expose API credentials in frontend JavaScript, mobile application source code, public repositories, or client-side requests.
• Do not log or share credentials in error messages, support tickets, or publicly accessible files.
• Validate callback data and verify the transaction status with Herepay before treating a payment as successful.

For the exact authentication headers, checksum format, and required parameters, follow the documentation for each endpoint.

4. Before Going Live

Use this checklist before switching to Production:

• Payment initiation works in UAT.
• Customers can complete the bank payment flow.
• Callback requests are received and handled correctly.
• The customer return URL works as expected.
• Transaction statuses are verified before orders or invoices are updated.
• Production credentials and the Production base URL are configured securely.

Once these checks are complete, your integration is ready for Production deployment, subject to your merchant account's activation and configuration.