VibeFox Omise for WooCommerce — Help

Requirements

WordPress: 6.2 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it; if WooCommerce is turned off later, the gateway is not loaded and an admin notice is shown.

PHP: 8.0 or later.

HTTPS: the card fields are on your checkout page, so the checkout must be served over HTTPS and kept free of untrusted scripts. Card data still never reaches your server. Omise sends webhooks to HTTPS addresses only.

Store currency: one of THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. For other currencies the payment method is hidden at checkout.

Omise account: you need the public key and the secret key of your Omise account for test and for live mode, from Settings > Keys in the Omise dashboard, and a webhook endpoint in Settings > Webhooks (see Configuration).

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_omise_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Omise > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter your Omise test and live keys and add the webhook URL shown on the settings page in the Omise dashboard (see Configuration).

6. Turn on Enable/Disable. Test a payment in test mode with an Omise test card such as 4242 4242 4242 4242, then untick Test mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Omise. Above the fields the page shows Test mode is on — orders are charged with the test keys, no real money is moved. while test mode is on, and warns you when the public or secret key of the current mode is missing or the store currency is not supported by Omise. In both cases the payment method is hidden at checkout. In the list of payment methods, Omise is marked as needing setup until both keys of the current mode are entered.

General

Enable/Disable: Enable card payments via Omise turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Credit / Debit Card.

Description: the text shown above the card form at checkout. Default: Pay securely with your credit or debit card via Omise.

API keys

Find your keys in the Omise dashboard under Settings > Keys. Test keys start with pkey_test_ and skey_test_, live keys with pkey_ and skey_. When you save, a key with the wrong prefix (for example a test key in a live field) is refused with an error, and the previous value is kept.

Test mode: Use the test keys (no real charges). Switches both keys. Refunds, captures and status checks of an order always use the keys of the mode the order was paid in. Default: on.

Test public key: the public key of test mode, pkey_test_...

Test secret key: the secret key of test mode, skey_test_...

Live public key: the public key of live mode, pkey_...

Live secret key: the secret key of live mode, skey_...

Payment and webhook

The section shows the webhook URL of your store. It looks like https://your-site/wp-json/omise-payment/v1/webhook. Copy it exactly as the settings show it and add it in the Omise dashboard under Settings > Webhooks (HTTPS only). The plugin handles these events:

The webhook body is never trusted: the charge must be the one stored on the order, and its status is read again from the Omise API with the keys of the order's mode. Without the webhook, an order whose customer closes the browser during 3-D Secure stays On hold until you run Omise: Sync payment status, and captures made in the Omise dashboard are not picked up automatically.

Payment action: what happens to the card amount.

Per-charge webhook: Send the webhook URL with every charge. Useful when several shops share one Omise account. Works only when the site uses HTTPS; otherwise the dashboard webhook is used. Default: off.

Advanced

Debug log: Log API requests and payment events to WooCommerce > Status > Logs, source wcp_omise_payment. Keys, tokens and card data are never logged. Default: off.

Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default Credit / Debit Card) and fills in the card form: Name on card, Card number, Expiry month (MM), Expiry year (YYYY) and Security code (CVV). In test mode the form shows TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. When the order is placed, Omise.js turns the card into a one-time token in the browser. The card fields are never posted to your server.

Your store creates the charge with the secret key for the order total in the order currency. The charge description is the store name and the order number, and the order ID is stored in the charge metadata. If the bank requires 3-D Secure, the customer is redirected to the bank and back to your store. The result is always read again from the Omise API.

The order is marked paid only after Omise confirms it: the charge must be captured and its amount and currency must match the order. With Authorize only the order is put On hold after a successful authorization. The customer sees the order received page.

If the card is declined, the customer stays at checkout with Payment failed: and a reason, for example insufficient funds, an invalid security code or a decline by the card issuer, and can try again. After a failed 3-D Secure the customer is taken to the Pay for order page. If the payment cannot be confirmed right after 3-D Secure, the customer sees We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.

A retry never charges twice: if the previous charge of the order is already paid or authorized, the order is completed without a new charge. An unfinished 3-D Secure attempt is expired before a new charge is made.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes cards only. It has no other Omise payment methods (PromptPay, TrueMoney, mobile banking, installments, Konbini, PayNow), no saved cards or Omise customers, no subscriptions and no partial capture.

