VibeFox Kushki for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

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

PHP: 8.0 or later.

Store currency: USD (Ecuador) or COP (Colombia). For 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

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

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Kushki > 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. 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).

6. Turn on Enable / Disable and place a test order. When ready, enter the live Merchant IDs (and the live webhook signature) and untick Test mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Kushki. Above the fields 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 store currency is not supported, when live mode is used without HTTPS 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. When you save with the payment method enabled but without the Merchant IDs of the current mode, an error reminds you to enter them. Spaces around the IDs are removed on save.

General

Enable / Disable: Enable Kushki card payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Credit / debit card (Kushki).

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

API credentials

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

Test mode: Use the Kushki test (UAT) environment switches the Merchant IDs, the card form and the API to the Kushki test environment together. No real money is charged, and a TEST MODE badge is shown at checkout. Default: on. Untick it to take real payments.

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.

Webhook (recommended)

Payments are confirmed at once by the Kushki API response, so the webhook is not required. It additionally confirms payments whose response was lost (for example on a timeout) and reports voids and refunds made in the Kushki Console. In the Kushki Console (Webhooks) add the URL shown in this section of the settings for card payments. It looks like https://your-site/wc-api/webhook_kushki_p/. Do this for the test account and for the production account.

The plugin 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. Without a signature key, all webhook notifications are rejected, but payments still work, because they are confirmed by the API response.

Advanced

Debug log: Log API calls and webhooks writes Kushki requests and webhooks to WooCommerce > Status > Logs, source wcp_kushki_payment. Errors are always logged. Logs never contain Merchant IDs, card tokens or customer e-mails. Default: off.

Delete data on uninstall: when on, deleting the plugin removes the settings and logs. Orders and their Kushki references are kept. Default: off.

Checkout

The customer chooses the payment method (by default Credit / debit card (Kushki)). The Kushki card form appears under it, with the order total in the order currency. On the Pay for order page the form uses the order total. The customer enters the card, chooses installments if the Kushki form offers them, and presses the pay button inside the Kushki form.

On the classic checkout the WooCommerce Place order button is hidden while Kushki is selected: after the card is accepted, the order is submitted automatically. On the Checkout block the customer also presses the pay button inside the Kushki form. If the customer tries to place the order without it, the message Please enter your card details in the Kushki form and press its pay button. is shown.

Your store then charges the card on the server. The order is marked paid only after Kushki confirms it with a ticket number, and the customer goes straight to the order received page. If Kushki reports an approved amount or currency, they are compared with the order.

If the card is declined, the customer sees Your payment was declined with the reason from Kushki and can try another card in the same 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 added to the order notes and the log. 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.

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). 3-D Secure, fraud rules and the installments offered are set up in the Kushki Console.

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

Orders and refunds

Order statuses

Pending payment: the order was created and the card has not been charged yet.

Processing: Kushki confirmed the charge (by the API response or by the webhook). Orders with only virtual downloadable products become Completed, the WooCommerce default. The order note shows the mode, the Kushki ticket number and the reference. The transaction ID is the Kushki transaction reference (or the ticket number).

On hold: Kushki returned a success without a ticket number, or reported a different amount or currency than the order. The order note explains it. Check the transaction in the Kushki Console and fulfil the order or refund the payment.

Failed: the card was declined or the charge could not be made. The order note shows the Kushki code and message. The customer can pay again.

If a webhook 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 order (or the other way round) is ignored with a note.

Refunds

Open the order, click Refund, enter the full order total and click Refund via Credit / debit card (Kushki) (the button shows your Title). Kushki refunds the whole payment, so only full refunds are accepted. For a partial amount the plugin shows Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. 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, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the Kushki refund ticket.

Voids and refunds made in the Kushki Console arrive by the webhook and are added to the order notes. They are not recorded as WooCommerce refunds automatically.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Kushki. 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, 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. 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: webhooks are still processed, 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

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. Check that the store currency (or the order currency on the Pay for order page) is USD or COP. The settings page shows a warning for each of these problems.

The payment went through, but the order is Failed or stays Pending payment: 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 the settings, 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 on hold instead.

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 this order (wrong order key or transaction). The order is not changed.

Webhook answers Busy, retry later: the order was being processed by another request at the same moment. Kushki can send the notification again.

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 plugin charges cards only.

The customer sees an error when paying: open the order notes or turn on Debug log and look at WooCommerce > Status > Logs, source wcp_kushki_payment. A wrong or missing Private Merchant ID gives the general message that the payment could not be processed.

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.

Refund fails with No Kushki ticket number found for this order: the order has no confirmed Kushki charge. Refund it in the Kushki Console.

Other currencies: developers can change the currency list with the kushki_p_supported_currencies filter at their own risk. The currency must be enabled on your Kushki account.

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.

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, Kushki ticket numbers and transaction IDs.

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