PayHere Checkout

PayHere Checkout lets you integrate PayHere with your website, mobile app or any other application in code level. It offers a simple form POST method to initiate a payment request and redirect your customers to PayHere Payment Gateway to securely process the payment. Once the payment is processed it notifies your given URL about the payment status also with a checksum to verify the response params. You can use those response params & checksum to verify and update your system, based on the payment status.

Action URL
  • Live - https://www.payhere.lk/pay/checkout

  • Sandbox - https://sandbox.payhere.lk/pay/checkout


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
  • 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 - Items & Quantities in one line (eg. iphone, ipad)
  • currency - Currency Code (LKR/USD)
  • amount - Total Payment Amount

Optional POST Parameters

  • delivery_address - Delivery Address Line1 + Line2
  • delivery_city - Delivery City
  • delivery_country - Delivery Country
  • item_name_1 - Name of Item 1
  • item_number_1 - Model number of Item 1
  • amount_1 - Unit amount of Item 1
  • quantity_1 - Quantity of Item 1
  • item_name_2 - Name of Item 2
  • item_number_2 - Model number of Item 2
  • amount_2 - Unit amount of Item 2
  • quantity_2 - Quantity of Item 2
    (You can list rest of the items also like this)
  • platform - Referring Platform
  • custom_1 - Custom param 1 set by merchant
  • custom_2 - Custom param 2 set by merchant


Listening to Payment Notification

Once the payment is processed, PayHere will notify the payment status to the notify_url you posted to the Checkout API. Payment status will contain the following data as POST params. So you need to make sure the notify_url you set, support accepting these params on a POST request.

POST params
  • merchant_id - PayHere Merchant ID of the merchant
  • order_id - Order ID sent by Merchant to Checkout page
  • payment_id - Unique Payment ID generated by PayHere for the processed payment
  • 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, -3)
  • md5sig - Encrypted signature to verify the payment
  • custom_1 - Custom param 1 sent by merchant to Checkout page
  • custom_2 - Custom param 2 sent by merchant to Checkout page

Payment Status Codes

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


Verifying the Payment Notification

It is important 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(payhere_secret)) ) )

Once you receive the payment 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 payment notification and the payhere_secret you have locally. Your locally generated checksum should equals to the md5sig sent by PayHere if the payment notification is valid.

Still need help? Get in touch!
Last updated on 15th Jul 2016