VibeFox Kushki for WooCommerce — Допомога

Вимоги

WordPress: 6.0 або новіша версія.

WooCommerce: 8.0 або новіша версія, встановлений і активний. Плагін не активується без нього.

PHP: 8.0 або новіша версія.

Валюта магазину: USD (Еквадор) або COP (Колумбія). Для інших валют спосіб оплати приховується під час оформлення замовлення.

HTTPS: Kushki вимагає, щоб оформлення замовлення відкривалося через HTTPS у робочому режимі.

Обліковий запис Kushki: вам потрібні публічний і приватний Merchant ID тестового облікового запису Kushki (UAT) та робочого облікового запису. Їх можна знайти в Kushki Console у розділі Developers > Credentials. Для необов'язкового вебхука також потрібен ключ підпису вебхука кожного облікового запису (див. розділ «Налаштування»).

Ліцензійний ключ VibeFox: купується на vibefox.net. Один ключ працює на одному домені.

Встановлення

1. У WordPress відкрийте Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку wcp_kushki_payment до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Kushki > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть свій ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки та натисніть Activate.

5. Введіть публічний і приватний Merchant ID тестового режиму та залиште увімкненим Test mode. За бажанням налаштуйте вебхук у Kushki Console і вставте його ключ підпису (див. розділ «Налаштування»).

6. Увімкніть Enable / Disable і зробіть тестове замовлення. Коли все готово, введіть Merchant ID робочого режиму (і підпис робочого вебхука) та вимкніть Test mode.

Налаштування

Усі налаштування розміщені на одній сторінці: WooCommerce > Settings > Payments > Kushki. Над полями сторінка попереджає, якщо спосіб оплати увімкнено, але не вказано Merchant ID поточного режиму (тоді спосіб оплати приховується під час оформлення замовлення), якщо валюта магазину не підтримується, якщо робочий режим використовується без HTTPS і якщо в поточному режимі немає підпису вебхука. Поки тестовий режим увімкнено, вона показує Test mode is on: the Kushki test environment is used, no real money is charged. Якщо ви зберігаєте налаштування з увімкненим способом оплати, але без Merchant ID поточного режиму, з'являється помилка з нагадуванням їх ввести. Пробіли навколо ідентифікаторів видаляються під час збереження.

Загальні

Enable / Disable: Enable Kushki card payments вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачать покупці під час оформлення замовлення. За замовчуванням: Credit / debit card (Kushki).

Description: текст над формою картки під час оформлення замовлення. За замовчуванням: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

Облікові дані API

Скопіюйте публічний і приватний Merchant ID з Kushki Console (Developers > Credentials). Тестовий (UAT) і робочий облікові записи мають різні ідентифікатори. Тестовий режим використовує лише тестові ідентифікатори, робочий — лише робочі.

Test mode: Use the Kushki test (UAT) environment одночасно перемикає Merchant ID, форму картки та API на тестове середовище Kushki. Реальні кошти не списуються, а під час оформлення замовлення показується позначка TEST MODE. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі.

Test Public Merchant ID: публічний Merchant ID вашого тестового облікового запису Kushki. Він завантажує форму картки.

Test Private Merchant ID: приватний Merchant ID вашого тестового облікового запису Kushki. Використовується на сервері для списань і повернень.

Live Public Merchant ID: публічний Merchant ID вашого робочого облікового запису Kushki.

Live Private Merchant ID: приватний Merchant ID вашого робочого облікового запису Kushki. Тримайте його в таємниці.

Вебхук (рекомендовано)

Платежі одразу підтверджуються відповіддю API Kushki, тож вебхук не обов'язковий. Він додатково підтверджує платежі, відповідь за якими була втрачена (наприклад, через тайм-аут), і повідомляє про анулювання та повернення, зроблені в Kushki Console. У Kushki Console (Webhooks) додайте URL, який показано в цьому розділі налаштувань для платежів карткою. Він має такий вигляд: https://your-site/wc-api/webhook_kushki_p/. Зробіть це для тестового та для робочого облікових записів.

Плагін обробляє такі сповіщення про картки:

Test webhook signature: ключ підпису вебхука тестового облікового запису Kushki (Console > Webhooks).

Live webhook signature: ключ підпису вебхука робочого облікового запису Kushki.

