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

Currency: USD (Ecuador) or COP (Colombia). For orders in other currencies the payment method is hidden at checkout.

HTTPS: Kushki requires the checkout to be served over HTTPS in live mode.

Kushki account: you need the Public and Private Merchant IDs of your Kushki test (UAT) account and of your production account. They are in the Kushki Console under Developers > Credentials. For the optional webhook you also need the webhook signature key of each account (see Configuration).

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_kushki_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_kushki_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_kushki_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 Kushki 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. Enter the test Public and Private Merchant IDs and keep Test mode on. Optionally, set up the webhook in the Kushki Console and paste its signature key (see Configuration).

5. Turn on Enable / Disable, click Save and place a test order. When ready, enter the live Merchant IDs (and the live webhook signature) and turn off Test mode.

OpenCart 4

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

4. Enter the license key, the Merchant IDs and the webhook 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).

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

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Kushki Payment > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page warns you when the payment method is enabled but the Merchant IDs of the current mode are missing (the payment method is then hidden at checkout), when the default currency of your store is not USD or COP, when live mode is used without HTTPS (on OpenCart 4, when the storefront address starts with http://) and when the current mode has no webhook signature. While test mode is on, it shows Test mode is on: the Kushki test environment is used, no real money is charged. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty and not longer than 128 characters, Sort Order must be a whole number (negative numbers are allowed), Total a number, 0 or greater, and every order status must exist. If a field is wrong, nothing is saved and the page names the field. Spaces around the IDs are removed on save.

Kushki

Enable / Disable: Enable Kushki card payments 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: Credit / debit card (Kushki). Required, up to 128 characters.

Description: the text shown above the card form at the Confirm Order step. Default: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

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

Geo Zone: offer Kushki 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 Kushki is offered. Leave it empty to offer Kushki for any total.

API credentials

Copy the Public and Private Merchant IDs from the Kushki Console (Developers > Credentials; the page links to the Console). Test (UAT) and production accounts have different IDs. Test mode uses only the test IDs, live mode only the live IDs.

Test mode: uses the Kushki test (UAT) environment: the test Merchant IDs, the test card form and the test API together. No real money is charged, and a TEST MODE badge is shown at checkout. Default: on. Turn it off to take real payments. Refunds always go to the environment the payment was made in.

Test Public Merchant ID: the Public Merchant ID of your Kushki test account. It loads the card form.

Test Private Merchant ID: the Private Merchant ID of your Kushki test account. It is used on the server for charges and refunds.

Live Public Merchant ID: the Public Merchant ID of your Kushki production account.

Live Private Merchant ID: the Private Merchant ID of your Kushki production account. Keep it secret.

Saved Private Merchant IDs and webhook signatures 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 (recommended)

Payments are confirmed at once by the Kushki API response, so the webhook is not required. It additionally confirms a payment whose response was lost (for example on a timeout) and reports voids, refunds and chargebacks made in the Kushki Console. In the Kushki Console (Webhooks) add the URL shown in Webhook URL in this section. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_kushki_payment/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_kushki_payment/payment/wcp_kushki_payment.webhook. It is built from the storefront address of your OpenCart installation. Copy the URL exactly as the settings show it. Do this for the test account and for the production account.

The extension handles these card notifications:

Test webhook signature: the webhook signature key of the Kushki test account (Console > Webhooks).

Live webhook signature: the webhook signature key of the Kushki production account.

Webhooks without a valid signature are rejected. A notification must be signed with the key of the mode the payment was made in, so a test notification never confirms a live payment. Without a signature key, all webhook notifications are rejected, but payments still work, because they are confirmed by the API response.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Kushki has approved the card charge. Each field below lists your OpenCart order statuses.

Order Status After Payment: Kushki approved the charge with a ticket number, for the order amount and currency. Default: Processing.

On Hold (Review) Status: Kushki approved the charge without a ticket number, or reported another amount or currency. A note explains why; check the payment in the Kushki Console before fulfilment. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Failed Status: an order in the review status whose charge Kushki later reports as declined (webhook). Default: Failed.

Canceled Status: orders in this status (or in the refunded status) are never reopened by a late webhook. Default: Canceled.

Refunded Status: set after the payment is refunded from the order tab. Default: Refunded.

Advanced

Debug log: writes Kushki requests and webhooks to kushki_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. Warnings and errors are always logged. Logs never contain Merchant IDs, card tokens or customer e-mails. 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 settings and the log. The Kushki payment records (charges and refunds) always stay, so old orders can still be refunded after a re-install. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Private Merchant IDs and webhook signatures are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved secrets are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit / debit card (Kushki)). OpenCart creates the order at the Confirm Order step, still without a status. There the customer sees your description and the Kushki card form with the order total in the order currency. The customer enters the card, chooses installments if the Kushki form offers them, and presses the pay button inside the Kushki form. The payment is then sent automatically, as the note under the form says: Enter your card in the secure Kushki form above and press its pay button — the payment is sent automatically. If the customer clicks the OpenCart Confirm Order button instead, the message Please enter your card details in the Kushki form and press its pay button. is shown.

