How to Take PayHere Payments with Gravity Forms in Sri Lanka

If you sell classes, courses, event tickets, services or products in Sri Lanka, PayHere is probably already on your list. It lets your customers pay online with the cards, wallets and online banking they use every day, on one checkout page. Gravity Forms is the form builder many WordPress sites use for bookings, registrations, orders and donations. This tutorial shows how to connect the two, so that every form submission becomes a PayHere payment for the exact form total, and every payment is confirmed by PayHere before your team treats it as paid.

We use the Gravity Forms PayHere Premium Add-on, a plugin that builds the PayHere checkout on your own server and talks to the PayHere Merchant API. It takes about twenty minutes from installing the plugin to your first test payment with a sandbox account.

Why take PayHere payments through Gravity Forms?

Many small businesses start by collecting payments by hand: someone fills in a booking form, a team member sends bank details over chat or email, the customer pays and sends a photo of the slip, and somebody checks the account later to see whether the money really arrived. That works for a few orders a week, but it is slow for customers, hard to match up, and easy to get wrong when the numbers grow.

With the form and the payment joined together, the customer pays straight after submitting, the amount always matches what they chose in the form, and the entry in Gravity Forms shows the payment status, the PayHere payment ID and any refunds. Your notification emails can wait until the payment is confirmed, so nobody starts work on an unpaid booking, and your accounts team can match every entry with the PayHere payment by its order ID.

How the payment works

• The customer fills in your form and sees the total in rupees, for example Rs 2,450.00.
• When they submit, your server saves the order with the entry and the browser is sent straight to the PayHere checkout page with that exact total.
• They pay there with a card, a wallet or online banking, whatever you have switched on for your account. Card numbers and banking logins are entered at PayHere, never on your site.
• They come back to your form page, and the plugin asks PayHere for the payment before it shows your thank-you message.

Forms that work well with PayHere

• Class, course and workshop bookings with a fixed price per seat.
• Event and seminar registrations with ticket types and quantities.
• Service deposits, for example for a consultation, a repair or a photo shoot.
• Simple product orders where a full online shop would be too much.
• Donations, admission fees and membership fees with a chosen amount.

What you need

• WordPress with Gravity Forms 2.9 or newer.
• A PayHere sandbox account for testing, and for live payments an approved PayHere merchant account.
• From each account: the merchant ID, the merchant secret PayHere shows after you add your website’s domain, and the app ID and app secret of a business app with the Payment Retrieval and Refund permissions.
• A site PayHere can reach from the internet, so it can send payment notifications to it.

Rupees in Gravity Forms

One detail is easy to miss. Gravity Forms does not list the Sri Lankan rupee by default. A site that sets a price of 950 in a currency Gravity Forms does not know can show odd totals or read amounts wrongly when the form is submitted. The plugin adds the rupee, with the Rs sign and two decimals, to the Gravity Forms currency list as soon as it is active, so the total on the form, the amount sent to PayHere and the amount on the entry are the same number, to the cent.

You can also run forms in US dollars, pounds, euros or Australian dollars if your PayHere plan accepts them; some plans take rupees and dollars only. The plugin checks every payment in the currency of your form, so a $19.99 form is confirmed as $19.99.

Step 1: Get your PayHere credentials

1. Sign up for a PayHere sandbox account (or log in to your live account later).
2. Note your merchant ID.
3. Add the domain of your website in the domains and credentials part of your account. PayHere shows a merchant secret for that domain. Copy it; it only works for that domain.
4. Under API keys, create a business app, tick the Payment Retrieval and Refund permissions, and copy the app ID and the app secret.

Why two sets? The merchant secret signs the checkout and the payment notifications. The business app lets the plugin ask PayHere directly about each payment, which is how it makes sure a payment really happened before an entry is marked paid.

Step 2: Install the add-on and connect your account

1. Upload and activate the plugin, then activate your licence key in Forms → Settings → PayHere.
2. Leave the mode on Test.
3. Enter the sandbox merchant ID, merchant secret, app ID and app secret and save. The plugin checks the app credentials with PayHere with a request that changes nothing, stores both secrets encrypted and only ever shows their first and last four characters.
4. In Forms → Settings, set the Gravity Forms currency to Sri Lankan Rupee.

Step 3: Payment notifications

The notification is how PayHere tells your site that a payment went through, even if the customer closes the browser right after paying. The plugin sends its notify address with every checkout, so it works without extra setup. You will find the address on the Notifications line of the settings. If your hosting has a firewall, make sure the PayHere servers can reach your site.

Every notification is checked against your merchant ID and merchant secret. A notification with a wrong or missing signature is refused, and a correct one is only a signal: the plugin still asks PayHere about the payment before it changes anything.

Step 4: Build the form

