VibeFox Omise for Adobe Commerce — ヘルプ

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

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: the order currency must be 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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-omise-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/OmisePayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_OmisePayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Omise Payment. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter your Omise test and live keys and add the webhook URL shown in the settings in the Omise dashboard (see Configuration). Set Enable Omise to Yes and click Save Config. Test a payment in test mode with an Omise test card such as 4242 4242 4242 4242, then set Test Mode to No.

The module adds the Credit / Debit Card payment method to the Magento checkout. It is off after installation (Enable Omise = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Omise charges and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Omise Payment, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title of 1 to 128 characters.); a Sort order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be zero or greater.).

The payment method is shown at checkout only when both keys of the current mode are set: the test public and secret keys in test mode, the live keys in live mode.

General

Enable Omise: shows or hides the payment method at checkout. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit / Debit Card. Required, at most 128 characters. While test mode is on, (TEST MODE) is added after the title.

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

Sort order: the position among the payment methods at checkout. A whole number.

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_.

Test Mode: uses the test keys, no real charges. It switches both keys. While it is on, customers see Test mode: no real payment is taken. under the description. Captures, refunds and status checks of an order always use the keys of the mode the order was paid in. Default: Yes.

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_...

Magento stores the secret keys encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete a saved secret key, clear the field and click Save Config. A key with the wrong prefix, for example a test key in a live field, is not saved: the previous value is kept, the other fields are saved and Magento shows the warning Wrong Omise key prefix. Previous key was kept; other valid fields were saved.

Payment

Payment action: what happens to the card amount.

Per-charge webhook: sends the webhook URL of the store with every charge. Useful when several stores share one Omise account. Omise accepts per-charge endpoints only on HTTPS; otherwise the webhook of the Omise dashboard is used. Default: No.

Conditions

Payment from Applicable Countries: All Allowed Countries offers the payment method for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer the payment method only for billing addresses in these countries.

Minimum Order Total: offer the payment method only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer the payment method only up to this order total, in the base currency. Empty means no maximum.

Webhook

Webhook and payment status: shows the webhook URL of your store. It is the storefront address of the default store view and looks like https://your-store/wcpomisepayment/webhook/index/. 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:

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 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 stays in Pending Payment, and captures made in the Omise dashboard are not picked up until you click Sync payment status on the order.

Advanced

Debug Log: writes API requests and payment events to var/log/omise_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Keys, tokens and customer e-mail addresses are not logged. Default: No. Nothing is written while it is off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the settings, the module cache and the log (see Uninstall). The license key is always removed. The Omise charges and refunds always stay, so old orders can still be refunded. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Credit / Debit Card) and fills in the card form: Cardholder name, Card number, Expiry month, Expiry year and Security code. When the customer clicks Place 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 store. If Omise does not accept the card data, the customer sees the Omise message above the form and can correct it. If Omise.js cannot be loaded, the message is The secure card service could not be loaded. Please try again.

Magento then places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. Your store creates the charge with the secret key for the order total in the order currency. The charge description at Omise is your store name and the order number (for example "Your Store order #000000123"), and the order and cart IDs are 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. Magento then creates the invoice with the Omise charge ID, the order goes to Processing, the order e-mail is sent and the customer sees the standard order success page. With Authorize only the order goes to Processing without an invoice and the order e-mail is sent. If the payment cannot be confirmed right after 3-D Secure, a Payment confirmation page shows Your payment is being confirmed. Do not pay again until its status is known. and a Check again link. The webhook confirms the order as soon as it arrives. A customer who comes back in another browser lands on the home page.

If the card is declined or 3-D Secure fails, the order is cancelled (the stock goes back), the cart is restored and the customer sees The Omise payment was not completed. You can try again. in the cart. If the payment cannot be started, the customer sees Omise could not start payment. Please check your order before retrying. in the cart; when no charge was attempted, the order is cancelled and the cart is restored. If the answer of Omise is lost while the charge is created, the order is put On Hold with a note, the customer sees Your Omise payment requires review. Do not pay again., and you check the charge in the Omise dashboard.

A retry never charges twice: before a new charge for the same cart, the previous charge is read again. If it is already paid or authorized, it is applied to its order and no new charge is made. An unfinished 3-D Secure attempt is expired before a new charge. If a second charge is still paid for a cart that already has a payment, a note asks you to review it in the Omise dashboard.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its unfinished Omise charge is expired.

The module works with the standard Magento checkout. It 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. The payment method is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed, but Omise has not confirmed the payment yet, for example the customer is on 3-D Secure. There is no invoice.

Processing (paid): the payment was confirmed. The invoice is created with the Omise charge ID as the transaction ID, and a note shows the charge and how it was confirmed (checkout, return, webhook, retry or sync).

Processing (authorized): the card was authorized with Authorize only. There is no invoice yet. A note says to capture the payment with an invoice or to cancel the order to void it.

