Omise Gateway for Gravity Forms

1. Overview

Omise Gateway for Gravity Forms by PatSaTECH takes payments on your Gravity Forms with Omise (Opn Payments), for businesses in Thailand, Singapore, Malaysia and Japan. After the form is submitted the visitor pays in Omise’s secure payment window (Omise.js) on a pay page of your site; card details never reach your server. PromptPay and PayNow show a QR code that moves on to your confirmation by itself once paid.

It is built on the official Gravity Forms Payment Add-On Framework: entries get the standard payment status, amount, transaction ID and date, notifications and add-on feeds can wait until the payment is received, and refunds are made from the entry screen. An entry is marked Paid only after the charge has been read back from the Omise API.

2. Features

Omise.js secure payment window
Cards with 3-D Secure
PromptPay / PayNow QR page
TrueMoney, mobile banking, FPX, GrabPay…
Gravity Forms Payment Add-On Framework
Products & Services feeds with conditional logic
Notifications only after payment
Post-payment actions for other add-ons
Test & Live keys, checked on save
Signed webhooks (Omise-Signature)
Every charge re-read from the API
Amount & currency verification
Full & partial refunds from the entry
Dashboard refunds noted
Duplicate payments refunded automatically
Minimum amount checked
Unpaid entries marked Failed on a timer
Card brand & last 4 in the entry note
Gravity Forms logging (no secrets logged)
Translation-ready (.pot)

3. Requirements

Component	Minimum
WordPress	6.0 (tested up to 7.1.3)
Gravity Forms	2.5 (tested up to 2.10.3)
PHP	7.4
SSL / HTTPS	Required for live payments and for webhooks.
Omise account	A free test account or a verified live account, its public and secret keys, and the webhook endpoint set to this site
Form currency	The Gravity Forms currency (Forms → Settings → Currency) must be one Omise accepts for your account

Tested on: WordPress 7.1.3, Gravity Forms 2.10.3, PHP 8.1.34, Omise test mode (Thailand, THB). See Tested on.

4. Installation

Plugins → Add New → Upload Plugin, choose gravityforms-omise-1.0.0.zip, Install Now.
Activate Omise Gateway for Gravity Forms. Gravity Forms must be active.

Step-by-step setup with screenshots

Live-tested on Gravity Forms 2.10.3 with an Omise test account (Thailand, THB). Verified:

Card payment, entry Paid, admin notification sent only after the payment (entry 9623)
Declined card: entry Failed, no notification, then paid with another card (entry 9624)
PromptPay QR paid with Omise’s test “Mark as paid”: the page moved to the confirmation by itself in about 6–7 seconds (entry 9625)
Minimum amount (THB 10 form): clear message, no charge (entry 9626); unpaid entry marked Failed by the time limit (entry 9627)
Refunds from the entry: 100.00 and 450.00 partial, a refund larger than the balance refused, the rest refunded → Refunded (entries 9623, 9629)
Screenshots: card payment and refunds on entry 9630, PromptPay QR on entry 9631, declined card on entry 9632

Click any screenshot to open it full size. Keys, webhook secrets, Omise IDs, emails, phone numbers and IP addresses are blurred or left out.

Part A: Omise dashboard

Copy your test keys
At dashboard.omise.co (test mode) open Keys and copy the public key (pkey_test_…) and secret key (skey_test_…). Details: Getting your Omise keys.
Point the webhook to this site
Open Webhooks and set the endpoint to https://your-site.com/?callback=gravityforms-omise.

Part B: WordPress / Gravity Forms

Upload and activate the add-on
Upload gravityforms-omise-1.0.0.zip and activate it.

Omise Gateway for Gravity Forms 1.0.0 active.
Paste the keys
Forms → Settings → Omise: choose Mode: Test, paste the Test public key, Test secret key and (optional) Test webhook secret, and save. The add-on checks the keys with Omise and shows the account country and funding currency.

Mode, test and live keys (masked) and the webhook URL.
Cards, other payment methods, payment window title, duplicate payments, time limit and debug log.
Add an Omise feed
Open your form → Settings → Omise → Add New. Choose Products and Services, the payment amount (form total or a product field), map First Name, Last Name and Email, and under Notifications tick Send notifications only when payment is received. Save.

Feed: transaction type, payment amount, customer field mapping.
Notifications delayed until payment; post-payment actions.

Part C: Test payment

Submit the form
Fill in the form and submit it.

A payment form with a THB 500 product (email blurred).
Pay in the Omise payment window
The pay page opens the Omise payment window. Pay with test card 4242 4242 4242 4242 (any name, future expiry, CVC), or choose PromptPay and use Mark as paid in the Omise dashboard.

