Recurring API
PayHere Recurring API lets you accept recurring payments from your customers so that the customer has to enter the card credentials only once & then his/her card will be automatically charged as per a time period you set & authorized by the customer.
It's a simple HTML Form based POST API (similar to PayHere Checkout API) which initiate a recurring payment request and redirect your customers to PayHere Payment Gateway to securely process & authorize the recurring payment. Once the first payment is processed & recurring payment is authorized, it notifies your given URL (notify_url
) about the payment status with a checksum to verify, everytime your customer's card is charged. You can use those response parameters & checksum to verify and update your system, based on the payment status.
Prerequisites
You need the following things ready to integrate your website with PayHere Recurring API.
- Merchant ID
- You can find your Merchant ID from Side Menu > Integrations of your PayHere Account.
- Merchant Secret
- You can generate a Merchant Secret for your domain/app by following below steps.
- Go to Side Menu > Integrations section of your PayHere Account
- Click 'Add Domain/App' > Enter your top level domain or App package name > Click 'Request to Allow'
- Wait for the approval for your domain/app (This will take up to 24 hours)
- Copy the Merchant Secret shown in front of your domain/app
- You can generate a Merchant Secret for your domain/app by following below steps.
Attention: Please note that Merchant ID is unique to your PayHere account, but Merchant Secret is specific to your integrating domain/app. Therefore, you need to add your new domains/apps & get a new Merchant Secret every time you're integrating PayHere on a new domain/app.
Integration
You need to complete the following 3 steps in order to fully integrate your website with PayHere Recurring API.
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) & securely process the payment there.
Action URL
Live - https://www.payhere.lk/pay/checkout
Sandbox - https://sandbox.payhere.lk/pay/checkout
Required POST Parameters
merchant_id
- PayHere Merchant IDreturn_url
- URL to redirect users when successcancel_url
- URL to redirect users when cancellednotify_url
- URL to callback the status of the paymentfirst_name
- Customer’s First Namelast_name
- Customer’s Last Nameemail
- Customer’s Emailphone
- Customer’s Phone Noaddress
- Customer’s Address Line1 + Line2city
- Customer’s Citycountry
- Customer’s Countryorder_id
- Order ID generated by the merchantitems
- Item title or Order/Invoice numbercurrency
- Currency Code (LKR/USD)recurrence
- Recurring Period (A number & a word separated by a space such as 2 Week, 1 Month, 6 Month, 1 Year, etc. Word can be ‘Week’, ‘Month’ or ‘Year’ in singular. Number can be any to define recurrent period with word.)duration
- Duration to charge ('Forever' if there's no time limitation. Otherwise a Number & a word separated by a space as 1 Month, 1 Year, 3 Year, ect. Word can be ‘Week’, ‘Month’, ‘Year’. Number should be compatible with the word in recurrence.)amount
- Total Payment Amount (eg. 1000.00)hash
- Generated hash value as mentioned below (*Required from 2023-01-16)
Generating 'hash' Value
You can generate the hash
value using the merchant_id
, order_id
, amount
, currency
and the merchant_secret
.
hash = to_upper_case(md5(merchant_id + order_id + amount + currency + to_upper_case(md5(merchant_secret))))
PHP Code sample for generating hash
value:
$hash = strtoupper(
md5(
$merchant_id .
$order_id .
number_format($amount, 2, '.', '') .
$currency .
strtoupper(md5($merchant_secret))
)
);
Attention:
Please note that the hash
parameter should not be generated in client-side since it will expose your merchant_secret
.
Optional POST Parameters
delivery_address
- Delivery Address Line1 + Line2delivery_city
- Delivery Citydelivery_country
- Delivery Countryitem_name_1
- Name of Item 1item_number_1
- Model number of Item 1amount_1
- Unit amount of Item 1quantity_1
- Quantity of Item 1item_name_2
- Name of Item 2item_number_2
- Model number of Item 2amount_2
- Unit amount of Item 2quantity_2
- Quantity of Item 2
(You can list rest of the items also like this)platform
- Referring Platformcustom_1
- Custom param 1 set by merchantcustom_2
- Custom param 2 set by merchantstartup_fee
- Additional fee or discount in 1st payment occurance
Code Sample
<html>
<body>
<form method="post" action="https://sandbox.payhere.lk/pay/checkout">
<input type="hidden" name="merchant_id" value="121XXXX"> <!-- Replace your Merchant ID -->
<input type="hidden" name="return_url" value="http://sample.com/return">
<input type="hidden" name="cancel_url" value="http://sample.com/cancel">
<input type="hidden" name="notify_url" value="http://sample.com/notify">
<br><br>Item Details<br>
<input type="text" name="order_id" value="ItemNo12345">
<input type="text" name="items" value="Door bell wireless"><br>
<input type="text" name="currency" value="LKR">
<input type="text" name="recurrence" value="1 Month">
<input type="text" name="duration" value="Forever">
<input type="text" name="amount" value="1000">
<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">
<input type="hidden" name="hash" value="098F6BCD4621D373CADE4E832627B4F6"> <!-- Replace with generated hash -->
<input type="submit" value="Buy Now">
</form>
</body>
</html>
2. Listening to Payment Notification
As soon as the payment is processed, PayHere notifies the payment status to the notify_url
you posted to the Checkout API as a server callback & redirects the customer back to your website to the return_url
. Payment 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 merchantorder_id
- Order ID sent by Merchant to Checkout pagepayment_id
- Unique Payment ID generated by PayHere for the processed paymentsubscription_id
- Unique Subscription ID generated by PayHere for the authorized subscriptionpayhere_amount
- Total Amount of the paymentpayhere_currency
- Currency code of the payment (LKR/USD)status_code
- Payment status code (2
,0
,-1
,-2
,-3
)md5sig
- Encrypted signature to verify the paymentcustom_1
- Custom param 1 sent by merchant to Checkout pagecustom_2
- Custom param 2 sent by merchant to Checkout pagemethod
- Payment method selected by the customer. (VISA
,MASTER
)status_message
- Message received from payment gateway which the customer tried to payrecurring
- Whether payment is a recurring payment (1:recurring, 0: not-recurring)message_type
- Status message (AUTHORIZATION_SUCCESS, AUTHORIZATION_FAILED, RECURRING_INSTALLMENT_SUCCESS, RECURRING_INSTALLMENT_FAILED, RECURRING_COMPLETE, RECURRING_STOPPED)item_recurrence
- How often it charges. eg. 1 Monthitem_duration
- How long it charges. eg. 1 Yearitem_rec_status
- Status of recurring subscription. (0: active, -1: cancelled, 1: completed)item_rec_date_next
- Date of next recurring installment (YYYY-MM-DD)item_rec_install_paid
- Number of successful recurring installments charged
If the customer made the payment byVISA
orMASTER
credit/debit card, following parameters will also be available.card_holder_name
- Card Holder Namecard_no
- Masked card number (Ex:************4564
)card_expiry
- Card expiry in format MMYY (Ex:0122
)
Payment Status Codes
2
- success0
- pending-1
- canceled-2
- failed-3
- chargedback
Attention:
- You cannot test the payment 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 payment 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 onnotify_url
& then show the payment status to your customer in the page onreturn_url
by fetching the status from your database. - The request parameters are encoded in the
'application/x-www-form-urlencoded'
format, not'application/json'
.
3. Verifying the Payment Status
It is critical to verify the Payment Notification before taking any actions on the payment response. You can do the verification using the md5sig
checksum parameter that is generated & sent by PayHere along with the payment status params according to following logic.
md5sig = strtoupper(
md5 (
merchant_id +
order_id +
payhere_amount +
payhere_currency +
status_code +
strtoupper(md5(merchant_secret))
)
)
Once you receive the payment status parameters from PayHere, you can locally generate this checksum using the merchant_id
, order_id
, payhere_amount
, payhere_currency
& status_code
sent by the payment notification and the merchant_secret
you have locally. Your locally generated checksum should be equal to the md5sig
sent by PayHere if the payment notification is valid.
Code Sample (PHP)
You can host this script at your notify_url
.
<?php
$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'];
$merchant_secret = 'XXXXXXXXXXXXX'; // Replace with your Merchant Secret
$local_md5sig = strtoupper(
md5(
$merchant_id .
$order_id .
$payhere_amount .
$payhere_currency .
$status_code .
strtoupper(md5($merchant_secret))
)
);
if (($local_md5sig === $md5sig) AND ($status_code == 2) ){
//TODO: Update your database as payment success
}
?>
Attention:
- Please make sure to consider the payment as successful only after the verfification, as it ensures that the payment notification received to your
notify_url
was genuinely initiated by PayHere, not by any other party. - If you do not implement this payment verification properly, there's a security risk of a third party sending a manipulated payment notification to your
notify_url
, falsly notifing that the payment is successful.