On Hold: the charge amount or currency differs from the order, the answer of Omise was lost while the charge was created, or the bank page address was not valid. No invoice is created. The note says what to check. Review the charge in the Omise dashboard.

Canceled: the card was declined, 3-D Secure failed, the charge expired, the authorization was voided, or the order was cancelled in Magento.

Closed: the payment was fully refunded with a credit memo.

If a paid or authorized charge arrives for an order that is already Canceled or Closed, the order is not reopened. A note asks you to review it in the Omise dashboard. The notes are order comments that the customer does not see.

Omise payment information

The payment information of the order (Sales > Orders > View) shows the payment method title and, after the charge, Omise charge (the charge ID), Environment (test or live), Card brand and Last four digits.

Below the order information the section VibeFox Omise Payment lists the charges of the order with the environment, the status and the amount charged and refunded as Omise reports them (in the smallest currency unit, for example satang), and the refund history. It is shown also when the module is disabled.

Sync payment status: reads the charge from Omise with the key of its mode and updates the order. The note also shows the total refunded at Omise. It needs the right to edit orders.

Refund actual charge: shown only for an order On Hold after a mismatch, which has no invoice. Enter the amount and, optionally, a reason. It refunds at most what Omise actually charged; the order stays On Hold, so you settle it in Magento manually. It needs the credit memo right.

Capture and void

With Authorize only, open the order and click Invoice. Choose Capture Online and submit the invoice: the full authorized amount is captured at Omise and the invoice is created. Partial capture is not possible. To void an authorization, cancel the order: the authorization is reversed at Omise and no money is captured.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Omise. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Omise.

The refund is made in the order currency, up to the amount Omise charged minus the amounts already refunded at Omise. For JPY, which has no decimals, the amount is rounded to whole yen so that a full refund equals the charge. The refund is sent in the mode the payment was made in, so that mode's secret key must be set. The reason entered as the credit memo comment is sent with the refund. If Omise does not accept the refund, Magento shows the error and the credit memo is not created. After a successful refund Magento records it with the Omise refund ID as the transaction ID. A full refund closes the order. If the result of a refund is not known, the next online refund of the order is blocked until you reconcile it with the Omise dashboard.

Refunds made in the Omise dashboard are not recorded in Magento. Sync payment status shows the total refunded at Omise in a note. Create a credit memo with Refund Offline or update the order manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Omise Payment is the first row of the VibeFox Omise Payment group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-omise and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the payment method is not shown to customers at checkout. If a payment is started anyway, no charge is made, the order is cancelled, the cart is restored and the customer sees Omise could not start payment. Please check your order before retrying. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and captures, voids, refunds and Sync payment status work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Credit / Debit Card does not appear at checkout: check that the license is active and Enable Omise is Yes for the website of the store, that both keys of the current mode are entered (test keys in test mode, live keys otherwise) and that the order currency is one of the supported currencies. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the webhook is not working. In the Omise dashboard check that the webhook URL is exactly the one shown in Webhook and payment status and uses HTTPS. On the order click Sync payment status. Turn on Debug Log to see the webhook answers.

Webhook answers unknown charge or wrong reference: the charge in the event was not created by this store for that order. Nothing is changed.

Webhook answers retry (HTTP 503): 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.

The webhook URL shows POST required in the browser: this is normal. The URL accepts only requests from Omise.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Omise retries the webhook later; you can also click Sync payment status on the order.

Warning on save: Wrong Omise key prefix: 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_.

Place Order shows Invalid Omise token or environment. Re-enter your card details.: the card token belongs to the other mode, for example Test Mode was switched while the customer was at checkout. The customer reloads the page and enters the card again.

The customer is back in the cart with Omise could not start payment: turn on Debug Log and look at the Log field. Wrong keys or a missing key of the current mode are the usual reasons.

Order is On Hold after payment: read the order notes (see Order statuses), then fulfil the order or refund the payment.

Refund fails with Refund exceeds the actual remaining Omise charge.: the amount is larger than what is left of the charge at Omise, for example after a refund in the Omise dashboard. Click Sync payment status to see the total refunded at Omise.

Refund fails with Omise refund failed. Check the dashboard before retrying.: Omise rejected the refund or could not be reached. Check the charge in the Omise dashboard before you try again. The secret key of the mode the payment was made in must be set.

Refund fails with An earlier refund requires manual reconciliation before another refund.: the result of an earlier refund is not known. Compare the refunds in the Omise dashboard with the credit memos of the order.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An authorized order has no invoice yet: capture it first, or cancel the order to void the authorization.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_OmisePayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_OmisePayment to remove the data, then bin/magento module:disable Vibefox_OmisePayment, delete the folder app/code/Vibefox/OmisePayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the settings, the module cache and the log are removed too. If it is No, the settings are kept for a 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 invoices, payment notes and transaction IDs.

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