Omise payment window on the pay page for entry #9630 (฿500.00), test card 4242.
Choosing PromptPay in the Omise payment window.
PromptPay QR code for entry #9631 with the amount and the “valid until” time (site time zone; UTC on the test site).
Confirmation
After the payment the visitor sees your form’s confirmation.

Form confirmation after the successful Omise payment for entry #9630.
Entry is Paid
The entry shows Payment Status: Paid, the amount, the Omise charge ID as transaction ID and notes, for example “Omise payment completed: confirmed with Omise, charge status “successful” (checked on …).” with the method (Card (Visa ending 4242)). Delayed notifications are sent now.

Entry #9630: Payment Status Paid, payment details and notes (transaction ID, email, user and IP blurred).
Entry #9633 notes: “Omise payment completed … Method: Card (Visa ending 4242)”, with the Payment Details and the Refund via Omise box (charge / transaction ID blurred).

5. Getting your Omise keys and webhook

Sign up / sign in at dashboard.omise.co. A new account starts in test mode: no real money moves and no verification is needed. The switch at the top of the dashboard toggles Test and Live; each mode has its own keys and webhook endpoint.
Open Keys and copy the public key (pkey_test_…) and the secret key (skey_test_…). Copy them straight into Forms → Settings → Omise (Test public key, Test secret key, Test webhook secret, or the live fields); don’t paste them into emails or chats.
Open Webhooks, set the endpoint to https://your-site.com/?callback=gravityforms-omise and save. If the page shows a webhook secret, copy it into the plugin’s webhook secret field: webhooks are then checked with the Omise-Signature header. Without a secret every event is confirmed by reading it back from the Omise API, which is just as safe. The add-on also sends its own webhook URL with every charge (setting Webhook URL with each charge, on by default), so the Gravity Forms site receives its events even when the dashboard endpoint points to another site.
Save the plugin settings. The plugin checks the keys with Omise and shows, for example, “Omise Test keys verified. Account country TH, funding currency THB.”
Optional: two-factor authentication for your dashboard login is under your Omise account settings. It is not needed for the keys.
When Omise has verified your business, switch the dashboard to Live, copy the live keys (pkey_…, skey_…), set the live webhook endpoint and fill in the live fields.

Keep the secret key and webhook secret private. Anyone with the secret key can create charges and refunds on your account. They are stored only in your WordPress database, the fields are masked, and they are never written to the log. If one leaks, roll it in the Omise dashboard and paste the new value.

6. Add-on settings

Forms → Settings → Omise

Setting	Description
Mode	Test (default) or Live. Entries keep the mode they were created in.
Test / Live public key, secret key	From the Omise dashboard → Keys. Checked with Omise when you save.
Test / Live webhook secret	Optional. When set, webhooks are verified with the `Omise-Signature` header; when empty, each event is read back from the Omise API.
Webhook	The URL to set in the Omise dashboard: `https://your-site.com/?callback=gravityforms-omise`.
Webhook URL with each charge	On by default: Omise sends the events of each charge to this site.
Cards	Offer credit / debit card payments (on by default).
Other payment methods	Optional, comma-separated Omise source types, for example `promptpay, paynow, truemoney_jumpapp`.
Payment window title	Shown at the top of the Omise payment window. Empty = the site name.
Duplicate payments	Automatically refund a second payment for an entry that is already paid (PromptPay and others Omise cannot refund are flagged in the notes instead). On by default.
Mark unpaid entries Failed after (minutes)	Default 60. QR codes expire at the same time; the add-on checks Omise once more first. 0 disables it.
Debug log	Logs webhook, API and info messages (needs Forms → Settings → Logging on for this add-on). Errors are always logged; keys and webhook secrets never are.

7. Feed settings

Setting	Description
Name	Any name for your own reference.
Transaction Type	Products and Services (one-time payments; subscriptions are not supported).
Payment Amount	Form total or a single product field.
Customer fields	First Name, Last Name and Email, sent to Omise with the charge (optional).
Notifications	Send notifications only when payment is received, for any notification you choose (tested: the admin notification arrived only after the payment).
Post Payment Actions	Run feeds of other add-ons (mailing lists, User Registration…) only when the payment is received.
Conditional Logic	Use Omise only when the condition is met.

8. Webhooks

Webhook URL: https://your-site.com/?callback=gravityforms-omise

