VibeFox KOMOJU 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.

KOMOJU account: you need the secret key (sk_live_... and, for test mode, sk_test_...) and the secret token of a webhook created in the KOMOJU dashboard (see Configuration). The publishable key is not needed. KOMOJU must be able to reach the webhook URL of your store.

Order currency: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD or VND. For orders in other currencies the payment method is hidden.

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_komoju_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_komoju_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_komoju_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 KOMOJU 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. In the KOMOJU dashboard add a webhook with the URL and the events shown in the Webhook URL section, and copy its secret token (see Configuration).

5. Enter the live secret key and live webhook secret token, and the test ones for sandbox mode. Turn on Enable/Disable and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_komoju_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 KOMOJU Payment, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the webhook and the keys 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 Webhook URL).

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

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox KOMOJU 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 KOMOJU Sandbox Mode is enabled. while test mode is on. It warns you when the current mode has no secret key (the payment method is then hidden at checkout) or no webhook secret token (KOMOJU notifications are then rejected, so konbini and bank transfer payments are never confirmed), and when KOMOJU does not support the default currency of the store (the payment method is then hidden for orders in that currency). Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must be at most 128 characters, Sort Order must be a whole number (negative numbers are allowed), Total a number, 0 or greater, and the geo zone and order statuses must exist. Otherwise nothing is saved and the page names the field. Missing keys do not block saving.

KOMOJU Payment

Enable/Disable: Enable KOMOJU Payment Gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: KOMOJU Payment. If you leave it empty, the default name is used. At most 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

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

Geo Zone: offer KOMOJU only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

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

Live API keys

Find the keys in the KOMOJU dashboard (the section links there): the secret key under Settings > API keys, the webhook secret token under Settings > Webhooks (add the webhook URL shown in the Webhook URL section there first).

Live Secret Key: your KOMOJU live secret key. It starts with sk_live_.

Live Webhook Secret Token: the secret token of the live webhook. It is used to verify the signature of every notification.

Test mode

KOMOJU uses the same API address for test and live payments: the key decides. Payments keep the mode they were made in, so refunds and status checks of an order always use the key of that mode.

Sandbox Mode: Enable test mode (use the test keys below, no real payments). Default: off. While it is on, the Confirm Order step shows Test mode above the description.

Sandbox Secret Key: your KOMOJU test secret key. It starts with sk_test_.

Sandbox Webhook Secret Token: the secret token of the test-mode webhook.

Saved keys and tokens 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 value, tick Clear the saved value on save under the field and click Save.

Webhook URL

The webhook tells your store about payments, including delayed konbini and bank transfer payments. In the KOMOJU dashboard under Settings > Webhooks, add the URL shown in this section, for live and for test mode. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_komoju_payment/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_komoju_payment/payment/wcp_komoju_payment.webhook. It is built from the storefront address of your OpenCart installation. Copy the URL exactly as the settings show it. Then copy the secret token of each webhook into Live Webhook Secret Token or Sandbox Webhook Secret Token.

Select these events (they are also listed in this section):

payment.authorized: the payment slip was issued (konbini, bank transfer) or the payment was authorized. The order gets Awaiting KOMOJU Payment Status.

payment.captured: the payment was completed. The order gets Order Status After Payment after the amount and currency check.

payment.expired: the payment slip expired. An awaiting order gets Cancelled Payment Status.

payment.cancelled: the payment was cancelled. An awaiting order gets Cancelled Payment Status.

payment.failed: the payment failed. An awaiting order gets Failed Payment Status; an order without a status keeps no status.

payment.refund.created: a refund was made, for example in the KOMOJU dashboard. It is recorded on the order.

payment.refunded: the payment was refunded. The refund is recorded on the order.

Expired, cancelled and failed events change the order only for its current payment, so a payment of an earlier attempt cannot cancel an order that is being paid another way. Webhooks without a valid signature are rejected. Webhooks signed with either secret token are accepted, but only for payments of the same mode. Without the webhook, card payments are still confirmed when the customer returns to the store, but konbini and bank transfer payments are never confirmed.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after KOMOJU has confirmed the payment. Each field below lists your OpenCart order statuses.

Order Status After Payment: the payment was captured, and the amount and currency were verified. Default: Processing.

Awaiting KOMOJU Payment Status: the payment is authorized: a konbini slip or bank transfer was issued, or the payment waits for capture in the KOMOJU dashboard. Default: Pending.

KOMOJU Payment On Hold Status: the paid amount or currency differs from the order, or the payment arrived after the order was cancelled. A note explains why. Default: Pending, because OpenCart has no On hold status.

Cancelled Payment Status: the payment of an awaiting order expired or was cancelled, for example the konbini slip was not paid in time. Default: Canceled.