Create the form as usual. Add a name field, an email field, a phone field, an address and a city field, your product fields and a total field. PayHere asks for the customer’s first and last name, email and phone on every checkout, so make those fields required. Prices follow the Gravity Forms currency, so a class at 950 rupees shows as Rs 950.00. Gravity Forms works out the total in the browser for the customer and again on your server when the form is submitted; the plugin always uses the server total.

Step 5: Add a PayHere feed

Open the form settings, choose PayHere and add a feed. Pick Products and Services (or Donations), map the first name, last name, email and phone to your fields, and the address, city and country if your form has them. Write a description such as “Pottery class #{entry_id}”. The description is the items text the customer sees on the checkout page and you see for the payment in your PayHere account. Keep “Send form notifications only after the customer has paid” ticked if your team should only hear about paid bookings.

Step 6: Test with your sandbox account

Open your form, fill it in and submit. You land on the PayHere sandbox checkout page. Pay with one of the PayHere test cards and you come back to your form page with the thank-you message. In Forms → Entries, the entry shows Paid, the PayHere payment ID and a note that it was a test payment. Try a partial refund from the PayHere box on the entry to see how refunds are recorded. Then start another payment and cancel it on the checkout page: the customer is told nothing was charged.

What happens behind the scenes

1. The form is checked on the server: the currency must be one PayHere takes, the total must have no more than two decimals and be within the limits, and the email and phone must be filled in.
2. The order is saved with the entry: a unique order ID, the exact amount, the currency and the mode.
3. The browser goes to a signed page of your site that builds the PayHere checkout form from the saved entry only, signs it with your merchant secret and sends it on to PayHere. Nothing the browser sends can change the amount, the currency or the order ID.
4. When the customer returns, when a notification arrives and every five minutes, the plugin asks PayHere for the payments of the order ID with the Retrieval API.
5. Only a payment PayHere reports as received, with your order ID, the entry amount and the entry currency, marks the entry Paid. Anything else is noted and left for you to check.

A worked example

A pottery studio in Kandy sells a two-hour wheel class at Rs 950.00 and a glaze and firing kit at Rs 550.00. A customer books two classes and one kit. The form shows Rs 2,450.00. On submit, the plugin saves order GF5c2e1ax1042x7k2m9q for 2450.00 LKR with the items text “Pottery class #1042” and sends the customer to the PayHere checkout page. The customer pays with a card. The notification arrives a few seconds later; its signature is valid, so the plugin asks PayHere about the order: one payment, received, 2450.00 LKR. The entry becomes Paid, the held booking email goes out, and the PayHere payment ID is stored on the entry. The next week the customer cancels one class, and the studio refunds 950.00 rupees from the entry. PayHere accepts the refund, it is recorded once, and the entry stays Paid with 1,500.00 rupees left.

How it differs

• It connects to your own PayHere account directly, so PayHere settles the money to you under your own merchant agreement, and the checkout page shows every method you have switched on.
• The checkout form is built on your server from the saved entry: the amount, the currency, the order ID and the signature never come from the browser, so a changed page cannot change what is charged.
• It never trusts the notification or the return page on its own. The notification signature is checked with your merchant secret, and then the payment is read back from PayHere with the Retrieval API. Only a received payment with the entry’s order ID, amount and currency marks the entry Paid.
• It adds the Sri Lankan rupee to Gravity Forms, so a total of Rs 2,450.00 is shown, sent and stored as exactly 2450.00, never misread or rounded.
• Refunds, including several partial refunds of rupee payments, are made from the Gravity Forms entry and recorded once.

Tips for smooth payments

• Make the name, email and phone fields required: PayHere asks for them on every checkout.
• Ask for the phone number with the country code, for example +94 77 123 4567.
• Keep prices at two decimals, for example 950.00 rupees.
• Use a clear description with the entry number, so your team can find the payment in your PayHere account quickly.
• Check the Notifications line in the settings after your first payment: it shows when the last valid notification arrived.
• Use the merchant secret of the exact domain your forms run on; a staging site on another domain needs its own secret.

Step 7: Go live

When your tests look right, enter the live merchant ID, the merchant secret of your live domain, and the app ID and app secret of a live business app, switch the mode to Live and save. Make one small real payment and refund it. Each entry remembers whether it was paid in Test or Live, so older test entries keep working.

Questions

Do card details reach my website?

No. The customer enters them on the PayHere checkout page. Your site only receives the payment status from PayHere.

Which currencies can I use?

Sri Lankan rupees, and US dollars, pounds, euros and Australian dollars where your PayHere plan accepts them. The plugin adds the rupee to Gravity Forms.

What if the notification never arrives?

The plugin also checks the payment when the customer returns and every five minutes, so the entry is updated anyway.

Can I refund part of a payment?

Yes, several partial refunds of rupee payments up to the paid amount, from the entry screen. Payments in other currencies are refunded in full from the entry, or in part in your PayHere account.

Are recurring payments or saved cards supported?

Not in this version. The plugin handles one-off payments for products, services and donations.

Get started

Get the Gravity Forms PayHere Premium Add-on and follow the setup guide. Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year.