Event	What the plugin does
`charge.create`	A charge was created. For cards without 3-D Secure the charge is already successful or declined at this point, so this is often the only event (seen in the live test). The plugin reads the charge again from the API and applies the result.
`charge.complete`	A pending charge finished: 3-D Secure, a bank / wallet page, or a PromptPay QR code that was paid or failed. Read again from the API and applied.
`charge.expire`	A QR code / wallet charge expired unpaid. Noted; at the time limit the order / entry is closed.
`charge.reverse / charge.update`	Any other change of the charge: read again and applied (a reversed charge is noted).
`refund.create`	A refund was made, from this plugin or in the Omise dashboard. Refunds made outside the plugin are noted (amount and refund ID).

Omise sends all events to the endpoint (there is nothing to tick). Events the plugin does not use (customer, dispute, transfer…) are acknowledged with HTTP 200 and logged.

Each webhook writes a log line saying how it was verified, for example Webhook charge.complete for entry #9625: charge chrg_test_… (test mode, signature verified).

9. Payment flow & entry statuses

Situation	Payment status
Form submitted, visitor on the pay page	Processing
Charge successful	Paid; delayed notifications and post-payment feeds run
Card declined / payment failed	Failed, reason in the notes; the visitor can pay again on the pay page
Time limit reached without a payment	Failed (“Omise: unpaid entry marked Failed after the time limit (customer did not pay).”); the pay link then says “This payment can no longer be completed. Please submit the form again.”
Fully refunded	Refunded

10. Refunds

Open the entry. In the Refund via Omise box enter an amount (leave blank for a full refund), an optional reason, and click the button. One message shows the result above the box: green when Omise accepted the refund, red when it was refused (for example “Refund amount exceeds refundable balance (฿ 500.00).”). Notes record each refund; when the whole amount is refunded the entry becomes Refunded (“Omise refund completed (refund …). Entry fully refunded.”).

Refund box — Entry #9633 sidebar: Refund via Omise box with the refundable balance (฿500.00). The amount box is empty and shows “500.00 (full refund)” only as a grey hint, so leaving it blank refunds the full balance.

Partial refund accepted — A ฿100.00 partial refund on entry #9630: one green message in the refund box naming the amount and the Omise refund (ID blurred).

Refund notes — Notes after the ฿100.00 partial refund and the ฿400.00 final refund; the box now says “Nothing left to refund.” (refund IDs blurred)

Entry refunded — Entry #9630 with Payment Status Refunded.

Refund refused — A refund larger than the balance: one red message, “Refund amount exceeds refundable balance (฿ 500.00).”, nothing sent to Omise and no note.

Refunds made in the Omise dashboard are noted on the entry through the refund.create webhook.
PromptPay and PayNow payments cannot be refunded or voided through Omise; the entry says so. Refund those visitors directly (for example by bank transfer) and record the refund manually.

11. Omise behaviour to know (declines, QR codes, minimum amount, time limit)

Declined cards

The visitor is back on the pay page with one clear message (for example insufficient funds) that is not repeated on reload, the entry becomes Failed and no notification is sent; paying again with another card makes it Paid and sends the notification (entry 9624).

PromptPay and other QR codes

The QR code is valid for the time limit (60 minutes by default, shown in your site’s time zone; tested on entry 9628). The page checks every few seconds and moves to your confirmation once paid.

Minimum amount

Below Omise’s minimum (THB 20, SGD 1, MYR 1, JPY 100) no charge is attempted and the visitor sees “This amount is below the minimum Omise payment amount of ฿ 20.00, so it cannot be paid online. Please change the amount or contact us.” (entry 9626).

Time limit

After Mark unpaid entries Failed after (default 60 minutes) the entry is checked with Omise and marked Failed if nothing was paid (entry 9627).

12. Double-payment protection

A per-entry lock means a webhook and the visitor’s return never complete the same entry twice.
While a payment is still being confirmed, a second payment is refused with a message, with a link for visitors who really closed it.
A second card or wallet payment that still goes through is refunded automatically in full and noted; a PromptPay / PayNow one is flagged in the notes for you to refund directly.

13. Testing in Omise test mode (test cards)

Use any name, any future expiry date (for example 12/30) and any 3-digit CVC. Card numbers are from Omise’s test-card list.

Scenario	Card	What happens
Success	Visa `4242 4242 4242 4242` (also Mastercard `5555 5555 5555 4444`, JCB `3530 1113 3330 0000`)	Paid straight away. Used for the successful test payments (entry 9623).
Declined	`4111 1111 1114 0011`	Declined with insufficient funds. The customer is back on the pay page with “Your payment was declined because the card or account has insufficient funds. Please try a different card or payment method.” and can pay again at once (entry 9624).

3-D Secure is off on new Omise test accounts, so test cards are charged without a 3-D Secure page. Omise support can turn it on for your test account; the test 3-D Secure page then has Success / Fail buttons.
PromptPay (Thailand) shows a QR code. In test mode open the charge in the Omise dashboard and use Actions → Mark as paid (or failed); the plugin’s QR page moves on by itself within a few seconds (tested: entry 9625, about 6–7 seconds).
Omise’s dashboard has no “send test webhook” button; a test payment is the way to see webhooks arrive.