Вебхуки без дійсного підпису відхиляються. Без ключа підпису всі сповіщення вебхуків відхиляються, але платежі продовжують працювати, оскільки вони підтверджуються відповіддю API.

Додатково

Debug log: Log API calls and webhooks записує запити та вебхуки Kushki до WooCommerce > Status > Logs, джерело wcp_kushki_payment. Помилки завжди записуються. Журнали ніколи не містять Merchant ID, токенів карток або електронних адрес покупців. За замовчуванням: вимкнено.

Delete data on uninstall: якщо увімкнено, видалення плагіна стирає налаштування та журнали. Замовлення та їхні посилання на Kushki зберігаються. За замовчуванням: вимкнено.

Оформлення замовлення

Покупець обирає спосіб оплати (за замовчуванням Credit / debit card (Kushki)). Під ним з'являється форма картки Kushki із сумою замовлення у валюті замовлення. На сторінці Pay for order форма використовує суму замовлення. Покупець вводить картку, обирає розстрочку, якщо форма Kushki її пропонує, і натискає кнопку оплати всередині форми Kushki.

У класичному оформленні замовлення кнопка WooCommerce Place order приховується, поки вибрано Kushki: після того як картку прийнято, замовлення надсилається автоматично. У блоці «Оформлення замовлення» покупець також натискає кнопку оплати всередині форми Kushki. Якщо покупець намагається оформити замовлення без цього, з'являється повідомлення Please enter your card details in the Kushki form and press its pay button.

Далі ваш магазин списує кошти з картки на сервері. Замовлення позначається оплаченим лише після того, як Kushki підтверджує його номером тікета, і покупець одразу переходить на сторінку «Замовлення отримано». Якщо Kushki повідомляє схвалену суму або валюту, їх порівнюють із замовленням.

Якщо картку відхилено, покупець бачить Your payment was declined з причиною від Kushki і може спробувати іншу картку в тій самій формі. У разі проблем із мережею, ключами або сервером покупець бачить The payment could not be processed right now. Please try again in a moment or choose another payment method. Технічна причина додається до приміток замовлення та журналу. Повторне натискання під час обробки платежу показує A payment for this order is already being processed. Please wait a moment and check your order status.

Спосіб оплати працює в класичному оформленні замовлення, у блоці «Оформлення замовлення» і на сторінці Pay for order. Він сумісний з WooCommerce High-Performance Order Storage (HPOS). 3-D Secure, правила захисту від шахрайства та запропоновану розстрочку налаштовують у Kushki Console.

Плагін приймає лише одноетапні платежі карткою. Він не підтримує часткові повернення, збережені картки, підписки та Add payment method, а також оплату готівкою, банківські перекази (PSE) чи оплату дебетовою карткою з перенаправленням, окремі авторизацію та списання.

Замовлення та повернення

Статуси замовлення

Pending payment: замовлення створено, кошти з картки ще не списано.

Processing: Kushki підтвердив списання (відповіддю API або вебхуком). Замовлення, що містять лише віртуальні товари для завантаження, переходять у статус Completed, як це типово для WooCommerce. У примітці до замовлення вказано режим, номер тікета Kushki та референс. ID транзакції — це референс транзакції Kushki (або номер тікета).

On hold: Kushki повернув успіх без номера тікета або повідомив суму чи валюту, що відрізняються від замовлення. Примітка до замовлення це пояснює. Перевірте транзакцію в Kushki Console, потім виконайте замовлення або поверніть платіж.

Failed: картку відхилено або списання не вдалося виконати. У примітці до замовлення вказано код і повідомлення Kushki. Покупець може оплатити знову.

Якщо вебхук повідомляє про ще одне схвалене списання для вже оплаченого, скасованого або поверненого замовлення, замовлення не змінюється. Примітка просить перевірити подвійне списання та повернути його в Kushki Console. Вебхук із тестового середовища для робочого замовлення (або навпаки) ігнорується з приміткою.

Повернення

Відкрийте замовлення, натисніть Refund, введіть повну суму замовлення та натисніть Refund via Credit / debit card (Kushki) (на кнопці відображається ваш Title). Kushki повертає весь платіж, тому приймаються лише повні повернення. Для часткової суми плагін показує 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. Платіж можна повернути один раз.

