VibeFox Omise for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

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. When the customer pays 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_omise_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_omise_payment.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_omise_payment-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Omise Payment and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_omise_payment.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Omise Payment, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the Omise keys and the webhook as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the webhook URL is different (see Payment and webhook).

A new install starts with the payment method turned off and test mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Omise Payment > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 (the payment method is then hidden at checkout), and warns you when Omise does not accept the default currency of your store. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, an empty Title or one longer than 128 characters, a Sort Order that is not a whole number, a Total that is not a number of 0 or more or an unknown order status stops the save: nothing is saved and the error is shown. A key with the wrong prefix (for example a test key in a live field) is not saved: the previous value is kept, a warning names the field and the other fields are saved.

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, up to 128 characters.

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

Sort Order: the position of Omise among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer the card form only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones. On OpenCart 4, when the store asks for no payment address, the shipping address is used.

Total: the checkout total, in the default currency of the store, that an order must reach before the payment method is offered. Leave it empty to offer it for any total.

API keys

Find your keys in the Omise dashboard under Settings > Keys (the page links there). Test keys start with pkey_test_ and skey_test_, live keys with pkey_ and skey_.

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_..., used by Omise.js in the browser.

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

Live public key: the public key of live mode, pkey_..., used by Omise.js in the browser.

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. To remove a saved key, tick Clear the saved value on save under the field and click Save.

Payment and webhook

Webhook URL: the address of the webhook of your store. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_omise_payment/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_omise_payment/payment/wcp_omise_payment.webhook. It is built from the storefront address of your OpenCart installation. Copy it exactly as the settings show it and add it in the Omise dashboard under Settings > Webhooks (HTTPS only). The extension handles these events (they are also listed in this section):

Omise does not sign webhooks, so the webhook body is never trusted: the charge must be one created by this store for that order, 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 updated 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.

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

Orders

The order is created at the Confirm Order step without a status (a missing order) and gets a status only after Omise has answered for the card. OpenCart has no On hold status: by default the authorized, review and awaiting statuses are all Pending, and the order tab and the notes tell them apart. You can create your own statuses in System > Localisation > Order Statuses and select them here.

Order Status After Payment: the card was charged (Capture immediately, or a capture later). Default: Processing.

Authorized Status: Authorize only: the amount is reserved, not captured yet. Default: Pending.

On Hold (Review) Status: the charged amount or currency differs from the order. Default: Pending.

Awaiting Payment Status: the customer has finished, but Omise has not confirmed the charge yet. Default: Pending.

Failed Status: a pending charge of an order with a status failed later. Default: Failed.

Canceled Status: the charge expired or the authorization was voided, no money was taken. Default: Canceled.

Refunded Status: set after the payment is fully refunded from the order tab. Default: Refunded.

Advanced

Debug log: writes API requests and payment events to omise_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to omise_p_debug.old.log.php. 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. Click Clear log to empty it.

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

Import / Export

Export: Download JSON saves the settings as a JSON file. Secret keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved secret keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit / Debit Card). At the Confirm Order step the customer sees your description and 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. OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options; the card form is in the confirmation section at the bottom of the checkout page, above Confirm Order. When the customer clicks Confirm Order, Omise.js turns the card into a one-time token in the browser, using the payment address of the order (on OpenCart 4, when the store asks for no payment address, the shipping address). The card fields are never posted to your store. Missing or invalid fields are shown above the form, for example Please enter a valid card number.

Your store then 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 sent to the bank page and back to your store, 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 order. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success 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 gets the Awaiting Payment Status 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. When Omise confirms or declines the payment later (the webhook or the customer's return), the new order status is sent with customer notification, so OpenCart e-mails it to the customer. 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, the order stays without a status. The customer stays at the Confirm Order step 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. On OpenCart 4 these messages after 3-D Secure are shown above the checkout page.

A retry never charges twice. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 keeps one order for the checkout and updates it, so after a declined card or a failed 3-D Secure the customer pays the same order with a new charge. If the previous charge of the cart is already paid or authorized, that order gets its status and no new charge is made. 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 is already paid (for example in another browser tab), no order is changed and a note on the paid order asks you to refund or void it in the Omise dashboard.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed meanwhile (for example its charge failed or expired, or you cancelled or refunded it), the customer is sent back to the checkout with Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order., and the next Confirm Order pays a new order. If that order is already paid and the cart now has other products or quantities, the customer is sent back to the checkout as well, and the new cart gets a new order.

The webhook also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action that lets the webhook and the customer's return from 3-D Secure through.

The extension 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 status (missing order): the customer is on 3-D Secure, or the card was declined. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

On OpenCart 4 an unpaid order of the checkout can get the status Voided, which OpenCart 4 sets when the customer comes back to the Confirm Order step. The extension treats such an order as an order without status, and a later payment still confirms it.

Order Status After Payment (default Processing): the payment was confirmed. A note shows the amount, the Omise charge (chrg_...) and how it was confirmed (checkout, 3-D Secure return, webhook, payment retry, manual capture or manual sync).

Authorized Status (default Pending): the card was authorized with Authorize only. Use Capture payment or Void authorization.

Awaiting Payment Status (default Pending): Omise has not confirmed the payment yet. The webhook or Sync payment status updates the order.

On Hold (Review) Status (default Pending): the charge amount or currency differs from the order, for example the order was changed during 3-D Secure. The note shows both values. Check the order and fulfil it or refund the payment.

Failed Status (default Failed): a pending payment failed later. A paid order is never downgraded by a later failed event.

Canceled Status (default Canceled): the charge expired or the authorization was voided.

Refunded Status (default Refunded): the payment was fully refunded through the extension.

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

Notes are entries in the order History that the customer does not see.

VibeFox Omise Payment tab

In Sales > Orders open an order paid with Omise. At the bottom of the order page, next to History and Additional, the VibeFox Omise Payment tab shows the charge ID with a Test label for test payments, the payment action, the charge status, the card brand and last digits, the amounts Charged / order / refunded, the buttons, the refund form, the refund history and the Omise notes of the order. The tab is shown to users who have access to the extension. The buttons need the right to modify the extension (set in System > Users > User Groups) and the secret key of the mode the payment was made in. The result of each action is shown in the tab.

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

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

Sync payment status: reads the charge from Omise again, for example after a capture or refund in the Omise dashboard, updates the order and adds a note with the charge status and the total refunded at Omise.

Status changes made from the tab do not notify the customer and do not move stock, like a manual status change.

Refunds

In the tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), 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 Status; 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 tab shows Refund failed. with the Omise message, and no refund is recorded.

Product returns in Sales > Returns do not send money back through Omise. Refunds made in the Omise dashboard are not recorded in OpenCart; Sync payment status shows the refunded total.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Omise Payment is the first block on Extensions > Extensions > Payments > VibeFox Omise Payment > Edit, 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 store. Below them are the line Product: opencart-payment-omise and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 customer pays in one of the supported currencies. The settings page shows a warning when keys are missing. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status or in the Awaiting Payment Status: 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 store for that order. 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 status could not be set, retry later: the order status could not be set at that moment. Omise retries the webhook. 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 in the review status after payment: read the notes in the VibeFox Omise Payment tab (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 Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Omise Payment. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the webhook and the 3-D Secure return through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, test mode, keys, payment action, webhook and logging options) and the debug log are removed. If it is off, they are kept for a later re-install. The Omise charges and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Omise Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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