Gravity Forms PayHere Premium Add-on Setup Guide

The Gravity Forms PayHere Premium Add-on connects Gravity Forms to your own PayHere account in Sri Lanka. When a form with a PayHere feed is submitted, the add-on saves the exact total Gravity Forms calculated with the entry and sends the customer to the PayHere checkout page, where they pay with a card, a wallet or online banking, whatever is active on your account. Payment details are entered at PayHere, never on your website.

When PayHere reports the payment, the add-on checks the notification signature with your merchant secret, reads the payment back with the PayHere Retrieval API and only then marks the entry Paid, with the PayHere payment ID as the transaction ID. This guide covers installation, currencies, every setting, payment notifications, the feed, what the customer sees, the payment statuses, refunds, testing with a sandbox account and going live.

Installation

1. Download the add-on zip from your GravityExtra account and upload it in Plugins → Add New → Upload Plugin, then activate it.
2. Open Forms → Settings → PayHere and activate your licence key. The PayHere settings appear once the licence is active.
3. In Forms → Settings, set the Gravity Forms currency to Sri Lankan Rupee (or one of the other currencies below).

What you need from PayHere

The add-on uses two sets of credentials for each mode, and both come from your PayHere account (the sandbox account for Test, the live account for Live):

1. Merchant ID and merchant secret. Your merchant ID is shown in your PayHere account. Add this website’s domain under the domains and credentials (integrations) part of your account; PayHere then shows a merchant secret for that domain. The secret is tied to the domain, so a secret made for another site does not work here.
2. App ID and app secret. Create a business app under API keys and give it the Payment Retrieval permission and the Refund permission. PayHere shows an app ID and an app secret. The add-on uses them to ask PayHere about each payment and to make refunds. For live use, PayHere may ask you to add your domain and the public IP address of your server to the app first.

Currencies and amounts

Gravity Forms does not include the Sri Lankan rupee out of the box. The add-on adds it to the Gravity Forms currency list as soon as it is active, with the Rs sign and two decimals, and never changes a currency that another plugin already defined. PayHere also takes US dollars, pounds, euros and Australian dollars, depending on your PayHere plan; some plans take rupees and dollars only.

The amount is worked out on your server from the entry, never from the browser. A total with more than two decimals is refused before the customer leaves the form, so nobody is charged a rounded amount. Payments go from 1.00 to 10,000,000.00; a filter can lower the largest amount, and PayHere applies its own limits to your account.

Settings

Payment notifications

PayHere tells your site about payments with a notification: a signed message posted to your site’s notify address. The add-on sends its notify address with every checkout, so there is nothing to set up for it to work. The address ends in /wp-json/gravityextra-payhere/v1/notify and is shown on the Notifications line of the settings.

Each notification is checked before anything happens: the merchant ID must be yours and the md5sig signature must match the order ID, amount, currency and status, signed with your merchant secret. The order must be one this site started in the same mode. Then the add-on reads the payment back from PayHere. A notification that arrives twice is acknowledged without changing the entry again. If the read-back fails, the add-on answers with an error and the five-minute status check picks the payment up.

The feed

• Transaction type: Products and Services, or Donations. The payment amount is the form total or one product field.
• First name, last name, email and phone are required by PayHere: map them to your form fields. Address, city and country are optional; PayHere asks for them on every checkout, so empty ones are sent as “N/A” (and Sri Lanka for the country).
• Description: the items text the customer sees on the PayHere checkout page and you see in your PayHere account (merge tags work).
• Notifications: hold the form notifications until the customer has paid (on by default).

What the customer sees

The customer fills in the form and sees the total, for example Rs 2,450.00. After pressing the submit button they go straight to the PayHere checkout page and choose a card, a wallet or online banking. After paying they come back to your form page, where the add-on reads the payment from PayHere and shows your confirmation. If they cancel, they see that nothing was charged and can return to the form.

Payment statuses

The entry screen

The PayHere box on the entry shows the status, the amount, the PayHere payment ID, the payment method, your order ID and the last status PayHere reported. Refresh status reads the payment from PayHere again. Test payments carry a “Test — test payment” badge. If PayHere reports a chargeback or shows a refund you made in your PayHere account, the entry gets a note so you can check it. Users need the Gravity Forms capability to edit entries (administrators always can) to see the buttons.

Refunds

• Type the amount in the refund field of a paid entry and press Refund with PayHere. The full remaining amount is filled in for you.
• The add-on reads the payment back first, then sends the refund to the PayHere Refund API and records it as soon as PayHere accepts it. PayHere then processes the refund to the customer.
• Rupee payments can be refunded in part, several times, up to the paid amount. Payments in other currencies are refunded in full from the entry; make partial refunds of those in your PayHere account.
• When the whole amount is refunded, the entry becomes Refunded.
• If PayHere does not answer a refund request, the request stays reserved: check your PayHere account, then use Release the unanswered refund request if no refund was made.
• Refunds you make in your PayHere account are not added to the entry automatically; the entry gets a note when PayHere shows the payment as refunded.

Testing with a sandbox account

1. Sign up for a PayHere sandbox account, add your site’s domain to get a merchant secret, and create a business app with the Payment Retrieval and Refund permissions.
2. Keep the add-on in Test mode, enter the sandbox merchant ID, merchant secret, app ID and app secret and save. The connection line turns green.
3. Submit your form and pay on the sandbox checkout page with a PayHere test card.
4. Check the entry: Paid, with the payment ID and a “Test — test payment” note. Try a partial refund.
5. Start another payment and cancel it on the checkout page: the customer sees that nothing was charged.

Going live

• 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 to Live and save.
• Make one small real payment and refund it.
• Your site must be reachable from the internet for live payment notifications.

For developers

The filter gravityextra_payhere_request_fields can change the customer fields and the items text. The amount, the currency, the order ID, the merchant ID, the hash and the return, cancel and notify addresses are always set by the add-on. gravityextra_payhere_max_minor lowers the largest payment and gravityextra_payhere_payments_per_hour changes the hourly cap of new payments (300 by default).

// Put the class date in the items text of one form (ID 7).
// The amount, currency, order ID, merchant ID, hash and the addresses cannot be changed here.
add_filter( 'gravityextra_payhere_request_fields', function ( $fields, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $fields;
    }
    $fields['items'] = 'Class ' . rgar( $entry, '9' ) . ' / booking ' . rgar( $entry, 'id' );
    return $fields;
}, 10, 4 );

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.

Troubleshooting

Uninstall

Deleting the add-on from the Plugins screen removes its settings (including the encrypted secrets), schedules and temporary data. Entries, notes and payments at PayHere stay as they are.

Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year. See the Gravity Forms PayHere Premium Add-on page for details.