14. Countries, currencies & payment methods

Who can use Omise. Omise (Opn Payments) serves businesses in Thailand, Singapore, Malaysia and Japan. Anyone can open a free test account at dashboard.omise.co (email and password, no phone number). Live payments need Omise’s business verification (KYC) for your country.

Currencies. The form currency must be one Omise accepts for your account; the funding currency of the test account used here was THB. Supported by the plugin: THB JPY SGD MYR USD EUR GBP AUD CAD CHF CNY DKK HKD (cards; Omise converts foreign currencies to your funding currency). Local methods only work in their own currency (PromptPay THB, PayNow SGD, FPX MYR…).

Amount limits. Omise’s minimum per charge is THB 20, SGD 1, MYR 1 or JPY 100 (maximum THB 150,000 / SGD 20,000 / MYR 100,000 / JPY 6,000,000 by default). Below the minimum the plugin shows a clear message before any payment is attempted (tested with a THB 10 order and form).

Payment methods. Cards are always offered (can be turned off). Add other methods in the Other payment methods setting, for example promptpay (TH), paynow (SG), fpx or duitnow_qr (MY), truemoney_jumpapp, mobile_banking_scb, rabbit_linepay, grabpay, shopeepay, touch_n_go, alipay_cn, econtext (JP convenience store)… Each method must be enabled on your Omise account; ask Omise support to activate the ones you need.

Tested so far: Omise test mode (Thailand account, THB): cards (success and decline), PromptPay QR, partial and full refunds, a dashboard refund, the duplicate-payment guard, the minimum amount and the time limit. Live payments, 3-D Secure and methods other than cards and PromptPay have not yet been paid with by PatSaTECH.

Finding the payment in Omise

In the Omise dashboard open Charges. Each charge shows the amount, status (Successful, Failed, Expired, Refunded / partially refunded), the method (for example Visa •••• 4242 or PromptPay) and, under Metadata, the order or entry it belongs to. Refunds made from the plugin show status Closed, Omise’s normal state for a completed refund. The entry ID and form ID are in the charge metadata (gf_entry_id, gf_form_id) and the Omise charge ID is the entry’s transaction ID.

15. Debug logs

Turn on Forms → Settings → Logging, enable Omise Gateway for Gravity Forms, tick Debug log in the add-on settings, and open the log from the Logging page. Errors are logged as ERROR; webhooks, refunds and status changes as DEBUG lines with their level (for example [NOTICE] Entry #9629: Omise refund … completed (refund from the entry screen).). Keys and webhook secrets are never logged.

Gravity Forms log for the Omise add-on: refund lines “completed (refund from the entry screen)” (IDs blurred).

16. Troubleshooting & FAQ

The entry stays Processing after paying

Check the webhook endpoint (https://your-site.com/?callback=gravityforms-omise) for the mode you use and that the site is reachable over https. The pay page and scheduled checks also read the charge from Omise; see the Gravity Forms log.

Notifications were sent before payment

In the Omise feed tick Send notifications only when payment is received for those notifications.

“Webhook rejected: invalid Omise-Signature”

The webhook secret in the add-on does not match the Omise dashboard for that mode. Paste it again or clear it.

Test emails

Gravity Forms’ email field rejects some reserved test addresses (for example [email protected]); use another address when testing.

Subscriptions?

No. One-time payments only.

17. Tested on

WordPress 7.1.3
Gravity Forms 2.10.3
PHP 8.1.34; PHP 7.4 or later required
Omise test mode (Thailand account, THB). Live payments not yet tested.
Scenarios: card payment with delayed notification, declined card and retry, PromptPay QR (Mark as paid), minimum amount, time limit, partial and full refunds, over-refund refused

18. Changelog

1.0.0 — 2026-10-18

Initial release.
Gravity Forms Payment Add-On with the Omise.js payment window: cards, PromptPay / PayNow QR page and other Omise methods.
Keys checked on save; webhooks verified with Omise-Signature or by event lookup.
Every charge re-read from the API under a per-entry lock; amount and currency verified.
Full and partial refunds from the entry; dashboard refunds noted; duplicate payments refunded automatically.
Delayed notifications and post-payment actions; minimum amount; unpaid entries marked Failed after a time limit; logging without secrets.

19. Support

PatSaTECH · [email protected] · www.patsatech.com

Please include your WordPress, Gravity Forms and PHP versions, the mode and the relevant log lines (never your keys).