VibeFox Omise for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

HTTPS: the card fields are on your checkout page, so the checkout should be served over HTTPS. Card data still never reaches your server. Omise sends webhooks to HTTPS addresses only, and the bank's 3-D Secure page must be an HTTPS address.

Currency: one of THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. For a cart in any other currency 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Omise Payment in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

5. Turn on Enable/Disable and click Save. Test a payment in test mode with an Omise test card such as 4242 4242 4242 4242, then turn off Test mode.

On install the module creates three order statuses: Omise payment authorized, Omise payment on hold and Awaiting Omise payment. The payment method is offered for the countries that are active at install time. If you activate more countries later, allow the module for them in Payment > Preferences, where you can also limit it by currency and customer group.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Omise Payment > Configure. Each section has its own Save button, which saves the whole page. 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, warns you when the public or secret key of the current mode is missing, and warns you when Omise does not accept the default currency of your shop. In these cases the payment method is hidden at checkout.

Omise

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

Title: the payment method name the customer sees at checkout. It is also the payment method name stored in the order. Default: Credit / Debit Card. Required.

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 not saved: the previous value is kept and a warning is shown.

Test mode: uses the test keys, no real charges. It switches both keys. Captures, refunds 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_...

Saved secret keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick a secret key and click Save to remove it. An empty field keeps the saved value.

Payment and webhook

Webhook URL: the address of the webhook of your shop. With friendly URLs it looks like https://your-shop/module/wcp_omise_payment/webhook. Copy it exactly as the settings show it and add it in the Omise dashboard under Settings > Webhooks (HTTPS only). The module handles these events (they are also listed in this section):

charge.complete: a charge was completed, for example after 3-D Secure.

charge.capture: an authorized charge was captured, also when you capture it in the Omise dashboard.

charge.reverse: an authorization was voided.

charge.expire: a charge expired.

Omise does not sign webhooks, so the webhook body is never trusted: the charge must be one created by this shop for that cart, and its status is read again from the Omise API with the secret key of the payment's mode. Without the webhook, an order whose customer closes the browser during 3-D Secure is not created automatically, and captures made in the Omise dashboard are not picked up until you click Sync payment status.

Payment action: what happens to the card amount.

Capture immediately: the amount is charged at once (default).

Authorize only (manual capture): the card is only authorized. The order stays in Omise payment authorized until you click Capture payment in the Omise block of the order. Authorizations expire after about 7 days.

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

Advanced

Debug log: writes API requests and payment events to logs/omise_p_debug.log.php in the module folder. The file cannot be read from the web. Keys, tokens and card data are never logged. Default: off. Nothing is written while it is off, errors included, so turn it on while you look for a problem.

Log: shows the size and the latest entries of the log, with a button to clear it.

Delete data on uninstall: when on, uninstalling the module removes the settings and the debug log. The Omise charges and refunds of orders are payment history and are always kept. Default: off.

Checkout

At the payment step 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 customer places the order, Omise.js turns the card into a one-time token in the browser, using the billing address of the cart. The card fields are never posted to your shop. Missing or invalid fields are shown under the form, for example Please enter a valid card number.

Your shop then creates the charge with the secret key for the cart total in the cart currency. The charge description is the shop name and the cart number, and the cart ID is stored in the charge metadata. No order exists yet at this point. If the bank requires 3-D Secure, the customer is sent to the bank page and back to your shop, and the result is 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 cart. The customer sees the standard order confirmation page with Your card payment has been received. With Authorize only the page says Your card payment has been authorized. The amount will be charged when your order is processed. If Omise still reports the payment as pending, the order is created in Awaiting Omise payment and the page says Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. If the payment cannot be confirmed right after 3-D Secure, a Payment confirmation page shows We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. and a Check again button.

If the card is declined, no order is created. 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 with the same cart. If 3-D Secure fails, the customer is back at checkout with the reason as well; if the charge expired or was reversed meanwhile, the message is The payment was not completed. Please try again.