Failed Payment Status: the payment of an awaiting order failed. Default: Failed.

Refunded Status: set after the payment is fully refunded, from the order page or in the KOMOJU dashboard. Default: Refunded.

You can create your own statuses, for example Awaiting KOMOJU payment or On hold, in System > Localisation > Order Statuses and select them here.

Advanced

Invoice Prefix: the prefix for the order numbers sent to KOMOJU. The number at KOMOJU is the prefix, the OpenCart order number and a short random suffix, for example OC-123-A1B2C3. If you use several stores with the same KOMOJU account, make it unique for each store. Default: OC-.

Enable Logging: writes KOMOJU events and API calls to komoju_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. Keys and customer data are not logged. Errors and warnings are always written. Default: off.

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 gateway settings and the log. Orders and the KOMOJU transactions and refunds always stay, so old orders can still be confirmed and refunded after a re-install. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Secret keys and webhook tokens 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 KOMOJU Payment). At the Confirm Order step the customer sees your description and the note You will be redirected to the KOMOJU payment page to complete the payment. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension creates a KOMOJU payment session for the order total in the order currency and sends the customer to the KOMOJU payment page. The e-mail, name, payment and shipping addresses and the ordered items are passed to KOMOJU. The page is shown in Japanese, English or Korean, depending on the customer's language (English for other languages). There the customer chooses a payment method. Which methods are offered depends on your KOMOJU account and the order currency.

On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. By default OpenCart 4 does not ask for a payment address; the extension then passes the shipping address as the payment address.

After paying, the customer returns to your store. The extension reads the payment session from the KOMOJU API with the key of the payment's mode. The order is marked paid only after KOMOJU confirms it: by the signed webhook or by the session read when the customer comes back. 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 payment with KOMOJU has been received. If KOMOJU cannot be reached at that moment, or the payment is confirmed but not applied yet, a Payment confirmation page shows We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes. and a Check again button.

For konbini and bank transfer payments the customer gets a payment slip. The order gets Awaiting KOMOJU Payment Status, and the success page tells the customer that the payment is authorized and must be completed as instructed by KOMOJU (for example at a convenience store or by bank transfer). The order moves to Order Status After Payment when the customer pays and KOMOJU sends the webhook. If the slip expires, the order moves to Cancelled Payment Status.

If the payment was not completed, the customer is back at checkout with The payment was not completed. You can try again or choose another payment method. If the order was already cancelled, the message is The KOMOJU payment was not completed and the order has been cancelled. The cart is kept. On OpenCart 4 these messages are shown above the checkout page. Each new attempt (OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout and pays the same order again) checks the open KOMOJU sessions of this order and of other orders of the same cart: the open session of this order with an unchanged total is reused, other open sessions are cancelled in KOMOJU, and a session that was paid in the meantime confirms its order instead of a new payment. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed meanwhile (for example its konbini slip expired, its payment failed or you cancelled it), the customer is sent back to the checkout with Your previous order was cancelled or its payment failed. Please confirm the order again. If the order is already placed and the cart now holds other products, the message is Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. In both cases the next Confirm Order pays a new order of the cart.

If KOMOJU cannot start the payment, the customer stays at the Confirm Order step with a short message above the button, for example KOMOJU could not accept this payment: with the reason, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. or Payment error: Could not connect to KOMOJU. Please try again in a moment. The technical reason is written to the log.

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

The extension has no card form on your site, saved cards or subscriptions. It does not restrict the payment methods: they are chosen on the KOMOJU page. It has no manual capture action: payments authorized for manual capture must be captured in the KOMOJU dashboard, and the order stays in Awaiting KOMOJU Payment Status until then.

Orders and refunds

Order statuses

No status (missing order): the customer was sent to KOMOJU and has not paid, or KOMOJU has not confirmed the payment yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): KOMOJU confirmed the payment. A note shows the KOMOJU payment ID, the payment method and how it was confirmed (webhook or return).

Awaiting KOMOJU Payment Status (default Pending): a konbini or bank transfer slip was issued and waits for payment, or a payment waits for capture in the KOMOJU dashboard.

KOMOJU Payment On Hold Status (default Pending): KOMOJU reported a different amount or currency than the order total, or the payment was captured after the order had been cancelled. The note explains it. Check the order and fulfil it or refund the payment.

Cancelled Payment Status (default Canceled): the payment slip expired or the payment was cancelled.

Failed Payment Status (default Failed): the payment of an awaiting order failed.

Refunded Status (default Refunded): the payment was fully refunded, from the order page or in the KOMOJU dashboard.

If a second payment is captured for an order that is already paid, or for another order of a cart that is already paid, the order is not changed. A note asks you to refund it in the KOMOJU dashboard if it is a duplicate. Refunded orders are never reopened.

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

