Preapproval API

PayHere Preapproval API allows you to get your customers preapproved for Automated Payments. It's a simple HTML form based POST API to redirect your customer to PayHere Payment Gateway to securely preapprove the future payments.

Once the preapproval is processed, it notifies your given URL (notify_url) about the preapproval status & the encrypted token for the customer's card by a server callback. You can fetch that encrypted token from the payment notification & store it in your database securely to programatically charge your customer later at anytime any amount on demand via PayHere Charging API.


You need your PayHere Merchant ID & Merchant Secret to integrate with Preapproval API.

  • Merchant ID can be found at Integrations (or Settings > Domains & Credentials in old portal)
  • Merchant Secret can be generated for your domain/app as follows
    1. Go to Integrations (or Settings > Domains & Credentials in old portal)
    2. Click 'Add Domain/App' > Fill details > Click 'Request to Allow'
    3. Wait for the approval for your domain
    4. Copy the Merchant Secret for your domain/app

Note: Merchant Secrets are domain/app specific, therefore you need to generate a new Merchant Secret every time you're integrating PayHere on a new domain/app.

1. Redirecting Customer to PayHere Payment Gateway

Regardless of your scripting language, you can simply use an HTML Form to submit the below POST params to PayHere Payment Gateway. When the form is submitted, your customer will be securely redirected to the PayHere Payment Gateway & the customer can then enter the credentials (Card No / CVV) & securely process the preapproval there.

Action URL
Live    -
Sandbox -

Required POST Parameters
  • merchant_id - PayHere Merchant ID
  • return_url - URL to redirect users when success
  • cancel_url - URL to redirect users when cancelled
  • notify_url - URL to callback the status of the payment (Needs to be a URL accessible on a public IP/domain)
  • first_name - Customer’s First Name
  • last_name - Customer’s Last Name
  • email - Customer’s Email
  • phone - Customer’s Phone No
  • address - Customer’s Address Line1 + Line2
  • city - Customer’s City
  • country - Customer’s Country
  • order_id - Order ID generated by the merchant
  • items - Item title or Order number
  • currency - Currency Code (LKR/USD)

Optional POST Parameters

  • amount - Payment amount which need to capture as part of preapproval. This will process as a payment in addition to preapproval.
  • platform - Referring Platform
  • custom_1 - Custom param 1 set by merchant
  • custom_2 - Custom param 2 set by merchant
  • hash - Generated hash value to ensure extra security

If you need to add extra security when initializing the payment you can use hash parameter. Please note that this parameter should not be generated in client-side since it will expose your payhere_secret
The hash value can be generated in following manner

hash = to_upper_case( md5( merchant_id + order_id + payhere_amount + payhere_currency + to_upper_case( md5(payhere_secret) ) ) )

PHP Code sample for generating hash

md5sig = strtoupper (md5 ( merchant_id + order_id + payhere_amount + payhere_currency + strtoupper(md5(payhere_secret)) ) )

Code Sample
<form method="post" action="">   
    <input type="hidden" name="merchant_id" value="121XXXX">    <!-- Replace your Merchant ID -->
    <input type="hidden" name="return_url" value="">
    <input type="hidden" name="cancel_url" value="">
    <input type="hidden" name="notify_url" value="">  
    <input type="text" name="order_id" value="Preapproval12345">
    <input type="text" name="items" value="MyTaxi Hires"><br>
    <input type="text" name="currency" value="LKR">
    <br><br>Customer Details<br>
    <input type="text" name="first_name" value="Saman">
    <input type="text" name="last_name" value="Perera"><br>
    <input type="text" name="email" value="[email protected]">
    <input type="text" name="phone" value="0771234567"><br>
    <input type="text" name="address" value="No.1, Galle Road">
    <input type="text" name="city" value="Colombo">
    <input type="hidden" name="country" value="Sri Lanka"><br><br> 
    <input type="submit" value="Preapprove">   

2. Listening to Preapproval Notification

As soon as the preapproval is processed, PayHere notifies the preapproval status to the notify_url you posted to the Preapproval API as a server callback & redirects the customer back to your website to the return_url. Preapproval notification will contain the following data as POST params, so you need to host a script on your notify_url to fetch the following POST params & update your database accordingly.

POST params
  • merchant_id - PayHere Merchant ID of the merchant
  • order_id - Order ID sent by Merchant to Preapproval page
  • payment_id - Unique Payment ID generated by PayHere for the preapproval
  • payhere_amount - Total Amount of the payment
  • payhere_currency - Currency code of the payment (LKR/USD)
  • status_code - Payment status code (2, 0, -1, -2)
  • md5sig - Encrypted signature to verify the payment
  • status_message - Message received from payment gateway which the customer tried to pay
  • customer_token - Encrypted token for customer's card
  • custom_1 - Custom param 1 sent by merchant to Checkout page
  • custom_2 - Custom param 2 sent by merchant to Checkout page
  • method - Payment method selected by the customer. (VISA, MASTER)
  • card_holder_name - Card Holder Name
  • card_no - Masked card number (Ex: ************4564)
  • card_expiry - Card expiry in format MMYY (Ex: 0122)

Payment Status Codes

  • 2 - success
  • 0 - pending
  • -1 - canceled
  • -2 - failed

Please note that;

  • You cannot test the preapproval notification by print/echo methods since notify_url never loads to the browser as it's a server callback. You can only test it by updating your database upon fetching the notification.
  • You cannot test the preapproval notification on localhost. You need to submit a publically accessible IP or domain based URL as your notify_url for PayHere to directly notify your server.
  • No payment status parameters are passed to the return_url when redirecting the customer back to your website. You need to update your database upon fetching payment status by your script on notify_url & then show the preapproval status to your customer in the page on return_url by fetching the status from your database.

3. Verifying the Preapproval Notification

It is important to verify the Preapproval Notification before taking any actions on the preapproval response. You can do the verification using the md5sig checksum parameter that is generated & sent by PayHere along with the preapproval status params according to following logic.

md5sig = strtoupper(
    md5 (
        merchant_id + 
        order_id + 
        payhere_amount + 
        payhere_currency + 
        status_code + 

Once you receive the preapproval status params from PayHere, you can locally generate this checksum using the merchant_id, order_id, payhere_amount, payhere_currency & status_code sent by the preapproval notification and the payhere_secret you have locally (You can find your Merchant Secret in your PayHere Account's Settings page). Your locally generated checksum should equals to the md5sig sent by PayHere if the preapproval notification is valid.

Code Sample (PHP)

You can host this script at your notify_url.


$merchant_id        = $_POST['merchant_id'];
$order_id           = $_POST['order_id'];
$payhere_amount     = $_POST['payhere_amount'];
$payhere_currency   = $_POST['payhere_currency'];
$status_code        = $_POST['status_code'];
$md5sig             = $_POST['md5sig'];
$status_message     = $_POST['status_message'];
$customer_token     = $_POST['customer_token'];

$merchant_secret = 'XXXXXXXXXXXXX'; // Replace with your Merchant Secret (Can be found on your PayHere account's Settings page)

$local_md5sig = strtoupper(
        $merchant_id . 
        $order_id . 
        $payhere_amount . 
        $payhere_currency . 
        $status_code . 
if (($local_md5sig === $md5sig) AND ($status_code == 2) ){
        //TODO: Store the encrypted token ($customer_token) securely in your database against your customer

Preapproval API - PayHere Knowledge Base

Still need help? Get in touch!
Last updated on 5th May 2022