Orders and refunds

Order statuses

Pending payment: the customer is on 3-D Secure or has not paid yet.

Processing: the payment was confirmed. Orders with only virtual downloadable products become Completed, as usual in WooCommerce. The order note shows the amount, the charge ID and how it was confirmed (checkout, 3-D Secure return, webhook, manual capture or manual sync). The transaction ID is the Omise charge ID (chrg_...).

On hold, awaiting capture: the card was authorized with Authorize only. Use Omise: Capture payment or Omise: Void authorization.

On hold, pending: Omise has not confirmed the payment yet, for example the customer closed the browser during 3-D Secure. The webhook or Omise: Sync payment status updates the order.

On hold, mismatch: the charge amount or currency differs from the order. The note shows both values. Check the order and complete it or refund the payment.

Failed: the payment was declined. A paid order is never downgraded by a later failed event.

Cancelled: the charge expired or the authorization was voided.

If a paid or authorized charge arrives for an order that is already Cancelled or Refunded, the order is not reopened. One note asks you to check the Omise dashboard and refund or reopen the order manually.

Order actions

Omise: Capture payment: captures the full authorized amount. Shown only for authorized orders.

Omise: Void authorization: voids the authorization; no money is captured and the order is cancelled. Shown only for authorized orders.

Omise: Sync payment status: reads the charge from Omise and updates the order. The note also shows the total refunded at Omise.

Refunds

Open the order, click Refund, enter the amount and click Refund via Omise. Full and partial refunds are supported. The refund is sent in the mode the payment was made in, so that mode's secret key must be set. A successful refund is added to the order notes with the Omise refund ID. For an authorization that was not captured yet, only a full refund is possible, and it voids the authorization. If Omise rejects the refund, WooCommerce shows Refund failed. with the Omise message, and no refund is recorded.

Refunds made in the Omise dashboard are not imported as WooCommerce refunds. Omise: Sync payment status shows the refunded total; create matching manual refunds in WooCommerce if needed.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Omise. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Omise is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and captures and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Omise does not appear at checkout: check that the license is active, Enable/Disable is on, both keys of the current mode are entered (test keys in test mode, live keys otherwise) and the currency is supported. On the Pay for order page the order currency counts. The settings page shows a warning when keys or the currency are wrong.

The payment went through, but the order stays Pending payment or On hold: the webhook is not working. In the Omise dashboard check that the webhook URL is exactly the one shown in the settings and uses HTTPS. Then run Omise: Sync payment status on the order. Turn on Debug log to see webhook answers.

Webhook answers Earlier charge of the order, order not changed: the event is for an earlier attempt of the order that was replaced by a retry. Nothing is changed on the order. If that earlier charge is paid or still authorized at Omise, an order note says so once: check the Omise dashboard for a double payment and refund or void it there.

Webhook answers Charge ID does not match order: the charge in the event belongs to another order. Nothing is changed.

Webhook answers Order is being processed, retry later or Failed to verify charge: the order was locked by another request, or the Omise API could not be reached. Omise retries the webhook.

Error on save: key must start with ... or must be a live key: a key was pasted into the wrong field. Test keys start with pkey_test_ / skey_test_, live keys with pkey_ / skey_.

The customer sees Card payments are temporarily unavailable: the keys are wrong, or the card token belongs to the other mode (a test token in live mode or the other way round). Check the keys and Test mode.

The customer sees We could not reach the payment provider: no valid answer came from Omise while creating the charge. A charge may still have been created; the order note asks you to check the Omise dashboard before charging the order again.

The customer sees This order is already being paid: the checkout was submitted twice at the same moment. The customer waits and checks the e-mail before trying again.

Order is On hold after payment: read the order note. The order awaits capture, Omise has not confirmed the payment yet, or the amount or currency differs from the order.

Refund fails with a message about the mode: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it and try again.

Partial refund of an authorized order fails: the payment is only authorized. Capture it first, or refund the full amount to void it.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Omise data saved on orders is payment history and is always kept. Existing orders keep their payment notes and transaction IDs.

Omise is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Omise.