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

Currency: USD (Ecuador) or COP (Colombia). The cart currency, the currency the customer pays in, must be one of them. 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. The settings page warns you when live mode is used without HTTPS.

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

2. Run bin/magento module:enable Vibefox_KushkiPayment 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 Kushki 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. Enter the test Public and Private Merchant IDs and keep Test Mode at Yes. Optionally, set up the webhook in the Kushki Console and paste its signature key (see Configuration). Set Enable to Yes, click Save Config and place a test order. When ready, enter the live Merchant IDs (and the live webhook signature) and set Test Mode to No.

The module adds the Credit / debit card (Kushki) 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 three tables for the Kushki charge attempts, webhook events and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Kushki 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. Set Remove data on uninstall in the Default Config. Save Config saves the whole page. Spaces around the values are removed on save. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (up to 128 characters).); a Sort Order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater.

When Enable is Yes, the Webhook URL and setup row near the end of the group shows warnings for the current mode: Enter the Public and Private Merchant IDs for the current mode, otherwise Kushki is hidden at checkout., No webhook signature key: lost charge responses cannot be confirmed automatically., and, while test mode is on, Kushki Test Mode is enabled. No real payments will be processed. In live mode without HTTPS it shows Use HTTPS for live Kushki payments. Settings with missing Merchant IDs are saved; the payment method stays hidden at checkout until they are entered.

The fields are one list on the page. Below they are grouped by purpose.

General

Enable: shows or hides Kushki at checkout. It is shown only when both Merchant IDs of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit / debit card (Kushki). Required, at most 128 characters.

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.

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

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 customers see TEST MODE — no real payments are processed. under the payment method. Default: Yes. Set it to No to take real payments. Refunds always go to the environment the payment was made in.

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

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

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

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

Magento stores the Private Merchant IDs and the webhook signatures encrypted and shows only a mask (******) after saving. Leave the mask, or leave the field empty, to keep the saved value (Leave blank to keep the saved secret. Use Clear to remove it.); type a new value to change it. To delete a saved value, set the matching Clear test private id, Clear live private id, Clear test webhook secret or Clear live webhook secret to Yes and click Save Config. The value is removed and the Clear field goes back to No.

Webhook (recommended)

Payments are confirmed at once by the Kushki API response, so the webhook is not required. It additionally confirms an order whose charge 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 and setup for card payments. It looks like https://your-store/wcpkushkipayment/webhook/index. Copy the URL exactly as the settings show it. Do this for the test account and for the production account, as the page says: Configure this URL in Kushki Console for both environments.

The module handles these card notifications:

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

Live Webhook Secret: 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. The webhook uses the keys of the website where the order was placed, so enter them in the Default Config or for that website. Without a signature key, all webhook notifications are rejected, but payments still work, because they are confirmed by the API response.

Conditions

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

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

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

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

Advanced

Debug log: writes Kushki requests and webhooks to var/log/kushki_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged. Logs never contain Merchant IDs, signature keys, card tokens or customer e-mails. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the module settings and the log (see Uninstall). The license key is always removed. The Kushki charges, webhook events and refunds always stay, so old orders can still be refunded. Default: No. The field says: Order, payment, event and refund history is always retained.

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 Credit / debit card (Kushki)). The description and the Kushki card form appear under it, with the cart total in the cart currency, and the button Reload card form. The customer enters the card, chooses installments if the Kushki form offers them, and presses the pay button inside the Kushki form. When the cart total changes, the form is loaded again with the new total.

After the Kushki pay button the order is placed automatically. If Magento still needs something, for example the acceptance of the terms and conditions, Magento shows its usual message; the card stays accepted, and the customer completes the step and clicks Place Order. If the customer clicks 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. If a non-card option is chosen in the Kushki form, the customer sees Please pay by card in the Kushki form. and the form is loaded again.

Magento then places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. Your store charges the card on the server for the order total in the order currency. The order is marked paid only after Kushki confirms it with a ticket number. Magento then creates the invoice, sets the order to Processing and sends the order e-mail. The customer sees the standard order success page.

If the card is declined, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart 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 later. and the cart is restored too. The technical reason is written to the log.

If the Kushki response is lost (for example on a timeout), or Kushki reports a different amount or currency, the customer sees the success page with Your Kushki payment is awaiting confirmation or manual review. Do not pay again until its status is verified. The order stays in Pending Payment (or On Hold after a mismatch). The charge is not sent again automatically. When the signed webhook reports the approved charge, the order is confirmed. A page refresh never charges an order again, and a cart that already has a charge is never charged a second time: a new order of that cart is cancelled and the customer sees Your cart already has a payment. Check the original order before trying again.

