How to Take HitPay Payments with Gravity Forms (PayNow, FPX, QR Ph, Cards)

Customers in Singapore, Malaysia and the Philippines expect to pay the way they pay everywhere else: scan a PayNow or QR Ph code with their banking app, pick their bank for an FPX transfer, use DuitNow, or simply pay by card. HitPay brings these methods together on one checkout for small and growing businesses. If you take bookings, orders, registrations or donations with Gravity Forms, you can offer that checkout without building a shop. This guide shows how to take HitPay payments with Gravity Forms step by step, from the keys in the HitPay dashboard to the first confirmed payment and a refund.

Why take HitPay payments through Gravity Forms?

Gravity Forms already works out prices, quantities, options and totals. What it needs is a safe way to collect the money and to know for sure when a payment has arrived. With a HitPay feed, the form becomes the order page: the customer fills it in, pays on the HitPay checkout, and the entry is marked Paid only after the payment has been read back from HitPay. Notifications to you and to the customer can wait until then, so nobody receives a “booking confirmed” email for an unpaid booking.

Because the payment happens on the HitPay checkout, card numbers and bank logins never pass through your website. Your site only sends the order (amount, currency, purpose, the customer’s email) and receives the result.

Ways your customers can pay

• Cards: Visa, Mastercard and American Express, plus wallets such as Apple Pay where HitPay offers them in your market.
• PayNow in Singapore: the customer scans a QR code with any banking app.
• FPX online banking and DuitNow in Malaysia.
• QR Ph and InstaPay in the Philippines.
• Other local methods you switch on in the HitPay dashboard.

Which methods appear depends on your HitPay account and your market. The add-on simply sends the customer to the checkout with the right amount and lets HitPay show what you offer. If one form should only offer some of them, list their HitPay codes in the feed.

Forms that work well with HitPay

• Class, workshop and event bookings with a fixed price per place.
• Small shops and pre-orders where a full shop would be too much.
• Membership fees, course registrations and application fees.
• Donations and fundraising forms.
• Deposits for services such as photography, tours, renovation or tuition.

What you need

• WordPress with Gravity Forms 2.9 or newer.
• The Gravity Forms HitPay Premium Add-on (one site $49 a year, five sites $69 a year, unlimited sites $199 a year).
• A HitPay account. For testing, a separate sandbox account on the HitPay sandbox dashboard.
• Your API key (Settings → API Keys) and the salt of the webhook you add under Developers → Webhook Endpoints.
• An https site that HitPay can reach, so it can send its webhooks.

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

Install and activate the add-on, then activate your licence key in Forms → Settings → HitPay. Leave the mode on Sandbox, paste the sandbox API key and save. The add-on asks HitPay to confirm the key (a read that changes nothing) and shows “Connected to HitPay (Sandbox)” with the key masked. The key is stored encrypted in your database.

Next, copy the webhook address from the settings page. In the HitPay dashboard, open Developers → Webhook Endpoints, add a webhook with that address, select payment_request.completed, payment_request.failed and charge.updated, and copy the webhook’s salt into the webhook salt field.

Set the Gravity Forms currency to Singapore Dollar, Malaysian Ringgit or Philippine Peso. If HitPay has enabled card payments in other currencies on your account, tick them in the add-on settings and you can price a form in US dollars, euro or another of those currencies instead.

Step 2: Build the form

Create the form as usual with Product fields (or a single product with a quantity), a Total field, and the customer’s name, email and phone. The email field matters: HitPay sends the payment confirmation there. Use the international phone format so the number reaches HitPay with its country code. Gravity Forms shows the prices in your currency, for example $ 120.00, and calculates the total as the customer changes quantities.

Step 3: Add a HitPay feed

In the form settings, open HitPay and add a feed. Choose Products and Services (or Donations), keep the form total as the payment amount, map the email, name and phone fields, and write a purpose such as {form_title} #{entry_id}, which you will see next to the payment in the HitPay dashboard. Leave the payment methods empty to offer everything on your account. Tick “Send form notifications only after the customer has paid” so confirmation emails go out only for paid entries.

Step 4: Test in the sandbox

Open the form on a public page and submit it. You are taken to the HitPay sandbox checkout, where you can pay with a test card or by scanning the sandbox PayNow QR code. Back on your site, the page shows your confirmation message as soon as the payment is confirmed. In the entry, the HitPay box shows Paid, the HitPay payment ID and the payment method. Try a partial refund too: it is recorded in the notes as soon as HitPay confirms it.

What happens behind the scenes

1. On submit, the add-on takes the total Gravity Forms calculated on the server and creates a HitPay payment request for it, for example 285.00 SGD, with a unique reference for this attempt and the address to return to.
2. HitPay answers with the address of its checkout for that request. The add-on checks that it really is the HitPay checkout and sends the customer there.
3. When the customer pays, HitPay sends a webhook to your site, signed with your webhook salt. The add-on checks the signature first.
4. The add-on then reads the payment request back from HitPay. Only a completed request with one succeeded payment of the entry’s amount and currency marks the entry Paid, and only then do the held emails go out.
5. If a webhook is missed, the return page, the status check every five minutes and the Refresh status button do the same read-back.

A worked example

A pottery studio in Singapore sells wheel classes at $ 120.00 and a glaze and firing kit at $ 45.00. A customer books two classes and one kit. Gravity Forms shows the total $ 285.00. The add-on creates a payment request for 285.00 SGD with the purpose “Book a pottery class #1042” and the customer’s email, and the customer pays with PayNow. HitPay sends its webhook, the add-on reads the request back, finds one succeeded payment of 285.00 SGD, marks the entry Paid with the HitPay payment ID and sends the booking email. A week later one class is cancelled: the studio refunds $ 120.00 from the entry and the note records it.

A studio in Kuala Lumpur does the same with the form currency set to Malaysian Ringgit: the total RM 285.00 becomes a payment request for 285.00 MYR, and customers can pay by FPX or DuitNow.

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.

Tips for smooth payments

• Keep prices in the format Gravity Forms shows or as plain numbers such as 1250.
• Use the Payment Completed notification event for receipts, so they are only sent for confirmed payments.
• Use a clear purpose with the entry number, so you can find a payment in the HitPay dashboard quickly.
• Add separate webhooks for the sandbox and live dashboards, each with its own salt in the matching field.
• If you want a payment link to expire quickly, a short filter can set it; the amount and addresses always stay as Gravity Forms calculated them.

Step 5: Go live

Copy the live API key from your live HitPay dashboard, add the same webhook address there and copy that webhook’s salt. Paste both into the Live fields, switch the mode to Live and save. Make one small real payment and refund it to check everything end to end. Entries paid in the sandbox keep their sandbox mode, so the two never mix.

Questions

Do card or bank details reach my website?

No. The customer pays on the HitPay checkout. Your site only sends the order and receives the result.

Which currencies can I use?

Singapore dollars, Malaysian ringgit and Philippine pesos out of the box. If HitPay has enabled card payments in other currencies on your account, you can tick US, Australian, New Zealand, Hong Kong or Canadian dollars, Thai baht, euro or pound sterling as well.

What if the webhook never arrives?

The customer’s return, the status check every five minutes and the Refresh status button all read the payment request from HitPay, so a missed webhook only delays the update a little. An entry still unpaid after 48 hours is cancelled, and a payment that arrives later still marks it Paid.

Can I refund part of a payment?

Yes. You can make several partial refunds from the entry, up to the paid amount. Refunds made in the HitPay dashboard are recorded too.

Are subscriptions supported?

Not in version 1.0.0: the add-on takes one-off payments for products, services and donations.

Get started

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