A retry never charges twice: if the previous charge of the cart is already paid or authorized, the order is created without a new charge. An unfinished 3-D Secure attempt is expired before a new charge is made. If a second charge is still paid for a cart that already has an order (for example in another browser tab), the order is not changed and a note asks you to refund or void it in the Omise dashboard.

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

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

Orders and refunds

Order statuses

No order yet: the customer is on 3-D Secure, or the card was declined. Only the cart exists.

Payment accepted: the payment was confirmed. The payment is recorded with the Omise charge ID (chrg_...) as the transaction ID, and a note shows the amount, the charge and how it was confirmed (checkout, 3-D Secure return, webhook, payment retry, manual capture or manual sync). Notes are private messages of the order, visible only in the back office.

Omise payment authorized: the card was authorized with Authorize only. Use Capture payment or Void authorization.

Awaiting Omise payment: Omise has not confirmed the payment yet. The webhook or Sync payment status updates the order.

Omise payment on hold: the charge amount or currency differs from the order, for example the cart was changed during 3-D Secure. The note shows both values. A captured payment is still recorded on the order. Check the order and fulfil it or refund the payment.

Payment error: a pending payment failed later. A paid order is never downgraded by a later failed event.

Canceled: the charge expired or the authorization was voided.

Refunded: the payment was fully refunded through the module.

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

Omise payment block

The order page shows an Omise payment block with the charge ID, the payment action, the charge status, the card brand and last digits, the amounts charged, of the order and refunded, a Test mode badge for test payments and the refund history. The buttons of the block need the right to edit orders and the secret key of the mode the payment was made in. Access to the Modules pages is not needed. The result of each action is shown at the top of the block.

Capture payment: captures the full authorized amount and sets the order to Payment accepted. Shown only for authorized orders.

Void authorization: voids the authorization; no money is captured and the order is set to Canceled. Shown only for authorized orders.

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

Refunds

In the Omise payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Omise. Confirm the question Refund this amount through Omise? This cannot be undone. Full and partial refunds are supported. Refunds are made in the amount and currency Omise charged, so after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total. The refund is sent in the mode the payment was made in, so that mode's secret key must be set. The reason is stored with the refund at Omise. A successful refund is added to the refund history and the notes with the Omise refund ID. A full refund sets the order to Refunded; a partial refund does not change the status. For an authorization that was not captured yet, only a full refund is possible, and it voids the authorization. If Omise rejects the refund, the block shows Refund failed. with the Omise message, and no refund is recorded.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Omise. Refunds made in the Omise dashboard are not recorded in PrestaShop; Sync payment status shows the refunded total.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Omise Payment is the first block on Modules > Module Manager > VibeFox Omise Payment > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-omise and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency is one of the supported currencies. The settings page shows a warning when keys are missing. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created or the order stays Awaiting Omise payment: the webhook is not working. In the Omise dashboard check that the webhook URL is exactly the one shown in Webhook URL and uses HTTPS. On an existing order click Sync payment status. Turn on Debug log to see the webhook answers.

Webhook answers Charge ID does not match order or Order not found: the charge in the event was not created by this shop for that cart. Nothing is changed.

Webhook answers Order is being processed, retry later or Failed to verify charge: the cart was locked by another request at the same moment, the Omise API could not be reached, or the secret key of the payment's mode is missing. Omise retries the webhook.

Webhook answers The order could not be created, retry later: the order could not be created, for example because the module is disabled. Turn on Debug log to see the reason.

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Omise.

Warning on save: key must start with ... or must be a live key: a key was pasted into the wrong field and was not saved. 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; check the Omise dashboard before the customer pays again.

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

Order is Omise payment on hold after payment: read the note in the order (see Order statuses), then fulfil the order or refund the payment.

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.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Omise Payment and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the settings and the debug log are removed. If it is off, all settings are kept for a later re-install. The Omise charges and refunds and the order statuses Omise payment authorized, Omise payment on hold and Awaiting Omise payment are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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