VibeFox Kushki for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

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

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

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

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

Установка

Архив для загрузки — один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_kushki_payment-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_kushki_payment.ocmod.zip. Установите только пакет для вашей версии OpenCart. Лицензионный ключ один и тот же для обеих версий.

OpenCart 3

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_kushki_payment-oc3-(version).ocmod.zip. Расширение не вносит изменений OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload из этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Kushki Payment и нажмите Install (зелёная кнопка +). Вашему административному пользователю нужно право на изменение списка расширений оплаты.

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек. Вставьте лицензионный ключ VibeFox в поле License key в блоке лицензии в верхней части страницы и нажмите Activate (см. Лицензионный ключ).

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

5. Включите Enable / Disable, нажмите Save и выполните тестовый заказ. Когда всё будет готово, введите боевые Merchant ID (и боевую подпись вебхука) и выключите Test mode.

OpenCart 4

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_kushki_payment.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Kushki Payment, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ, Merchant ID и вебхук так же, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL вебхука (см. Вебхук).

Новая установка стартует с выключенным способом оплаты и включённым тестовым режимом.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Kushki Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если способ оплаты включён, но Merchant ID текущего режима не заполнены (тогда способ оплаты скрыт на оформлении заказа), если валюта по умолчанию вашего магазина не USD и не COP, если боевой режим используется без HTTPS (на OpenCart 4 — когда адрес витрины начинается с http://) и если для текущего режима не задан ключ подписи вебхука. Пока включён тестовый режим, она показывает Test mode is on: the Kushki test environment is used, no real money is charged. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении поле Title не должно быть пустым и не должно быть длиннее 128 символов, Sort Order должно быть целым числом (отрицательные числа допускаются), Total — числом, не меньше 0, а каждый статус заказа должен существовать. Если поле заполнено неверно, ничего не сохраняется, и страница указывает на это поле. Пробелы вокруг ID удаляются при сохранении.

Kushki

Enable / Disable: Enable Kushki card payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель на оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Credit / debit card (Kushki). Обязательно, до 128 символов.

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

Sort Order: положение Kushki среди способов оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Kushki только для адресов оплаты в выбранной географической зоне. По умолчанию: All zones. Географические зоны настраиваются в System > Localisation > Geo Zones.

Total: сумма заказа в валюте магазина по умолчанию, которой должен достичь заказ, чтобы Kushki предлагался. Оставьте поле пустым, чтобы предлагать Kushki при любой сумме.

Учётные данные API

Скопируйте публичный и приватный Merchant ID из Kushki Console (Developers > Credentials; страница содержит ссылку на Console). Тестовый (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 и подписи вебхуков больше никогда не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённое значение, отметьте Clear the saved value on save под полем и нажмите Save.

Вебхук (рекомендуется)

Платежи подтверждаются сразу ответом API Kushki, поэтому вебхук не обязателен. Он дополнительно подтверждает платёж, ответ по которому был потерян (например, из-за тайм-аута), и сообщает об аннулированиях, возвратах и чарджбэках, сделанных в Kushki Console. В Kushki Console (Webhooks) добавьте URL, который показан в этом разделе в поле Webhook URL. На OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_kushki_payment/webhook, на OpenCart 4 — так: https://your-store/index.php?route=extension/wcp_kushki_payment/payment/wcp_kushki_payment.webhook. Он формируется из адреса витрины вашей установки OpenCart. Скопируйте URL точно так, как его показывают настройки. Сделайте это для тестового аккаунта и для боевого аккаунта.

Расширение обрабатывает эти уведомления по картам:

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

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

Вебхуки без корректной подписи отклоняются. Уведомление должно быть подписано ключом того режима, в котором был сделан платёж, поэтому тестовое уведомление никогда не подтверждает боевой платёж. Без ключа подписи все уведомления вебхуков отклоняются, но платежи продолжают работать, потому что подтверждаются ответом API.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Заказ получает статус только после того, как Kushki одобрил списание с карты. Каждое поле ниже перечисляет статусы заказов вашего OpenCart.

Order Status After Payment: Kushki одобрил списание с номером тикета на сумму и в валюте заказа. По умолчанию: В обработке.

On Hold (Review) Status: Kushki одобрил списание без номера тикета или сообщил о другой сумме или валюте. Заметка объясняет причину; проверьте платёж в Kushki Console перед выполнением заказа. По умолчанию: Ожидает оплаты, так как в OpenCart нет статуса «На удержании». Вы можете создать свой статус в System > Localisation > Order Statuses и выбрать его здесь.

Failed Status: заказ в статусе проверки, списание по которому Kushki позже сообщает как отклонённое (вебхук). По умолчанию: Неудавшийся.

Canceled Status: заказы в этом статусе (или в статусе возврата) никогда не открываются повторно поздним вебхуком. По умолчанию: Отменён.

Refunded Status: устанавливается после возврата платежа со вкладки заказа. По умолчанию: Возвращён.

Дополнительно

Debug log: записывает запросы и вебхуки Kushki в файл kushki_p_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть через веб. Предупреждения и ошибки всегда записываются. В логах никогда не бывает Merchant ID, токенов карт или адресов электронной почты покупателей. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы его очистить.

Delete data on uninstall: если включено, при удалении расширения удаляются настройки и журнал. Записи о платежах Kushki (списаниях и возвратах) всегда сохраняются, поэтому старые заказы можно вернуть и после повторной установки. По умолчанию: выключено.

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. Приватные Merchant ID и подписи вебхуков не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые секреты сохраняются.

Оформление заказа

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit / debit card (Kushki)). OpenCart создаёт заказ на шаге Confirm Order, по-прежнему без статуса. Там покупатель видит ваше описание и форму карты Kushki с суммой заказа в валюте заказа. Покупатель вводит карту, выбирает рассрочку, если её предлагает форма Kushki, и нажимает кнопку оплаты внутри формы Kushki. Платёж затем отправляется автоматически, как написано в примечании под формой: Enter your card in the secure Kushki form above and press its pay button — the payment is sent automatically. Если покупатель нажимает вместо этого кнопку OpenCart Confirm Order, появляется сообщение Please enter your card details in the Kushki form and press its pay button.

На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options. Форма карты Kushki затем появляется в блоке подтверждения заказа внизу страницы оформления, над кнопкой Confirm Order, и пересоздаётся для текущей суммы заказа каждый раз, когда OpenCart перезагружает этот блок.

Затем ваш магазин списывает деньги с карты на сервере. Заказ отмечается оплаченным только после того, как Kushki подтвердит платёж номером тикета. После этого заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, корзина очищается, и покупатель видит страницу успешного заказа OpenCart с сообщением Your card payment has been received. Сумма и валюта, сообщённые Kushki, сверяются с заказом. Заказ в статусе проверки показывает Your payment is being reviewed. We will update your order as soon as the review is complete.

Если карта отклонена, заказ остаётся без статуса, покупатель остаётся на шаге Confirm Order с сообщением 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.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 сохраняет один заказ для оформления и обновляет его. В любом случае корзина оплачивается только один раз: корзина, которая уже оплачена, или одобренное списание, заказ по которому ещё не имеет статуса, никогда не списываются повторно, и покупатель видит страницу успеха. Если ответ Kushki потерян (например, из-за тайм-аута), покупатель видит общее сообщение, но попытка списания сохраняется. Когда подписанный вебхук сообщает об одобренном списании, заказ получает статус. Если покупатель платит снова до прихода какого-либо вебхука, это новое списание; поздно пришедшее одобрение первого списания лишь добавляет заметку о возможном двойном списании.

OpenCart 4 сохраняет заказ в оформлении до показа страницы успеха. Если за это время заказ был закрыт (например, позже отклонено списание на проверке или вы его отменили), либо он уже оплачен за более раннюю корзину, а покупатель с тех пор изменил корзину, покупатель при оплате возвращается на страницу оформления, а следующее нажатие Confirm Order создаёт новый заказ. Над страницей оформления покупатель видит Your previous order is closed (declined, cancelled or refunded by the store). Please confirm the order again: the cart will be paid with a new order., если заказ был закрыт, или Your previous order is already paid for other cart contents. Please confirm the order again: the current cart will be paid with a new order., если он был оплачен за другую корзину. Изменение корзины, включая новое количество, считается новой корзиной, которой нужна собственная оплата.

Вебхук работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы расширений оплаты, а в OpenCart 4 расширение добавляет для него стартовое действие (startup action). 3-D Secure, правила антифрода и предлагаемая рассрочка настраиваются в Kushki Console.

Расширение поддерживает только одностадийные платежи картами. У него нет частичных возвратов, сохранённых карт или подписок, нет оплаты наличными, банковским переводом (PSE) или переводом на дебетовую карту, а также раздельной авторизации и захвата.

Заказы и возвраты

Статусы заказов

Нет статуса (отсутствующий заказ): покупатель не оплатил, карта была отклонена, либо ответ Kushki потерян и вебхук ещё не пришёл. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Order Status After Payment (по умолчанию В обработке): Kushki подтвердил списание (ответом API или вебхуком). Заметка показывает режим, сумму, номер тикета Kushki и референс.

On Hold (Review) Status (по умолчанию Ожидает оплаты): Kushki вернул успешный результат без номера тикета либо сообщил о сумме или валюте, отличных от заказа. Заметка объясняет это. Проверьте транзакцию в Kushki Console и выполните заказ или возвратите платёж. Последующее подписанное одобрение с номером тикета и совпадающей суммой переводит заказ в статус Order Status After Payment.

Failed Status (по умолчанию Неудавшийся): вебхук сообщил, что списание по заказу в статусе проверки было отклонено.

Refunded Status (по умолчанию Возвращён): платёж был возвращён через расширение.

Если Kushki сообщает о ещё одном одобренном списании по заказу, который уже оплачен, отменён или возвращён, заказ не меняется. Заметка просит вас проверить двойное списание и вернуть его в Kushki Console. Вебхук из тестовой среды для реального платежа (или наоборот) игнорируется с заметкой.

Заметки — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox Kushki Payment

В Sales > Orders откройте заказ, оплаченный через Kushki. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Kushki Payment показывает Ticket number (с меткой TEST для тестовых платежей), Transaction reference, Environment, Result, суммы Charged / order amount, форму возврата, историю возвратов и Kushki notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

Kushki возвращает всё списание целиком, поэтому возможны только полные возвраты. На вкладке VibeFox Kushki Payment заполнено поле Amount, которое списал Kushki. При необходимости введите Reason (optional), нажмите Refund via Kushki и подтвердите вопрос Refund the full payment through Kushki? This cannot be undone. Вам нужно право на изменение расширения (задаётся в System > Users > User Groups). Для любой другой суммы расширение показывает Kushki refunds the full payment only. Enter the full charged amount и ничего не отправляет. Возврат выполняется в сумме и валюте, которые списал Kushki, поэтому при расхождении суммы покупатель получает обратно то, что реально было списано, а не сумму заказа. Платёж можно вернуть только один раз.

Возврат отправляется в том режиме, в котором был сделан платёж (тестовом или боевом), поэтому приватный Merchant ID этого режима должен быть задан. Если Kushki не принимает возврат, вкладка показывает Kushki refund failed с кодом и сообщением Kushki, и возврат не записывается. Успешный возврат добавляется в историю возвратов и заметки с номером тикета возврата Kushki, а заказ переводится в Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Для возврата нужно подтверждённое списание Kushki с номером тикета.

Возвраты товаров в Sales > Returns не возвращают деньги через Kushki. Аннулирования и возвраты, сделанные в Kushki Console, приходят вебхуком и добавляются в заметки. Статус заказа автоматически не меняется.

Лицензионный ключ

Расширение работает с лицензионным ключом VibeFox с сайта vibefox.net. Блок лицензии License — VibeFox Kushki Payment — это первый блок в разделе Extensions > Extensions > Payments > VibeFox Kushki Payment > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-kushki и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменять ключ могут только администраторы с правом Modify для расширения. Тексты блока следуют языку администратора (включены английский и русский).

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

Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает его место для домена. Освободите место в вашем аккаунте на vibefox.net.

Без активного ключа Kushki не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Администратор, вошедший в административную часть в том же браузере, по-прежнему видит способ оплаты в магазине, отмеченный как (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать расширение до покупки ключа. На OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без активного ключа способ оплаты скрыт для всех. После того как вы один раз откроете страницу Edit, на административной панели Dashboard появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда лицензия истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется автоматически при открытии административного Dashboard или страницы Edit: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. При удалении расширения лицензионный ключ и статус лицензии удаляются всегда.

Устранение неполадок

Kushki не появляется на оформлении заказа: проверьте, что лицензия активна, Enable / Disable включено и в текущем режиме заполнены оба Merchant ID: тестовые в тестовом режиме, боевые в боевом. Страница настроек показывает предупреждение, если ID не заполнены. Проверьте, что валюта заказа — USD или COP, что адрес оплаты входит в выбранную Geo Zone и что сумма заказа достигает Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: ответ API Kushki был потерян, например из-за тайм-аута. Вебхук подтверждает такие платежи. В Kushki Console проверьте, что URL вебхука точно совпадает с показанным в Webhook URL, для аккаунта того режима, который вы используете, и что ключ подписи этого аккаунта находится в соответствующем поле (Test webhook signature или Live webhook signature). Одобренное списание без оплаченной суммы и валюты переводит заказ в On Hold (Review) Status.

Вебхук отвечает Webhook signature not configured: не задана ни одна подпись вебхука. Вставьте ключ подписи в настройки.

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

Вебхук отвечает Order mismatch: уведомление не относится к попытке списания этого заказа (неверный ключ попытки или транзакция). Ничего не меняется.

Вебхук отвечает Busy, retry later: заказ в тот же момент обрабатывал другой запрос, либо не удалось установить статус заказа. Kushki может отправить уведомление повторно. Ошибки всегда записываются в журнал.

URL вебхука показывает только POST в браузере: это нормально. URL принимает только уведомления от 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 и посмотрите поле Log на странице расширения. This payment method is not available. Please reload the checkout page. означает, что сессия оформления больше не соответствует заказу или способ оплаты тем временем выключили: покупателю нужно перезагрузить оформление заказа. Неверный или отсутствующий приватный Merchant ID даёт общее сообщение о том, что платёж не удалось обработать.

Покупатель видит Your payment was received, but the order could not be completed automatically: Kushki одобрил списание, но OpenCart не смог установить статус заказа. Причина указана в журнале. Следующая попытка оплаты той же корзины установит статус без нового списания.

Возврат не проходит с сообщением о режиме: платёж был сделан в тестовом или боевом режиме, а приватный Merchant ID этого режима не задан. Введите его и попробуйте снова.

На вкладке нет формы возврата: вкладка объясняет причину: платёж уже возвращён, у заказа нет номера тикета Kushki (No Kushki ticket number found for this order — refund it in the Kushki Console.), ваша группа пользователей не имеет права изменять расширение, или не задан приватный Merchant ID режима платежа.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Kushki Payment. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable / Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения также удаляется (на OpenCart 4 также его события, в том числе показывающее сообщение над страницей оформления, и стартовое действие (startup action), которое пропускает вебхук в режиме обслуживания). Если Delete data on uninstall включено, удаляются остальные настройки (название, описание, тестовый режим, Merchant ID, подписи вебхуков, логирование) и журнал. Если выключено, они сохраняются для повторной установки. Записи о платежах Kushki (списаниях и возвратах) всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои заметки об оплате.

На OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Kushki Payment в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Kushki — торговая марка её владельца. Это расширение не связано с Kushki и не одобрено Kushki.