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

Вимоги

PrestaShop: від 8.0 до 9.x.

PHP: 8.0 або новіша. Модуль не встановлюється на старіших версіях PHP.

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

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

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

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

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

1. У панелі адміністратора відкрийте Modules > Module Manager і натисніть Upload a module. Виберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Kushki Payment у списку модулів і натисніть Configure.

3. Введіть ліцензійний ключ VibeFox у поле License key у блоці ліцензії у верхній частині сторінки Configure і натисніть Activate (див. Ліцензійний ключ).

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

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

Під час встановлення модуль створює статус замовлення Kushki payment on hold. PrestaShop призначає новий платіжний модуль валютам, країнам і групам клієнтів вашого магазину. У Payment > Preferences перевірте, що модуль дозволено для USD або COP та для Еквадору або Колумбії.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Kushki Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, коли спосіб оплати увімкнено, але не заповнено Merchant ID поточного режиму (тоді спосіб оплати приховується в оформленні замовлення), коли валюта за замовчуванням вашого магазину не USD і не COP, коли робочий режим використовується без HTTPS і коли для поточного режиму немає ключа підпису вебхука. Поки тестовий режим увімкнено, вона показує Тестовий режим увімкнено: використовується тестове середовище Kushki, реальні кошти не списуються. Якщо ви зберігаєте налаштування, коли спосіб оплати увімкнено, але Merchant ID поточного режиму не заповнено, налаштування зберігаються, а повідомлення нагадає ввести їх. Пробіли навколо ідентифікаторів видаляються під час збереження.

Kushki

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) і робочий облікові записи мають різні ID. Тестовий режим використовує лише тестові ID, робочий — лише робочі.

Test mode: використовує тестове середовище Kushki (UAT): тестові Merchant ID, тестову форму картки та тестовий API разом. Реальні кошти не списуються, а в оформленні замовлення показується позначка 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. Тримайте його в таємниці.

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

Webhook (рекомендовано)

Платежі підтверджуються одразу відповіддю API Kushki, тож вебхук не є обов'язковим. Крім того, він створює замовлення для платежу, відповідь за яким було втрачено (наприклад, через тайм-аут), і повідомляє про анулювання та повернення, зроблені в Kushki Console. У Kushki Console (Webhooks) додайте URL, який показано в Webhook URL, для платежів картками. З дружніми URL він має вигляд https://your-shop/module/wcp_kushki_payment/webhook, можливо, з кодом мови, наприклад /es/. Копіюйте URL точно так, як його показують налаштування. Зробіть це для тестового та для робочого облікового запису.

Модуль обробляє такі сповіщення про картки:

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

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

Clear saved secrets: позначте приватний Merchant ID або підпис вебхука та натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

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

Додатково

Debug log: записує запити та вебхуки Kushki у файл logs/kushki_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки завжди записуються. Журнали ніколи не містять Merchant ID, токенів карток чи електронних адрес клієнтів. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

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

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

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

Кнопка PrestaShop Place order залишається видимою, бо з нею пов'язана згода з умовами надання послуг. Якщо умови вже прийнято, платіж надсилається автоматично після кнопки оплати Kushki. Інакше покупець бачить Вашу картку прийнято Kushki. Прийміть умови надання послуг і натисніть «Place order», щоб сплатити. Якщо покупець натискає Place order, не використовуючи форму Kushki, з'являється повідомлення Введіть дані картки у формі Kushki і натисніть її кнопку оплати.

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

Якщо картку відхилено, замовлення не створюється, покупець повертається до етапу оплати з повідомленням Ваш платіж відхилено та причиною від Kushki і може спробувати іншу картку. У разі проблем із мережею, ключами або сервером покупець бачить Наразі не вдалося обробити платіж. Спробуйте ще раз за мить або оберіть інший спосіб оплати. Технічна причина записується в журнал. Повторне натискання, поки платіж обробляється, показує Платіж для цього замовлення вже обробляється. Зачекайте мить і перевірте статус замовлення.

