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

KOMOJU account: you need the secret key (sk_live_... and, for sandbox 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. KOMOJU is hidden at checkout when the customer shops in another currency.

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-komoju-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/KomojuPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_KomojuPayment 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 KOMOJU 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. In the KOMOJU dashboard add a webhook with the URL and the events shown in Webhook URL and setup, and copy its secret token (see Configuration). Enter the live secret key and live webhook secret, and the sandbox ones for testing. Set Enable to Yes and click Save Config. Test a payment with Sandbox Mode = Yes, then set it to No.

The module adds the KOMOJU Payment payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the KOMOJU payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox KOMOJU 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 for the default store view. 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: a Sort Order that is not a whole number of 0 or more (Sort Order must be a non-negative integer.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or more (Order total must be a non-negative number.).

While Enable is Yes, the Webhook URL and setup row warns you: No secret key for the current mode: KOMOJU is hidden at checkout., No webhook secret: delayed payments cannot be confirmed. and, while sandbox mode is on, KOMOJU Sandbox Mode is enabled. No real payments will be processed.

General

Enable: shows or hides KOMOJU at checkout. It is shown only when the secret key of the current mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. An empty title is saved as the default. Default: KOMOJU Payment.

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

Mode and 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 there first, see below). 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, also after you switch.

Sandbox Mode: Yes uses the sandbox keys below, and no real payments are taken. New payments use the current mode. Default: No. While it is on, customers see Test mode: no real payment is taken. under the payment method.

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

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

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

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

Magento stores the keys and secrets encrypted and shows only a mask (******) after saving. Leave the mask or an empty field as it is to keep the saved value, type a new value to change it. To delete a saved key or secret, set the Clear row under it (Clear live secret key, Clear live webhook secret, Clear sandbox secret key, Clear sandbox webhook secret) to Yes and click Save Config. The Clear rows go back to No after saving.

Webhook URL and setup

The webhook tells your store about payments, including delayed konbini and bank transfer payments. This row shows the webhook URL: the storefront address of the default store view, which looks like https://your-store/wcpkomojupayment/webhook/index. Copy the URL exactly as the settings show it. In the KOMOJU dashboard under Settings > Webhooks, add it for live and for test mode, then copy the secret token of each webhook into Live Webhook Secret or Sandbox Webhook Secret. The signature is checked with the secrets saved for the store view of the order, so enter them in the Default Config or for the website of that store.

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

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

Invoice Prefix: the prefix of the order reference sent to KOMOJU. The reference is the prefix, the Magento order number, a dash and six random characters, unique for each payment attempt. If several stores use the same KOMOJU account, make the prefix unique for each store. Default: MG-.

Conditions

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

Payment from Specific Countries: offer KOMOJU only for billing addresses in these countries.

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

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

Sort Order: the position among the payment methods at checkout. A whole number. Default: 0.

Advanced

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

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. Order, payment and refund history is always retained. Default: No.

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

Checkout

At the payment step the customer chooses the payment method (by default KOMOJU Payment) and sees the description and the note You will be redirected to KOMOJU to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then 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, billing and shipping addresses and the ordered items are passed to KOMOJU. The page is shown in Japanese, English or Korean, depending on the locale of the store view (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 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. Magento then creates the invoice with the KOMOJU payment ID, sets the order to Processing and sends the order e-mail. The customer sees the standard order success page with Your KOMOJU payment has been received. If KOMOJU cannot be reached at that moment, the success page shows Your KOMOJU payment is awaiting confirmation. Complete the payment at the convenience store or by bank transfer if required., and the webhook confirms the order later. A customer who comes back in another browser lands on the home page with the message.

For konbini and bank transfer payments the customer gets a payment slip from KOMOJU. The order moves to Processing without an invoice and gets the note KOMOJU authorized: waiting for the customer to pay … with the payment deadline; the success page shows the same awaiting-confirmation message. No money is captured yet, so do not ship the order before it is invoiced. The order is invoiced when the customer pays and KOMOJU sends the webhook. If the slip expires or the payment fails or is cancelled, the order is cancelled.

If the customer comes back without paying, the open KOMOJU session is cancelled, the order is cancelled (the stock goes back) and the customer is back in the cart with The KOMOJU payment was cancelled or failed. You can choose another payment method. The cart is restored, and the next attempt gets a new order and a new KOMOJU session. If the payment page of the same order is opened again, the open session is reused when the total, currency and mode are unchanged. A session that was paid in the meantime is confirmed instead of starting a new payment.

If KOMOJU refuses to start the payment, the order is cancelled, the cart is restored and the customer sees KOMOJU could not create the payment session. Check the payment before trying again. in the cart. If KOMOJU payments are not available for the order (for example, no secret key for the current mode), the message is KOMOJU payments are temporarily unavailable. Please choose another payment method. If KOMOJU could not be reached, it is unknown whether the session was created: the order stays in Pending Payment, the customer sees the same message on the success page, and new attempts for the same cart are refused with This cart already has a payment or needs verification. Check KOMOJU before trying again. until you check the payment in the KOMOJU 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 open KOMOJU session is cancelled first and can no longer be paid. If KOMOJU has already received the payment, the order is invoiced instead of cancelled. Orders with an issued konbini or bank transfer slip are in Processing, so the cron does not cancel them while the customer can still pay. If KOMOJU cannot be reached (or the secret key of the order's mode was removed), the cron does not cancel the order and adds the note KOMOJU could not confirm that the payment can no longer be completed, so the order was not cancelled automatically. …; it tries again on its next run, and the other orders are processed as usual. When you click Cancel on such an order, the Admin shows KOMOJU could not confirm that this payment can no longer be completed. Check the payment in the KOMOJU dashboard and try again.

When you cancel an order whose slip or authorization is still open (Processing without an invoice), the KOMOJU payment is cancelled too, so the customer can no longer pay it. If KOMOJU has already captured it, the order is invoiced instead and the Admin shows KOMOJU has already received a payment for this order. The order was not cancelled; check its status. A slip paid after the order was cancelled is not invoiced; the order gets a note (see Order statuses).

The module works with the standard Magento checkout. It 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 Processing without an invoice until then. KOMOJU is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to KOMOJU, but KOMOJU has not reported the payment yet. There is no invoice.

Processing without an invoice: a konbini or bank transfer slip waits for payment, or a payment waits for capture in the KOMOJU dashboard. The note shows the payment deadline. No money is captured yet; do not ship the order. The Magento cron does not cancel it.

Processing with an invoice: KOMOJU confirmed the payment. The invoice is created with the KOMOJU payment ID as the transaction ID, and a note shows how the payment was confirmed (webhook or return).

On Hold after a mismatch: KOMOJU reported a different amount or currency than the order total. No invoice is created. Check the payment in the KOMOJU dashboard, then fulfil the order or refund the payment there.

Canceled: the customer did not complete the payment, the payment could not be started, the slip expired, the payment failed or was cancelled, or the order was cancelled in Magento. If a payment arrives after the order was cancelled or closed, the order is not reopened: the note KOMOJU payment received after the order was closed or cancelled. Check stock and fulfil or refund manually. is added.

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

If a second payment arrives for an order that is already paid, or another order of the same cart already holds a payment, the order is not changed. A note asks you to check it and refund the duplicate in the KOMOJU dashboard. The notes are order comments that the customer does not see.

KOMOJU payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and KOMOJU mode (test or live), KOMOJU session, KOMOJU payment (the payment ID), KOMOJU method (for example konbini), KOMOJU state and KOMOJU refund history. The customer sees only the payment method title.

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

The module first reads the payment from KOMOJU with the key of the mode the payment was made in, so that mode's secret key must be set. Refunds are possible once KOMOJU has captured the payment, up to the amount KOMOJU charged minus the amounts already refunded. If KOMOJU does not accept the refund, Magento shows the error and the credit memo is not created. A refund counts as done only when KOMOJU confirms it; the KOMOJU refund ID is recorded as the transaction ID. A full refund closes the order. Some methods, for example konbini, cannot be refunded automatically by KOMOJU: refund them in the KOMOJU dashboard.

For payments that KOMOJU converted into another currency (for example konbini in JPY for a USD order), only a full refund is possible from Magento: Only a full refund is available for a converted KOMOJU payment. Use the dashboard for partial refunds.

Refunds made in the KOMOJU dashboard arrive by webhook. The module creates a credit memo with an offline refund for the refunded amount (no second refund is sent to KOMOJU), with the comment KOMOJU dashboard refund; no second API refund. A full refund refunds the remaining items and shipping and closes the order. Partial refunds made in the dashboard for payments converted into another currency are only noted on the order: record the matching amount in Magento manually with a credit memo and Refund Offline.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox KOMOJU Payment is the first row of the VibeFox KOMOJU 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-komoju 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, KOMOJU is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. 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 refunds 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

KOMOJU does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has a secret key: Sandbox Secret Key in sandbox mode, Live Secret Key in live mode. The Webhook URL and setup row shows a warning when the key is missing. The currency the customer shops in must be supported by KOMOJU (see Requirements). 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 KOMOJU dashboard check that the webhook exists for the mode you use, that its URL is exactly the one shown in Webhook URL and setup and that the events are selected. Check that its secret token is in the matching field (Live Webhook Secret or Sandbox Webhook Secret) for the website of the store, and turn on Enable Logging to see the reason. 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 Invalid 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 notification is for a payment that was not started by this store, for example from another shop on the same KOMOJU account.

Webhook answers OK retry, OK error or Temporary error, retry later.: the order was being updated by another request at the same moment, or an error occurred while the order was being updated. KOMOJU retries the notification. The reason is in the log.

The webhook URL shows Method not allowed. in the browser: this is normal. The URL accepts only signed requests from KOMOJU.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. KOMOJU retries the notification later, and card payments are also confirmed when the customer returns.

Order is On Hold or has a KOMOJU note: read the order notes (see Order statuses). The amount or currency did not match, the payment came after the order was cancelled, or a second payment was received.

Refund fails: read the message. The secret key of the mode the payment was made in may be missing, the payment may not be captured yet or may not be refundable automatically (refund it in the KOMOJU dashboard), only a full refund is possible for a converted payment, or KOMOJU refund balance changed. Reconcile the dashboard refund before trying again. when a refund was made in the dashboard and is not recorded in Magento yet. After KOMOJU did not confirm the refund. Check the dashboard before trying again. or KOMOJU refund failed. Check the dashboard before trying again., check the payment in the KOMOJU dashboard before you try again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the KOMOJU dashboard.

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.

Developers can change the list of currencies with the Magento event komoju_p_supported_currencies and the payment session, for example the payment methods, with the event komoju_p_session_params. The amount, currency and order reference cannot be changed there.

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_KomojuPayment. It removes the data and the code.

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The KOMOJU transactions 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.

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