VibeFox KOMOJU for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

HTTPS: your site needs HTTPS, and KOMOJU must be able to reach the webhook URL.

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.

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

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_komoju_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > KOMOJU Payment > 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. In the KOMOJU dashboard add a webhook with the URL shown on the settings page and the events listed there, and copy its secret token (see Configuration).

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

Configuration

All settings are on one page: WooCommerce > Settings > Payments > KOMOJU Payment. Above the fields 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 the store currency is not supported. In the list of payment methods, KOMOJU is marked as needing setup until the current mode has a secret key, and shows a test mode badge while sandbox mode is on.

General

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

Title: the payment method name customers see at checkout. Default: KOMOJU Payment.

Description: the text shown under the payment method at checkout. Default: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

Live API keys

Find the keys in the KOMOJU dashboard: the secret key under Settings > API keys, the webhook secret token under Settings > Webhooks (add the webhook URL shown below 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. Orders keep the mode they were paid 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 checkout 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.

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 of the settings, for live and for test mode. It looks like https://your-site/wc-api/komoju_p_webhook/. If your site uses a language prefix in URLs, 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:

payment.authorized: the payment slip was issued (konbini, bank transfer) or the payment was authorized. The order is put on hold until the customer pays.

payment.captured: the payment was completed. The order is marked paid after the amount and currency check.

payment.expired: the payment slip expired. The order is cancelled.

payment.cancelled: the payment was cancelled. The order is cancelled.

payment.failed: the payment failed. The order becomes Failed, and the customer can try again.

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

payment.refunded: the payment was refunded. The refund is recorded in WooCommerce.

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

Advanced

Invoice Prefix: the prefix for order numbers sent to KOMOJU. If you use several stores with the same KOMOJU account, make it unique for each store. Default: WC-.

Enable Logging: Log KOMOJU events and API calls in WooCommerce > Status > Logs, source wcp_komoju_payment, without keys or customer data. Errors are always logged. Default: off.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. Order data (KOMOJU payment IDs in orders) is always kept. Default: off.

Checkout

The customer chooses the payment method (by default KOMOJU Payment) and places the order. The plugin creates a KOMOJU payment session for the order total in the order currency and sends the customer to the KOMOJU payment page. The billing e-mail, name, billing and shipping addresses and the ordered items are passed to KOMOJU. The page is shown in Japanese, English or Korean, depending on the site 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.

After paying, the customer returns to your store. The plugin reads the payment session from the KOMOJU API with the key of the order's mode. The order is marked paid only after KOMOJU confirms it: by the signed webhook or by the session read when the customer returns. If KOMOJU cannot be reached at that moment, the customer goes to the order received page with 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.

For konbini and bank transfer payments, the customer gets a payment slip. The order is put on hold and is completed when the customer pays and KOMOJU sends the webhook. If the slip expires, the order is cancelled.

If the payment was not completed, the customer returns to the Pay for order page with The payment was not completed. You can try again or choose another payment method. A new attempt reuses the open KOMOJU session if the total is unchanged. A session with an old total is cancelled in KOMOJU, and a session that was paid in the meantime confirms the order. When an unpaid order is cancelled (by you, the customer or the WooCommerce hold stock timer), its open KOMOJU session is cancelled too, so it can no longer be paid.

If KOMOJU cannot start the payment, the customer sees a short message, 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 details are added to the order notes and the log.

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 has no card form on your site, saved cards or subscriptions. The plugin 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 on hold until then.

Orders and refunds

Order statuses

Pending payment: the customer was sent to KOMOJU and has not paid yet, or KOMOJU has not confirmed the payment yet.

Processing or Completed: KOMOJU confirmed the payment. WooCommerce sets the usual status for a paid order. The order note shows the KOMOJU payment ID, the payment method and how it was confirmed (webhook or return). The transaction ID is the KOMOJU payment ID, and on the order screen it links to the payment in the KOMOJU dashboard.

On hold: a konbini or bank transfer slip was issued and waits for payment, or a payment waits for capture in the KOMOJU dashboard. An order is also put on hold when the amount or currency did not match the order, or when a payment was captured after the order had been cancelled. The order note explains it. Fulfil the order or refund the payment.

Failed: the payment failed. The customer can try again.

Cancelled: the payment slip expired or the payment was cancelled.

Refunded: the payment was fully refunded, from WooCommerce or in the KOMOJU dashboard.

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

Refunds

Open the order, click Refund, enter the amount and click Refund via KOMOJU Payment. Full and partial refunds are supported. The refund is sent with the key of the mode the order was paid in, so that mode's secret key must be set. The plugin 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 order notes.

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

Refunds made in the KOMOJU dashboard arrive by webhook and are recorded as WooCommerce refunds automatically. A full refund sets the order to Refunded. Partial refunds made in the dashboard for payments converted into another currency are only noted on the order: record the matching amount in WooCommerce with "Refund manually".

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > KOMOJU Payment. 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, 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. 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 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

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 store currency must be supported by KOMOJU. The settings page shows a warning when something is missing.

The payment went through, but the order stays Pending payment: 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 settings 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 WooCommerce > Status > Logs, source wcp_komoju_payment. Card payments are also confirmed when the customer returns to your shop, 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 order was paid in. Use separate webhooks and tokens for live and test mode.

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 checked at that moment. KOMOJU retries the notification.

Order is On hold: read the order note. 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.

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

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.

Developers can change the list of currencies with the filter komoju_p_supported_currencies and the payment session, for example the payment methods, with the filter komoju_p_session_params.

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. Existing orders keep their payment notes and transaction IDs.

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