Якщо відповідь Kushki втрачено (наприклад, через тайм-аут), покупець бачить загальне повідомлення, але спроба списання зберігається. Коли підписаний вебхук повідомляє про схвалене списання, замовлення створюється. Кошик, який уже має замовлення, або схвалене списання, для якого замовлення ще не створено, ніколи не списується повторно: покупець бачить підтвердження цього замовлення. Якщо покупець платить знову до того, як прийде будь-який вебхук, це нове списання; пізнє схвалення першого списання тоді лише додає примітку про можливе подвійне списання.

Вебхук працює, навіть коли магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину. 3-D Secure, правила антифроду та запропоновані розстрочки налаштовуються в Kushki Console.

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

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

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

No order yet: покупець не сплатив, картку відхилено, або відповідь Kushki втрачено і вебхук ще не надійшов. Існує лише кошик.

Payment accepted: Kushki підтвердив списання (відповіддю API або вебхуком). Платіж записується з референсом транзакції Kushki (або номером тікета) як ID транзакції. Примітка показує режим, номер тікета Kushki і референс.

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

Payment error: вебхук повідомив, що списання для замовлення на утриманні було відхилено.

Refunded: платіж було повернено через модуль.

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

Блок платежу Kushki

Сторінка замовлення показує блок Kushki payment з номером тікета, референсом транзакції, середовищем (з позначкою Test для тестових платежів), статусом списання, сумою списання та підсумком замовлення, формою повернення, історією повернень і Kushki notes замовлення.

Повернення

Kushki повертає списання повністю, тому можливі лише повні повернення. У блоці Kushki payment вже вказано суму, списану Kushki. За бажанням введіть причину і натисніть Refund via Kushki, потім підтвердьте питання Повернути весь платіж через Kushki? Цю дію не можна скасувати. Вам потрібне право редагувати замовлення. Для будь-якої іншої суми модуль показує Kushki повертає лише повний платіж. Введіть повну списану суму разом із сумою, і нічого не надсилається. Повернення виконується в сумі та валюті, які списав Kushki, тож у разі розбіжності сум покупець отримує назад саме те, що фактично списано, а не підсумок замовлення. Платіж можна повернути лише один раз.

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

Модуль не створює кредитових нот. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Kushki. Анулювання та повернення, зроблені в Kushki Console, надходять через вебхук і додаються до приміток. Статус замовлення автоматично не змінюється.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Kushki Payment — перший блок на сторінці Modules > Module Manager > VibeFox Kushki Payment > Configure, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ прихованим, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-payment-kushki і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

Якщо ключ не приймається, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on із датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати за останнім відомим статусом.

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

Без активного ключа Kushki не показується покупцям в оформленні замовлення. Якщо платіж все одно розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви ввійшли в адмін-панель, тому спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але протестувати його в оформленні замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не зачіпаються: платежі, що вже розпочато, як і раніше підтверджуються, а повернення працюють.

Коли ліцензія спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється під час роботи в адмін-панелі: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

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

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

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

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

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

Webhook answers Order mismatch: сповіщення не відповідає списанню цього кошика (неправильний ключ спроби або транзакція). Нічого не змінюється.

Webhook answers Busy, retry later: замовлення в цей момент оброблявся іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). Kushki може надіслати сповіщення повторно. Помилки завжди записуються в журнал.

URL вебхука в браузері показує лише POST: це нормально. URL приймає лише сповіщення від Kushki.

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

Покупець бачить Цей спосіб оплати недоступний у цьому магазині. Оплатіть карткою.: у формі Kushki обрано спосіб оплати, який не є карткою. Модуль списує кошти лише з карток.

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

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

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

Повернення не пропонується, з повідомленням «Для цього замовлення не знайдено номер тікета Kushki»: у замовлення немає підтвердженого списання Kushki. Поверніть його в Kushki Console.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Kushki Payment і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування та журнали видаляються. Якщо вимкнено, усі налаштування зберігаються для подальшого повторного встановлення. Записи платежів Kushki (списання та повернення) і статус замовлення Kushki payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату, номери тікетів Kushki та ID транзакцій.

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