Повернення надсилається в тому режимі, в якому було здійснено платіж (тестовому або робочому), тому має бути вказано приватний Merchant ID цього режиму. Якщо Kushki не приймає повернення, WooCommerce показує помилку, і повернення не фіксується. Успішне повернення додається до приміток замовлення разом із номером тікета повернення Kushki.

Анулювання та повернення, зроблені в Kushki Console, надходять через вебхук і додаються до приміток замовлення. Вони не реєструються автоматично як повернення WooCommerce.

Ліцензійний ключ

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі сторінки WooCommerce > Settings > Payments > Kushki. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія дійсна, і ваш домен. Кнопка Check now повторно перевіряє статус, Change key дозволяє ввести інший ключ, а Remove key видаляє його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

Один ключ працює на одному домені. Видалення ключа з сайту не звільняє слот домену. Звільніть слот в обліковому записі vibefox.net.

Без активного ключа Kushki не показується покупцям під час оформлення замовлення. Якщо платіж все одно розпочато, покупець бачить This payment method is not available. Please choose another one. Авторизовані адміністратори магазину й надалі бачать спосіб оплати з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати та протестувати плагін до купівлі ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються: вебхуки обробляються, а повернення працюють.

Коли термін ліцензії спливає, плагін продовжує працювати, але оновлення та підтримка потребують продовження. Статус автоматично перевіряється у фоновому режимі.

Усунення несправностей

Kushki не з'являється під час оформлення замовлення: переконайтеся, що ліцензія активна, Enable / Disable увімкнено і в поточному режимі вказано обидва Merchant ID: тестові — у тестовому режимі, робочі — у робочому. Перевірте, що валюта магазину (або валюта замовлення на сторінці Pay for order) — USD або COP. Сторінка налаштувань показує попередження для кожної з цих проблем.

Платіж пройшов, але замовлення має статус Failed або залишається в Pending payment: відповідь API Kushki була втрачена, наприклад через тайм-аут. Вебхук підтверджує такі платежі. У Kushki Console перевірте, що URL вебхука точно збігається з показаним у налаштуваннях для облікового запису режиму, яким ви користуєтеся, і що ключ підпису цього облікового запису вказано в потрібному полі (Test webhook signature або Live webhook signature). Схвалене списання без оплаченої суми та валюти натомість переводить замовлення в статус «На утриманні».

Вебхук відповідає Webhook signature not configured: жодний підпис вебхука не задано. Вставте ключ підпису в налаштування.

Вебхук відповідає Invalid signature: ключ підпису належить іншому обліковому запису або режиму, або сповіщення було змінено дорогою.

Вебхук відповідає Order mismatch: сповіщення не належить цьому замовленню (неправильний ключ замовлення або транзакція). Замовлення не змінюється.

Вебхук відповідає Busy, retry later: замовлення в цей момент оброблялося іншим запитом. Kushki може надіслати сповіщення повторно.

Форма картки не завантажується: покупець бачить The Kushki card form could not be loaded. Please reload the page or choose another payment method. Перевірте публічний Merchant ID поточного режиму.

Покупець бачить This payment option is not available in this store. Please pay by card.: у формі Kushki вибрано спосіб оплати, який не є карткою. Плагін списує кошти лише з карток.

Покупець бачить помилку під час оплати: відкрийте примітки до замовлення або увімкніть Debug log і перегляньте WooCommerce > Status > Logs, джерело wcp_kushki_payment. Неправильний або відсутній приватний Merchant ID дає загальне повідомлення про те, що платіж не вдалося обробити.

Повернення завершується помилкою з повідомленням про режим: платіж було здійснено в тестовому або робочому режимі, а приватний Merchant ID цього режиму не вказано. Введіть його і повторіть спробу.

Повернення завершується помилкою No Kushki ticket number found for this order: у замовлення немає підтвердженого списання Kushki. Поверніть кошти в Kushki Console.

Інші валюти: розробники можуть змінити список валют фільтром kushki_p_supported_currencies на власний ризик. Валюта має бути увімкнена у вашому обліковому записі Kushki.

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін працює з останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть плагін на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування способу оплати та журнали видаляються, лише якщо була увімкнена опція Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Наявні замовлення зберігають свої платіжні примітки, номери тікетів Kushki та ID транзакцій.

Kushki є товарним знаком відповідного власника. Цей плагін не пов'язаний із Kushki і не схвалений Kushki.