On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options. The Kushki card form then appears in the order confirmation block at the bottom of the checkout page, above the Confirm Order button, and is rebuilt for the current order total every time OpenCart reloads that block.

Your store then charges the card on the server. The order is marked paid only after Kushki confirms it with a ticket number. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, the cart is emptied, and the customer sees the OpenCart order success page with Your card payment has been received. The amount and currency reported by Kushki are compared with the order. An order in the review status shows Your payment is being reviewed. We will update your order as soon as the review is complete.

If the card is declined, the order stays without a status and the customer stays at the Confirm Order step with Your payment was declined and the reason from Kushki, and can try another card in the reloaded form. For network, key or server problems the customer sees The payment could not be processed right now. Please try again in a moment or choose another payment method. The technical reason is written to the log and to the order notes. A second click while a payment is being processed shows A payment for this order is already being processed. Please wait a moment and check your order status.

OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 keeps one order for the checkout and updates it. Either way one cart is paid only once: a cart that is already paid, or an approved charge whose order has no status yet, is never charged again, and the customer sees the success page. If the Kushki response is lost (for example on a timeout), the customer sees the general message, but the charge attempt is kept. When the signed webhook reports the approved charge, the order gets its status. If the customer pays again before any webhook arrives, this is a new charge; a late approval of the first charge then only adds a note about a possible double charge.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example a charge on review was later declined, or you cancelled it), or it is already paid for an earlier cart and the customer has changed the cart since, the customer is taken back to the checkout page when paying, and the next Confirm Order creates a new order. Above the checkout page the customer sees Your previous order is closed (declined, cancelled or refunded by the store). Please confirm the order again: the cart will be paid with a new order. when the order was closed, or Your previous order is already paid for other cart contents. Please confirm the order again: the current cart will be paid with a new order. when it was paid for an earlier cart. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

The webhook also works while the store is in maintenance mode, because OpenCart 3 lets payment extension requests through and on OpenCart 4 the extension adds a startup action for it. 3-D Secure, fraud rules and the installments offered are set up in the Kushki Console.

The extension takes one-step card payments only. It has no partial refunds, saved cards or subscriptions, no cash, bank transfer (PSE) or debit-card redirect payments and no separate authorize and capture.

Orders and refunds

Order statuses

No status (missing order): the customer has not paid, the card was declined, or the Kushki response was lost and the webhook has not arrived yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): Kushki confirmed the charge (by the API response or by the webhook). A note shows the mode, the amount, the Kushki ticket number and the reference.

On Hold (Review) Status (default Pending): Kushki returned a success without a ticket number, or reported a different amount or currency than the order. The note explains it. Check the transaction in the Kushki Console and fulfil the order or refund the payment. A later signed approval with a ticket number and the matching amount sets the order to Order Status After Payment.

Failed Status (default Failed): the webhook reported that the charge of an order in the review status was declined.

Refunded Status (default Refunded): the payment was refunded through the extension.

If Kushki reports another approved charge for an order that is already paid, cancelled or refunded, the order is not changed. A note asks you to check for a double charge and refund it in the Kushki Console. A webhook from the test environment for a live payment (or the other way round) is ignored with a note.

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

VibeFox Kushki Payment tab