3-D Secure, fraud rules and the installments offered are set up in the Kushki Console. 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), a later approval of its charge does not reopen it; a note asks you to check the payment.

The module works with the standard Magento checkout. It 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. Kushki is not offered for orders created in the Admin or for checkout with multiple addresses.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the charge has not been confirmed yet, for example when the Kushki response was lost and the webhook has not arrived yet. There is no invoice.

Processing: Kushki confirmed the charge (by the API response or by the webhook). The invoice is created with the Kushki transaction reference (or the ticket number) as the transaction ID. A note says whether the charge was confirmed at checkout or by the webhook.

On Hold: Kushki returned a success without a ticket number, reported a different amount or currency than the order, or the order total changed. No invoice is created. The note Kushki payment requires manual review: explains it. Check the transaction in the Kushki Console and refund the payment (see Refunds) or wait for a matching signed approval, which creates the invoice.

Canceled: the card was declined, the payment could not be started, the webhook reported a declined charge, the order was cancelled in Magento, or a charge without an invoice was refunded from the order page.

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

If Kushki reports another approved charge for an order that is already paid, or for another order of the same cart, 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. The notes are order comments that the customer does not see.

Kushki payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for the Kushki charge, Kushki mode (test or live), Kushki ticket, Kushki reference and Kushki state. After a refund it also shows Kushki refund with the amount, the refund state and the Kushki refund ticket. The customer sees only the payment method title.

Refunds

Kushki refunds the whole charge, so only full refunds are possible. Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Keep all items and amounts and click Refund. The whole Kushki charge is refunded. For any other amount Magento shows Kushki refunds the full charge only. Use a full invoice Credit Memo. and nothing is sent. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Kushki. A payment can be refunded once. A full refund closes the order.

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, Magento shows Kushki refund failed or needs verification. Check the Console. and the credit memo is not created; you can try again. If the answer of Kushki is lost, Magento shows The Kushki refund outcome is unknown. Check the Console before trying again. Further refund attempts of that order are then blocked, so the customer is never refunded twice. Check the refund in the Kushki Console.

Charge without an invoice: a confirmed charge whose order has no invoice, for example On Hold after a mismatch or approved after the order was cancelled, can be refunded on the Information tab of the order. The block Kushki charge without a paid invoice offers the button Refund full Kushki charge: with the amount Kushki charged. The refund is made in the amount and currency Kushki charged. No credit memo is created, a note is added and a waiting order is cancelled. You need the role permission for credit memos.

Voids and refunds made in the Kushki Console arrive by the webhook and are added to the order notes. The order and credit memos are not changed automatically. Create a credit memo with Refund Offline or update the order manually if needed.

License key

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

Kushki 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 both Merchant IDs: the test IDs in test mode, the live IDs in live mode. The Webhook URL and setup row shows a warning when they are missing. Check that the cart currency is USD or COP. 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 Kushki API response was lost, for example by a timeout. The webhook confirms such orders. In the Kushki Console check that the webhook URL is exactly the one shown in Webhook URL and setup, for the account of the mode you use, and that the signature key of that account is in the matching field (Test Webhook Secret or Live Webhook Secret) for the website of the order. An approved charge without the paid amount and currency puts the order On Hold.

Webhook answers Invalid signature: no signature key is set for the mode, the 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 order. Nothing is changed.

Webhook answers Mode mismatch: the notification is signed with the key of the other mode (test or live) than the payment. It is ignored.

Webhook answers Busy, retry later: the order was being processed by another request at the same moment, or an error occurred while the order was being updated. 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.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Payments are still confirmed by the API response at checkout; a lost response is confirmed when Kushki sends the notification again after maintenance.

The card form does not load: check the Public Merchant ID of the current mode. The customer can click Reload card form. If the form address cannot be built, the customer sees The Kushki card form could not be loaded. Please reload it.

The customer is back in the cart with an error after Place Order: turn on Debug log and look at the Log field. A wrong or missing Private Merchant ID gives the general message that the payment could not be processed. This Kushki token was already used. Please load the form again. means that the same card form result was sent twice; the customer enters the card again. The order of that attempt is cancelled.

The customer sees Your Kushki payment needs verification. Please contact us before paying again.: a charge of this order was sent, but its result is not known. Check the transaction in the Kushki Console before the customer pays again.

Order is On Hold after payment: read the order notes (see Order statuses), then fulfil the order after a matching approval or refund the payment.

Refund fails with The Private Merchant ID for this payment mode is not configured.: 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 is available. Check the Console.: the order has no confirmed Kushki charge. Refund it in the Kushki Console.

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 is refunded with Refund full Kushki charge on the Information tab (see Refunds).

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.

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

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings and the log are removed too. If it is No, the settings are kept for a re-install. The Kushki charges, webhook events and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, 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.