Gravity Forms Omise Premium Add-on Setup Guide

The Gravity Forms Omise Premium Add-on takes payments in Thailand, Japan, Singapore and Malaysia with your forms through Omise (Opn Payments). The form shows a payment box with the methods of your currency: cards everywhere, PromptPay, TrueMoney, Rabbit LINE Pay and mobile banking apps in Thailand, Konbini and Pay-easy in Japan, PayNow in Singapore, and FPX and DuitNow QR in Malaysia. The amount is always the total Gravity Forms worked out on the server, and before an entry changes the add-on reads the charge back from Omise and checks it.

This guide covers the setup, the feed, the payment methods, webhooks, refunds, capture and going live. The add-on costs one site $49 a year, five sites $69 a year, unlimited sites $199 a year.

What you need

• Gravity Forms 2.9 or newer, WordPress 6.5 or newer and PHP 7.4 or newer.
• An Omise account in Thailand, Japan, Singapore or Malaysia, with the payment methods you want enabled on it. Omise enables some methods (for example FPX, Konbini and PayNow) on request.
• Your site on HTTPS. Omise sends webhooks to HTTPS addresses only, and Omise.js needs a secure page for cards.
• A form with product fields and a total, in one of the supported currencies.

Install and activate

1. Upload the add-on in Plugins → Add New → Upload Plugin and activate it.
2. Open Forms → Settings → Omise and activate your license key. The Omise settings appear once the license is active.

Connect your Omise account

In the Omise dashboard open Keys. Each mode has a public key and a secret key: pkey_test_… and skey_test_… in test mode, pkey_… and skey_… in live mode.

1. Leave the mode on Test.
2. Paste the test public key and the test secret key. The secret key field refuses a public key, and each field refuses the key of the other mode.
3. Save. The account line shows the masked keys, and the currency line lists the methods for the currency of your forms.

The secret key creates every charge and reads every result back. It is stored encrypted with a key made from your site’s salts and is never shown again. The public key is not a secret: Omise.js uses it in the customer’s browser to create card tokens.

Currencies and payment methods

Choose the currency in Forms → Settings. The payment box offers the ticked methods that take that currency:

Amounts go to Omise in the smallest unit of the currency: satang for baht, cents for Singapore dollars and ringgit, and whole yen for the Japanese yen, which has no decimals. A form total of ¥6,000 is sent as 6000, and ฿3,250.00 as 325000. Omise sets a minimum per currency and per method, for example THB 20 for every Thai method, JPY 100 for cards and JPY 200 for Konbini, SGD 1 for PayNow and MYR 1 for FPX. When the total is outside the limits of the chosen method, the form shows a message before anything is saved.

Create the feed

1. Open the form, then Settings → Omise, and add a new feed.
2. Keep the transaction type Products and Services and the payment amount Form Total.
3. Tick the payment methods to offer. Methods of other currencies are ignored on this form.
4. Choose when cards are charged: at once, or authorize only and capture later from the entry screen.
5. Write the charge description shown in your Omise dashboard. Merge tags such as {form_title} and {entry_id} work.
6. Keep Send form notifications only after the customer has paid ticked so bookings are confirmed only when the money is there.
7. Add conditional logic if only some submissions should be paid.

What the customer sees

The payment box sits above the submit button. The customer picks a method and fills in what it needs: the card fields for cards, a 10-digit phone number for TrueMoney, the bank for FPX and mobile banking, and a short name, email and phone number for Konbini and Pay-easy.

• Card: on submit, Omise.js creates a token. If the card is charged at once, the customer sees your confirmation. If the bank asks for 3-D Secure, the customer confirms on Omise’s page and returns to your confirmation. A declined card shows the reason and a link back to the form.
• PromptPay, PayNow, DuitNow QR: the confirmation shows the QR code and the amount. The customer scans it with a banking app; the page checks the payment by itself and also has a “check now” link.
• TrueMoney, Rabbit LINE Pay, mobile banking, FPX: the customer goes to the wallet or bank page, approves the payment and comes back to your confirmation.
• Konbini, Pay-easy, online banking: the customer receives the payment instructions from Omise and pays within the time Omise allows. The entry waits as Pending.

Webhooks

QR, wallet, bank and Konbini payments often finish after the customer has left your site, so Omise reports them with webhooks. Copy the webhook address from the settings page and add it as the endpoint of each mode in the Omise dashboard (Webhooks). One address serves both modes.

For every event the add-on asks Omise for the event by its id. A made-up event does not exist at Omise and is refused; an event whose type or charge differs from the one Omise holds is refused too. Then the charge is read back and checked against the entry: your reference, the amount, the currency and the mode must match. The same event delivered twice is applied once.

For a second layer, paste the webhook signing secret of each mode from the Omise dashboard. With it saved, every webhook needs a valid Omise-Signature header (HMAC-SHA256 of the timestamp and the body), and webhooks without one are answered 401. The webhook address also answers too many requests from one address with 429.

Payment statuses

Refunds

Open the entry. The Omise box shows the status, the charge, the method, the amount and what was refunded. Type an amount (the rest of the payment is filled in) and press Refund. Full and partial refunds work, and each refund is booked by its Omise refund id, so the refund webhook for it later is not counted again. Refunds made in the Omise dashboard are recorded on the entry when their webhook arrives or when you press Check the payment with Omise.

Omise cannot refund PromptPay and Konbini / Pay-easy payments, so those entries show a short note instead of the refund form. Other methods have their own refund periods at Omise, for example 30 days for TrueMoney and six months for PayNow and FPX; Omise’s answer is shown when a refund is refused.

Authorize now, capture later

With Authorize only, capture later in the feed, card payments are authorized and the entry is marked Authorized. Press Capture in the entry box when you are ready; the add-on captures the charge and reads it back before the entry is marked Paid. Authorizations that are not captured expire at Omise after the period your account allows.

How this add-on differs

• Card details are typed in your form but turned into a one-time token by Omise.js in the browser; the card fields have no name, so the card number is never sent to your website.
• The local methods of four countries in one feed, each shown only for its currency and only when the total is within Omise’s limits for that method.
• Nothing is trusted from the browser, the return address or a webhook: every result is read back from Omise with your secret key and checked against the entry (charge, reference, amount, currency, mode).
• Webhook events must exist at Omise, and with a signing secret saved they also need a valid Omise-Signature; the same event is never applied twice.
• Refunds from the entry screen are booked by their Omise refund id, so a webhook for the same refund, or a refund made in the dashboard, is counted once.
• Card payments can be authorized only and captured later from the entry screen.

For developers

The filter gravityextra_omise_charge_body changes the charge request before it is sent. The amount, the currency, the return address, the reference and the card token or source are set again after the filter, so they always match the entry.

// Add the customer's email to the Omise charge metadata for one form (ID 7).
add_filter( 'gravityextra_omise_charge_body', function ( $body, $feed, $form, $entry ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $body;
    }
    $body['metadata']['customer_email'] = (string) rgar( $entry, '2' );
    return $body;
}, 10, 4 );

Other filters: gravityextra_omise_webhook_url (the webhook address), gravityextra_omise_js_url (the Omise.js address) and gravityextra_omise_rate_limit (requests per minute per address for the webhook and the return page).

Troubleshooting

Go live

1. Make a test payment with each method you offer, using the Omise test cards and the test pages of the other methods.
2. Paste the live public key and the live secret key, and add the webhook address in live mode in the Omise dashboard.
3. Switch the mode to Live and save.
4. Make one small real payment and refund it from the entry screen.

Entries paid in test mode keep a test label and stay checked against the test keys, so test and live payments never mix.