In Sales > Orders open an order paid with Kushki. At the bottom of the order page, next to History and Additional, the VibeFox Kushki Payment tab shows the Ticket number (with a TEST label for test payments), the Transaction reference, the Environment, the Result, the amounts Charged / order amount, the refund form, the refund history and the Kushki notes of the order. The tab is shown to users who have access to the extension.

Refunds

Kushki refunds the whole charge, so only full refunds are possible. In the VibeFox Kushki Payment tab the Amount Kushki charged is filled in. Optionally enter a Reason (optional) and click Refund via Kushki, then confirm the question Refund the full payment through Kushki? This cannot be undone. You need the right to modify the extension (set in System > Users > User Groups). For any other amount the extension shows Kushki refunds the full payment only. Enter the full charged amount with the amount, and nothing is sent. The refund is made in the amount and currency Kushki charged, so after an amount mismatch the customer gets back what was actually charged, not the order total. A payment can be refunded once.

The refund is sent in the mode the payment was made in (test or live), so that mode's Private Merchant ID must be set. If Kushki does not accept the refund, the tab shows Kushki refund failed with the Kushki code and message, and no refund is recorded. A successful refund is added to the refund history and the notes with the Kushki refund ticket, and the order is set to Refunded Status without notifying the customer and without returning products to stock, like a manual status change. Refunds need a confirmed Kushki charge with a ticket number.

Product returns in Sales > Returns do not send money back through Kushki. Voids and refunds made in the Kushki Console arrive by the webhook and are added to the notes. The order status is not changed automatically.

License key

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

Kushki does not appear at checkout: check that the license is active, Enable / Disable is on and the current mode has both Merchant IDs: the test IDs in test mode, the live IDs in live mode. The settings page shows a warning when the IDs are missing. Check that the order currency is USD or COP, 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 Kushki API response was lost, for example by a timeout. The webhook confirms such payments. In the Kushki Console check that the webhook URL is exactly the one shown in Webhook URL, for the account of the mode you use, and that the signature key of that account is in the matching field (Test webhook signature or Live webhook signature). An approved charge without the paid amount and currency puts the order in On Hold (Review) Status.

Webhook answers Webhook signature not configured: neither webhook signature is set. Paste the signature key into the settings.

Webhook answers Invalid signature: the signature key belongs to another account or mode, or the notification was changed on the way.

Webhook answers Order mismatch: the notification does not belong to a charge attempt of this order (wrong attempt key or transaction). Nothing is changed.

Webhook answers Busy, retry later: the order was being processed by another request at the same moment, or the order status could not be set. Kushki can send the notification again. Errors are always written to the log.

The webhook URL shows POST only in the browser: this is normal. The URL accepts only notifications from Kushki.

The card form does not load: the customer sees The Kushki card form could not be loaded. Please reload the page or choose another payment method. Check the Public Merchant ID of the current mode.

The customer sees This payment option is not available in this store. Please pay by card.: a non-card payment option was chosen in the Kushki form. The extension charges cards only.

The customer sees an error when paying: turn on Debug log and look at the Log field on the extension page. This payment method is not available. Please reload the checkout page. means the checkout session no longer matches the order, or the payment method was turned off meanwhile: the customer reloads the checkout. A wrong or missing Private Merchant ID gives the general message that the payment could not be processed.

The customer sees Your payment was received, but the order could not be completed automatically: Kushki approved the charge, but OpenCart could not set the order status. The log shows the reason. The next payment attempt of the same cart sets the status without a new charge.

Refund fails with a message about the mode: the payment was made in test or live mode, and the Private Merchant ID of that mode is not set. Enter it and try again.

No refund form in the tab: the tab says why: the payment is already refunded, the order has no Kushki ticket number (No Kushki ticket number found for this order — refund it in the Kushki Console.), your user group has no right to modify the extension, or the Private Merchant ID of the payment's mode is not set.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Kushki 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, including the one that shows the message above the checkout page, and its startup action, which lets the webhook through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, test mode, Merchant IDs, webhook signatures, logging) and the log are removed. If it is off, they are kept for a later re-install. The Kushki payment records (charges and refunds) are always kept, so orders paid before can still be 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 Kushki Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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