VibeFox Kushki for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

HTTPS: Kushki требует, чтобы оформление заказа открывалось по HTTPS в рабочем режиме.

Аккаунт Kushki: нужны публичный и приватный Merchant ID вашего тестового (UAT) аккаунта Kushki и рабочего аккаунта. Их можно найти в 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, для платежей картой. При использовании ЧПУ он выглядит так: 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 и не поддерживается им.