VibeFox KOMOJU Payment tab

In Sales > Orders open an order paid with KOMOJU. At the bottom of the order page, next to History and Additional, the VibeFox KOMOJU Payment tab shows the KOMOJU payment ID (linked to the payment in the KOMOJU dashboard) with a Test mode label for test payments, the payment method, the session, the order number at KOMOJU, the status, the amounts Paid / refunded, the refund form, the refund history (from OpenCart or the KOMOJU dashboard) and the KOMOJU notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox KOMOJU Payment tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), and click Refund via KOMOJU. Confirm the question Refund this amount through KOMOJU? This cannot be undone. Full and partial refunds are supported. You need the right to modify the extension (set in System > Users > User Groups). Refunds are limited to the amount KOMOJU actually charged, so after an amount mismatch you can refund up to what the customer paid, not the order total. The refund is sent with the key of the mode the payment was made in, so that mode's secret key must be set. The extension first checks the payment in KOMOJU and refuses refunds above the amount still refundable. If KOMOJU cannot refund a payment automatically (some methods, for example konbini, need the customer's bank details), KOMOJU's error message is shown and nothing is recorded: handle such refunds in the KOMOJU dashboard. A refund counts as done only when KOMOJU confirms it. A successful refund is added to the refund history and the notes. A full refund sets the order to Refunded Status without returning products to stock, like a manual status change. A partial refund does not change the status. Refunds are available once KOMOJU has captured the payment.

For payments that KOMOJU converted into another currency (for example konbini in JPY for a EUR order), only a full refund is possible from OpenCart. Make partial refunds in the KOMOJU dashboard.

Product returns in Sales > Returns do not send money back through KOMOJU.

Refunds made in the KOMOJU dashboard arrive by webhook and are added to the refund history with a note. When the whole payment is refunded, the order is set to Refunded Status. Partial refunds made in the dashboard for payments converted into another currency are only noted on the order: record the matching amount in OpenCart manually.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox KOMOJU Payment is the first block on Extensions > Extensions > Payments > VibeFox KOMOJU 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-komoju 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, KOMOJU 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

KOMOJU does not appear at checkout: check that the license is active, Enable/Disable is on and the current mode has a secret key: Sandbox Secret Key in sandbox mode, Live Secret Key in live mode. The customer must pay in a currency supported by KOMOJU. The settings page shows a warning when something is 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: the webhook is not working. In the KOMOJU dashboard check that the webhook exists for the mode you use, that its URL is exactly the one shown in the Webhook URL section and that the events are selected. Check that its secret token is in the matching field (Live Webhook Secret Token or Sandbox Webhook Secret Token), and look at the Log field on the extension page. Card payments are also confirmed when the customer returns to your store, but konbini and bank transfer payments are confirmed only by the webhook.

Webhook answers Failed to verify KOMOJU webhook signature.: the secret token is missing or belongs to another webhook. KOMOJU retries the notification.

Webhook answers Mode mismatch, ignored.: the webhook was signed with the secret token of the other mode than the payment was made in. Use separate webhooks and tokens for live and test mode, and check that they are not swapped.

Webhook answers Order not found.: the payment does not belong to an order of this store, for example it was made by another store with the same KOMOJU account. The event is ignored.

Webhook answers Order is busy, retry later. or Temporary error, retry later.: the order was being updated by another request, or the payment could not be processed at that moment. KOMOJU retries the notification. The reason is in the log.

The webhook URL shows an error in the browser: this is normal. The URL accepts only signed requests from KOMOJU.

Order is in the on hold or awaiting status: read the KOMOJU notes in the order tab. A slip is waiting for payment, a payment waits for capture in the KOMOJU dashboard, the amount or currency did not match, or the payment came after the order was cancelled.

No refund form in the tab: the tab says why: KOMOJU has not captured the payment yet, it is fully refunded, your user group has no right to modify the extension, or the secret key of the payment's mode is not set.

Refund fails: read the message. The secret key of the mode the payment was made in may be missing, the payment may not be refundable automatically (refund it in the KOMOJU dashboard), KOMOJU may not know the payment with the configured key, or only a full refund is possible for a converted payment.

For developers: the extension triggers the OpenCart events komoju_p_supported_currencies (to change the list of currencies) and komoju_p_session_params (to change the payment session, for example the payment methods).

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox KOMOJU 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 customer's return through in maintenance mode). If Delete data on uninstall is on, the other gateway settings (title, description, keys, webhook tokens, sandbox mode, invoice prefix, logging) and the log are removed. If it is off, they are kept for a later re-install. The KOMOJU transactions and refunds are always kept, so old orders can still be confirmed and 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 KOMOJU Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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