VibeFox KOMOJU for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

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

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

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

On install the module creates two order statuses, Awaiting KOMOJU payment and KOMOJU payment on hold. PrestaShop links a new payment module only to the countries active at that moment: a country you enable later must be ticked for the module in Payment > Preferences. There you can also limit currencies and customer groups.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox KOMOJU Payment > Configure. Each section has its own Save button, which saves the whole page. 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 KOMOJU does not support the default currency of the shop (the payment method is then hidden for carts in that currency).

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.

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

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.

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

Webhook URL

The webhook tells your shop 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. With friendly URLs it looks like https://your-shop/module/wcp_komoju_payment/webhook, possibly with a language code such as /en/. 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 is created in Awaiting KOMOJU payment.

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. An existing order goes to Payment error; without an order nothing is created.

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 shop, but konbini and bank transfer payments are never confirmed.

Advanced

Invoice Prefix: the prefix for the order numbers sent to KOMOJU, followed by the cart number. If you use several shops with the same KOMOJU account, make it unique for each shop. Default: PS-.

Enable Logging: writes KOMOJU events and API calls to logs/komoju_p_debug.log.php in the module folder. 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 module removes the gateway settings and the log. Orders, the KOMOJU transactions and refunds and the order statuses always stay, so old orders can still be confirmed and refunded after a re-install. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default KOMOJU Payment) and confirms. The module creates a KOMOJU payment session for the cart total in the cart currency and sends the customer to the KOMOJU payment page. The 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 language of the cart (English for other languages). There the customer chooses a payment method. Which methods are offered depends on your KOMOJU account and the cart currency. No order exists yet at this point.

After paying, the customer returns to your shop. The module 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 is then created and the customer sees the standard order confirmation page with Your payment with KOMOJU has been received. If KOMOJU cannot be reached at that moment, 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 is created in Awaiting KOMOJU payment, and the confirmation page tells the customer to complete the payment as instructed by KOMOJU (for example at a convenience store or by bank transfer). The order becomes Payment accepted when the customer pays and KOMOJU sends the webhook. If the slip expires or the payment fails later, the confirmation page shows Your KOMOJU payment was not completed. Please contact us about this order.

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. The cart is kept. 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 creates the order instead of a new payment.

If KOMOJU cannot start the payment, the customer stays at checkout with 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 technical reason is written to the log.

If a voucher in the cart stops being valid between the payment and its confirmation, PrestaShop removes it from the order. The order then goes to KOMOJU payment on hold with a note, because the customer paid the price with the discount.

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

The module 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 until then.

Orders and refunds

Order statuses

No order yet: the customer was sent to KOMOJU and has not paid, or KOMOJU has not confirmed the payment yet. Only the cart exists.

Payment accepted: KOMOJU confirmed the payment. The payment is recorded with the KOMOJU payment ID as the transaction ID, and a note shows the payment ID, the payment method and how it was confirmed (webhook or return).

Awaiting KOMOJU payment: 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: KOMOJU reported a different amount or currency than the order total (for example, the cart was changed after the payment started), a voucher was removed, 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.

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

Payment error: a payment of an existing order failed.

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

KOMOJU payment block

The order page shows a KOMOJU payment block with the KOMOJU payment ID (linked to the payment in the KOMOJU dashboard) and the payment method, the session, the order number at KOMOJU, the status, the amount paid and the amount refunded, a Test mode badge for test payments, the refund history and the KOMOJU notes of the order.

Refunds

In the KOMOJU payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, 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 edit orders. 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 module 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. 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 cart), only a full refund is possible from PrestaShop. Make partial refunds in the KOMOJU dashboard.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page 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. Partial refunds made in the dashboard for payments converted into another currency are only noted on the order: record the matching amount in PrestaShop manually (credit slip).

License key

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

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 cart currency must be supported by KOMOJU. The settings page shows a warning when something is 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: 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 module page. 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 payment was made in. Use separate webhooks and tokens for live and test mode, and check that they are not swapped.

Webhook answers Order is busy, retry later. or Temporary error, retry later.: the order was being updated by another request, the order could not be created at that moment (for example, the module is disabled), or the payment could not be checked. 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 KOMOJU payment on hold or Awaiting KOMOJU payment: read the KOMOJU notes in the order block. A slip is waiting for payment, a payment waits for capture in the KOMOJU dashboard, the amount or currency did not match, a voucher was removed, or the payment came after the order was cancelled.

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.

Developers can change the list of currencies with the hook actionKomojuPSupportedCurrencies and the payment session, for example the payment methods, with the hook actionKomojuPSessionParams.

Uninstall

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

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