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.