VibeFox Kushki for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

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

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

On install the module creates the order status Kushki payment on hold. PrestaShop assigns a new payment module to the currencies, countries and customer groups of your shop. In Payment > Preferences check that the module is allowed for USD or COP and for Ecuador or Colombia.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Kushki Payment > Configure. Each section has its own Save button, which saves the whole page. 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 default currency of your shop is not USD or COP, 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, the settings are saved and a message reminds you to enter them. 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.

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

Webhook (recommended)

Payments are confirmed at once by the Kushki API response, so the webhook is not required. It additionally creates the order for a payment 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 Webhook URL for card payments. With friendly URLs it looks like https://your-shop/module/wcp_kushki_payment/webhook, possibly with a language code such as /es/. Copy the URL exactly as the settings show it. Do this for the test account and for the production account.

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

Clear saved secrets: tick a Private Merchant ID or webhook signature and click Save to remove it. An empty field keeps the saved value.

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.

Advanced

Debug log: writes Kushki requests and webhooks to logs/kushki_p_debug.log.php in the module folder. The file cannot be opened from the web. 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 module removes the settings and the logs. The Kushki payment records (charges and refunds) and the order status Kushki payment on hold always stay, so old orders can still be refunded after a re-install. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Credit / debit card (Kushki)). The Kushki card form appears under it, with the cart total in the cart currency. The customer enters the card, chooses installments if the Kushki form offers them, and presses the pay button inside the Kushki form.

The PrestaShop Place order button stays visible, because it carries the terms of service. If the terms are already accepted, the payment is submitted automatically after the Kushki pay button. Otherwise the customer sees Your card was accepted by Kushki. Accept the terms of service and press "Place order" to pay. If the customer presses Place order without using the Kushki form, the message Please enter your card details in the Kushki form and press its pay button. is shown.

Your shop then charges the card on the server. The order is marked paid only after Kushki confirms it with a ticket number. The order is then created, and the customer sees the standard order confirmation page with Your card payment has been received. If Kushki reports an approved amount or currency, they are compared with the cart. An order on hold shows Your payment is being reviewed. We will update your order as soon as the review is complete.

If the card is declined, no order is created and the customer is back at the payment step with Your payment was declined and the reason from Kushki, and can try another card. 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. 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.

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 is created. A cart that already has an order, or an approved charge whose order was not created yet, is never charged again: the customer sees the confirmation of that order. 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.

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop. 3-D Secure, fraud rules and the installments offered are set up in the Kushki Console.

The module 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 order yet: the customer has not paid, the card was declined, or the Kushki response was lost and the webhook has not arrived yet. Only the cart exists.

Payment accepted: Kushki confirmed the charge (by the API response or by the webhook). The payment is recorded with the Kushki transaction reference (or the ticket number) as the transaction ID. A note shows the mode, the Kushki ticket number and the reference.

Kushki payment on hold: Kushki returned a success without a ticket number, reported a different amount or currency than the cart, or the cart was changed during the payment. 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 Payment accepted.

Payment error: the webhook reported that the charge of an order on hold was declined.

Refunded: the payment was refunded through the module.

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.

Kushki payment block

The order page shows a Kushki payment block with the ticket number, the transaction reference, the environment (with a Test badge for test payments), the status of the charge, the amount charged and the order total, the refund form, the refund history and the Kushki notes of the order.

Refunds

Kushki refunds the whole charge, so only full refunds are possible. In the Kushki payment block the amount Kushki charged is filled in. Optionally enter a reason and click Refund via Kushki, then confirm the question Refund the full payment through Kushki? This cannot be undone. You need the right to edit orders. For any other amount the module 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 block 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. Refunds need a confirmed Kushki charge with a ticket number.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page 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 module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Kushki Payment is the first block on Modules > Module Manager > VibeFox Kushki 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-kushki 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, 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. 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

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 cart currency is USD or COP. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. The settings page shows a warning when the IDs are missing.

The payment went through, but no order was created: the Kushki API response was lost, for example by a timeout. The webhook creates the order for 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 creates the order in Kushki payment on hold.

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 of this cart (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 could not be created (for example, the module is disabled). 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 module charges cards only.

The customer sees an error when paying: turn on Debug log and look at the Log field on the module page. 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 PrestaShop could not create the order. The log shows the reason. The next payment attempt of the same cart creates the order 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.

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

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Kushki Payment and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the settings and the logs are removed. If it is off, all settings are kept for a later re-install. The Kushki payment records (charges and refunds) and the order status Kushki payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes, Kushki ticket numbers and transaction IDs.

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