Authorize API
PayHere Authorize API allows you to get your customer authorization for Hold on Card payments. It's a simple HTML form based POST API to redirect your customer to PayHere Payment Gateway to securely authorize Hold on Card payments.
Once the payment is authorized, it notifies your given URL (notify_url) about the authorization status & an authorization token for the particular payment by a server callback. You can fetch that authorization token from the notification & store it in your database securely to programmatically capture the authorized or lesser amount later via PayHere Capture API.
Prerequisites
You need your PayHere Merchant ID & Merchant Secret to integrate with Authorize 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
- Go to Integrations (or Settings > Domains & Credentials in old portal)
- Click 'Add Domain/App' > Fill details > Click 'Request to Allow'
- Wait for the approval for your domain
- 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 authorization there.
Action URL
Live - https://www.payhere.lk/pay/authorize
Sandbox - https://sandbox.payhere.lk/pay/authorize
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 authorization (Needs to be a URL accessible on a public IP/domain)first_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 numbercurrency
- Currency Code (LKR/USD)amount
- Total Payment Amount
Optional POST Parameters
platform
- Referring Platformcustom_1
- Custom param 1 set by merchantcustom_2
- Custom param 2 set by merchanthash
- Generated hash value to ensure extra security
If you need to add extra security when initializing the authorization 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
<html>
<body>
<form method="post" action="https://sandbox.payhere.lk/pay/authorize">
<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">
<input type="text" name="order_id" value="Order12345">
<input type="text" name="items" value="Toy car"><br>
<input type="text" name="currency" value="LKR">
<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"><br><br>
<input type="submit" value="Authorize">
</form>
</body>
</html>
2. Listening to Authorization Notification
As soon as the authorization is processed, PayHere notifies the authorization status to the notify_url
you posted to the Authorize API as a server callback & redirects the customer back to your website to the return_url
. Authorization 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 Merchantpayhere_amount
- Total Amount of the paymentpayhere_currency
- Currency code of the payment (LKR/USD)status_code
- Payment status code (3
,0
,-1
,-2
)md5sig
- Encrypted signature to verify the paymentstatus_message
- Message received from payment gateway which the customer tried to payauthorization_token
- Authorization token for the ordercustom_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
)card_holder_name
- Card Holder Namecard_no
- Masked card number (Ex:************4564
)card_expiry
- Card expiry in format MMYY (Ex:0122
)
Authorization Status Codes
3
- authorization success0
- pending-1
- canceled-2
- failed
Please note that;
- You cannot test the authorization 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 authorization notification on localhost. You need to submit a publicly 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 authorization status to your customer in the page onreturn_url
by fetching the status from your database.
3. Verifying the Authorization Notification
It is important to verify the Authorization Notification before taking any actions on the authorization response. You can do the verification using the md5sig
checksum parameter that is generated & sent by PayHere along with the 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 authorization 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 authorization 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 authorization 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'];
$status_message = $_POST['status_message'];
$authorization_token = $_POST['authorization_token'];
$merchant_secret = 'XXXXXXXXXXXXX'; // Replace with your Merchant Secret (Can be found on your PayHere account's Settings page)
$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: Store the encrypted token ($authorization_token) securely in your database against your customer
}
?>