Gravity Forms HitPay Premium Add-on Setup Guide

The Gravity Forms HitPay Premium Add-on connects Gravity Forms to your own HitPay account in Singapore, Malaysia or the Philippines. When a form with a HitPay feed is submitted, the add-on creates a HitPay payment request for the exact total Gravity Forms calculated and sends the customer to the HitPay checkout, where they choose how to pay: a card, PayNow, FPX online banking, DuitNow, QR Ph or any other method active on your account. Payment details are entered at HitPay, never on your website.

When HitPay reports the payment, the add-on checks the webhook signature with your webhook salt, reads the payment request back from HitPay and only then marks the entry Paid, with the HitPay payment ID as the transaction ID. This guide covers installation, every setting, the webhook, the feed, what the customer sees, the payment statuses, refunds, testing in the sandbox 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 → HitPay and activate your licence key. The HitPay settings appear once the licence is active.
3. Set the Gravity Forms currency (Forms → Settings) to Singapore Dollar, Malaysian Ringgit or Philippine Peso, whichever your HitPay account settles in.

Updates are delivered from gravityextra.com like every GravityExtra add-on. The add-on keeps working if you rename its folder.

Currencies and amounts

The Singapore dollar, Malaysian ringgit and Philippine peso are built into Gravity Forms with two decimals, so prices such as $ 285.00, RM 1,250.00 or Php 1,250.00 are read correctly both in the browser and on the server. The add-on sends the total to HitPay as a decimal amount with two places, as HitPay asks: a total of $ 285.00 is sent as 285.00 SGD. Totals with more than two decimals, below 1.00 or in a currency that is not enabled are refused before anything is sent to HitPay.

If HitPay has enabled multi-currency card payments on your account, you can also take payments in US, Australian, New Zealand or Hong Kong dollars, Thai baht, euro, pound sterling or Canadian dollars: tick the currency in the settings and set the Gravity Forms currency to it. These are all built into Gravity Forms with two decimals as well. Currencies without decimals are not offered.

Settings

When you save, the add-on asks HitPay to confirm the API key of each mode (a read that changes nothing in your account). A key HitPay refuses is not saved, and the error tells you which mode to check. The webhook salt cannot be checked until HitPay sends a webhook: the settings page shows when the last webhook with a valid signature arrived.

The webhook

HitPay tells your site about payments with webhooks. Add one in the HitPay dashboard:

1. Open Developers → Webhook Endpoints and click New Webhook.
2. Enter a name and the webhook address shown in the add-on settings (https://your-site/?callback=gfhitpay).
3. Select the events payment_request.completed, payment_request.failed and charge.updated (the last one tells the add-on about refunds).
4. Save, open the webhook’s detail view, copy its salt and paste it into the webhook salt field of the same mode.

For each webhook the add-on:

1. limits how many webhooks one address can send per minute;
2. checks the Hitpay-Signature header, the HMAC-SHA256 of the raw message with your webhook salt, and refuses the webhook when it does not match;
3. finds the entry by the payment request ID it created, and checks that the salt belongs to the mode the payment was made in;
4. reads the payment request back from HitPay and only then changes the entry.

If HitPay cannot be read for a moment, the add-on answers with an error, so HitPay sends the webhook again later. A repeated webhook never completes a payment twice. Use a separate webhook with its own salt for the sandbox and for live.

The feed

Open the form, go to Settings → HitPay and add a feed:

• Transaction type: Products and Services, or Donations. The payment amount is usually the form total.
• Customer information: map the email field (required: HitPay sends its payment confirmation there). First name, last name and phone are optional; the phone is sent only when it was typed with its country code, such as +65 9123 4567.
• Purpose: shown with the payment on the HitPay checkout and in your dashboard. Merge tags work; the default is {form_title} #{entry_id}.
• Payment methods: leave empty to offer every method active on your account, or list HitPay method codes such as card, paynow_online for this form.
• Notifications: tick it to send the form notifications only after the customer has paid. Use the Payment Completed event for receipts.
• Conditional logic: as with any Gravity Forms payment feed.

What the customer sees

The customer fills in the form and clicks the submit button. The add-on creates the payment request and sends them to the HitPay checkout, where they pick a payment method and pay. HitPay then sends them back to the form page. The add-on reads the payment request from HitPay and shows your confirmation as soon as the payment is confirmed. If a payment needs a moment, the page shows “Confirming your payment” and checks again by itself every few seconds. If the customer cancelled, the page says no payment was received and that they have not been charged, with a link back to the form.

Payment statuses

The entry screen

Every entry paid through HitPay has a HitPay box with the status, the amount, the HitPay payment ID, the payment method, the payment request ID, the reference and any refunds. Sandbox payments carry a “Sandbox — test payment” badge. Refresh status reads the payment request and its refunds from HitPay again. Each step is also written to the entry notes.

Refunds

On a paid entry, type the amount in the refund field and click Refund with HitPay. Amounts can be typed as 50.00, 1,250.00 or 1250. The add-on first reads the payment request from HitPay to make sure the payment is completed with the entry amount, then sends the refund. When HitPay answers that the refund succeeded, it is recorded at once; otherwise the entry shows “Refund requested” until HitPay confirms it. Several partial refunds are possible up to the paid amount; when they add up to the whole amount the entry becomes Refunded.

• A refund form can be used once, so a double click or a resubmitted page cannot refund twice.
• If HitPay does not answer, the request stays reserved (“do not refund again”). The status check records it when HitPay shows the refunded amount, or frees it after an hour with a note.
• Refunds made in the HitPay dashboard are recorded from the charge.updated webhook or when you click Refresh status.
• Staff need the Gravity Forms “edit entries” permission; administrators always can.

Testing in the sandbox

1. Create an account on the HitPay sandbox dashboard, then copy the sandbox API key from Settings → API Keys.
2. In the sandbox dashboard, add a webhook endpoint with the webhook address from the add-on settings and copy its salt.
3. Keep the mode on Sandbox, paste the API key and the salt and save. The connection line should say “Connected to HitPay (Sandbox)”.
4. Add a feed, open the form on a page that HitPay can reach over the internet and pay a small amount with a sandbox test card or the sandbox PayNow QR.
5. Check that the entry becomes Paid, the payment ID appears in the HitPay box and the settings page shows the last webhook. Then make a partial refund.

Going live

• Copy the live API key from your live HitPay dashboard, add a live webhook endpoint with the same address and copy its salt.
• Paste both into the Live fields and switch the mode to Live.
• Make sure the site uses https and is reachable from the internet, so HitPay can send its webhooks.
• Make one small real payment and refund it to confirm everything end to end.
• Entries started in the sandbox keep using the sandbox key and salt, so switching modes never mixes the two.

For developers

The filter gravityextra_hitpay_request_fields can change the purpose, the customer name, email and phone, the payment methods, the expiry of the payment link (expires_after, for example 30 mins) and whether HitPay sends its own email or SMS receipt (send_email, send_sms). The amount, currency, reference, return address and the single-payment setting are always set by the add-on. Other filters: gravityextra_hitpay_max_cents (lower the largest payment), gravityextra_hitpay_rate_limit, gravityextra_hitpay_payments_per_hour and gravityextra_hitpay_notify_base (the base of the webhook address, for sites behind a proxy).

// Give customers of one form (ID 7) 30 minutes to pay and let HitPay email them a receipt.
// The amount, currency, reference and return address cannot be changed here.
add_filter( 'gravityextra_hitpay_request_fields', function ( $fields, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $fields;
    }
    $fields['expires_after'] = '30 mins';
    $fields['send_email']    = 'true';
    $fields['purpose']       = 'Class ' . rgar( $entry, '8' ) . ' / booking ' . rgar( $entry, 'id' );
    return $fields;
}, 10, 4 );

How it differs

• It connects to your own HitPay account directly with the HitPay payment request API, so the money is settled by HitPay to your account under your own HitPay agreement, and the checkout shows every method you have switched on there.
• It never trusts the return address or the webhook body on its own. The webhook signature is checked with your salt, and then the payment request is read back from HitPay. Only a completed request with a payment of the entry’s amount and currency marks the entry Paid.
• It uses HitPay’s current dashboard webhooks with the signature in the Hitpay-Signature header, not the older per-request webhook parameter that HitPay has deprecated.
• Refunds, including several partial refunds, are made from the Gravity Forms entry and recorded once, together with refunds you make in the HitPay dashboard.

Troubleshooting

Uninstall

Uninstalling from Forms → Settings → Uninstall, or deleting the plugin, removes the settings (including the encrypted key and salt), the schedule, locks, counters and cached checks. Entries, their notes and the payments at HitPay are kept.

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