VibeFox PayPlug for PrestaShop — Помощь

Требования

PrestaShop: 8.0 – 9.x.

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

Валюта и суммы: евро (EUR), от 0,99 до 20 000,00 за платёж, значения PayPlug по умолчанию. При другой валюте корзины или вне этих пределов способ оплаты скрывается.

Аккаунт PayPlug: нужны секретные ключи вашего аккаунта PayPlug: тестовый ключ (sk_test_...) и/или рабочий ключ (sk_live_...). Никакие другие ключи не требуются, и в PayPlug не нужно настраивать уведомления. Ваш магазин должен быть доступен из интернета, чтобы получать уведомления; в противном случае заказы создаются, когда покупатель возвращается из PayPlug.

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

Установка

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

2. По завершении загрузки нажмите Configure или позже найдите VibeFox PayPlug Gateway в списке модулей и нажмите Configure.

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

4. Вставьте секретные ключи из портала PayPlug (см. Настройки).

5. Включите Enable/Disable и нажмите Save. Проверьте оплату с включённым Test Mode, затем выключите его, чтобы принимать настоящие платежи.

При установке модуль создаёт статус заказа PayPlug payment on hold. PrestaShop включает новый платёжный модуль для всех валют, стран и групп покупателей. Их можно ограничить в разделе Payment > Preferences.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox PayPlug Gateway > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если способ оплаты включён, но секретный ключ текущего режима пуст, а также если валюта магазина по умолчанию не EUR. В обоих случаях способ оплаты скрывается при оформлении заказа.

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

Enable/Disable: Enable PayPlug Gateway включает или выключает способ оплаты. По умолчанию: off.

Title: название способа оплаты, которое видит покупатель при оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: PayPlug. Обязательное поле.

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely by card via PayPlug.

Ключи API

Секретные ключи находятся в портале PayPlug в разделе Developers > API keys. В этом разделе есть ссылка на портал.

Test Mode: использует тестовый секретный ключ для новых платежей. Настоящие платежи не проводятся. Платежи, сделанные в другом режиме, для проверки статуса и возвратов по-прежнему используют ключ своего режима. По умолчанию: on. Пока режим включён, покупатели видят под способом оплаты надпись Test mode: no real payment will be made.

Test Secret Key: ваш тестовый секретный ключ PayPlug. Он начинается с sk_test_.

Live Secret Key: ваш рабочий секретный ключ PayPlug. Он начинается с sk_live_.

Ключ с неверным префиксом не сохраняется. Страница показывает, например, Test Secret Key must start with "sk_test_". The previous value was kept. Сохранённые ключи больше не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved keys: отметьте ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Notification URL: адрес, который модуль передаёт в PayPlug с каждым платежом. При включённых ЧПУ он выглядит так: https://your-shop/module/wcp_payplug_gateway/webhook. В портале PayPlug ничего вводить не нужно. URL должен быть доступен из интернета; в противном случае заказы создаются, когда покупатель возвращается из PayPlug.

Заказы

Order Status After Payment: статус заказа, который устанавливается после успешной оплаты. Статус устанавливается сразу, без второй смены статуса.

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

Logging: записывает вызовы API и уведомления в файл logs/ppg_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки и предупреждения записываются всегда. Секретные ключи, данные карт и данные покупателей никогда не записываются. По умолчанию: off.

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

Delete Data on Uninstall: если включено, настройки модуля и его журнал удаляются при удалении модуля. Идентификаторы платежей PayPlug, сохранённые в заказах, и статус заказа PayPlug payment on hold сохраняются. По умолчанию: off.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию PayPlug, с логотипом PayPlug). В тестовом режиме у этой опции отображается Test mode: no real payment will be made. После подтверждения модуль создаёт платёж PayPlug на сумму корзины в центах и отправляет покупателя на страницу оплаты PayPlug. Адреса выставления счёта и доставки, адрес электронной почты и язык корзины передаются в PayPlug. Там покупатель оплачивает картой. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается как оплаченный только после подтверждения PayPlug: модуль получает данные платежа из API PayPlug, когда приходит уведомление и когда покупатель возвращается. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your payment with PayPlug has been received. Если заказ на удержании, страница сообщает We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Если заказ в статусе Payment error или был отменён без оплаты, страница сообщает Your PayPlug payment was not completed. Please contact us about this order. Если при возврате покупателя не удалось запросить PayPlug, страница Payment confirmation показывает тот же текст «we are confirming» и кнопку Check again; уведомление создаст заказ, как только придёт.

Если покупатель отменяет оплату на странице PayPlug, страница оплаты закрывается в PayPlug, поэтому её нельзя оплатить позже по ошибке. Покупатель возвращается к оформлению заказа с сообщением: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. или, если платёж остался открытым, Your PayPlug payment was not completed. You can try again or choose another payment method. Корзина сохраняется.

Когда покупатель оплачивает ту же корзину повторно, модуль сначала проверяет предыдущую попытку. Если за это время её оплатили, заказ создаётся без новой оплаты. Если она всё ещё открыта на ту же сумму, используется та же страница оплаты. В противном случае старая страница закрывается в PayPlug и создаётся новый платёж.

Если PayPlug не может начать оплату, покупатель остаётся при оформлении заказа с коротким сообщением, например PayPlug could not accept your billing details (postcode). Please check them and try again. или The payment provider could not be reached. Please try again in a moment. Техническая причина записывается в журнал.

Уведомление работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

Платежи списываются сразу. Модуль не поддерживает рассрочку Oney, сохранённые карты для оплаты в один клик, встроенную форму оплаты, подписки и отложенное списание.

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

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

No order yet: покупатель был отправлен в PayPlug и не оплатил, или PayPlug ещё не подтвердил платёж. Существует только корзина.

Payment accepted or Delivered: платёж подтверждён. Статус соответствует Order Status After Payment. Платёж записывается с идентификатором PayPlug (pay_...) в качестве ID транзакции, а примечание показывает платёж PayPlug и его режим.

PayPlug payment on hold: оплаченная сумма или валюта отличаются от корзины (примечание amount/currency mismatch, например корзина была изменена после начала оплаты); или тестовый платёж был сделан, пока магазин работал в рабочем режиме, поэтому деньги не получены и платёж не записывается; или платёж поступил для отменённого заказа; или платёж авторизован, но не списан (спишите его в портале PayPlug; заказ отмечается как оплаченный, когда PayPlug сообщает об оплате). Примечание объясняет, что нужно проверить.

Payment error: авторизованный платёж заказа на удержании не прошёл или был отменён.

Refunded: платёж полностью возвращён через модуль.

Если повторная попытка оплаты уже оплаченной корзины тоже прошла, заказ не меняется. Примечание просит вас вернуть дублирующий платёж в портале PayPlug. Оплаченный, отменённый или возвращённый заказ никогда не открывается повторно по более позднему уведомлению.

Блок платежа PayPlug

На странице заказа отображается блок PayPlug payment с идентификатором платежа PayPlug, статусом платежа, оплаченной и возвращённой суммой, меткой Test mode для тестовых платежей, историей возвратов и PayPlug notes заказа.

Возвраты

В блоке PayPlug payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via PayPlug. Подтвердите вопрос Refund this amount through PayPlug? This cannot be undone. Поддерживаются полные и частичные возвраты. Вам нужно право редактировать заказы; доступ к страницам модулей не требуется. Возвраты выполняются в пределах суммы, которую PayPlug фактически списал, поэтому после расхождения сумм можно вернуть то, что заплатил покупатель, а не итог заказа. Возврат направляется на платёж, которым заказ фактически оплачен, с секретным ключом режима (тестового или рабочего), в котором он был проведён, поэтому этот ключ должен быть настроен. Если PayPlug не принимает возврат, блок показывает ошибку, и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания с идентификатором возврата PayPlug и причиной. Полный возврат переводит заказ в статус Refunded. Частичный возврат не меняет статус. Возвраты доступны, когда PayPlug сообщил, что платёж оплачен.

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через PayPlug.

Возвраты, выполненные в портале PayPlug, поступают через уведомление и добавляются в примечания один раз. Они не учитываются в блоке и не меняют статус заказа или кредит-ноты. При необходимости запишите их вручную.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox PayPlug Gateway является первым блоком на странице Modules > Module Manager > VibeFox PayPlug Gateway > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату окончания действия лицензии и ваш домен) и кнопки Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже них находятся строка Product: presta-payment-payplug и ссылка 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.

Без активного ключа PayPlug не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит сообщение This payment method is not available. Please choose another one. Витрина магазина не знает, что вы вошли в панель администратора, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

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

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

PayPlug не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, в текущем режиме задан секретный ключ (Test Secret Key в тестовом режиме, Live Secret Key в рабочем режиме), валюта корзины — EUR, а сумма корзины находится в пределах от 0,99 до 20 000,00 EUR. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя. Разработчики могут изменить валюты и лимиты с помощью хуков actionWcpPayplugSupportedCurrencies и actionWcpPayplugAmountLimits (значения в центах).

Платёж прошёл, но заказ не создан: уведомление не дошло до вашего магазина, и покупатель не вернулся. Проверьте, что ваш магазин доступен из интернета по Notification URL, указанному в настройках, например что его не блокируют брандмауэр или парольная защита. Включите Logging и посмотрите поле Log на отклонённые уведомления.

Уведомление отвечает Verification failed.: платёж не удалось прочитать через API PayPlug, например потому что PayPlug не ответил или не задан секретный ключ режима платежа. Заказ не меняется, и PayPlug отправит уведомление повторно.

Уведомление отвечает Temporarily unavailable.: корзина в это же время обновлялась другим запросом, например возвратом покупателя, или заказ не удалось создать (например, модуль отключён). PayPlug отправит уведомление повторно. Причина указана в журнале.

Уведомление отвечает Unknown payment. или Payment does not belong to the order.: платёж создан не этим магазином или не для этой корзины, например платёж другого магазина на том же аккаунте PayPlug. Он игнорируется.

URL уведомления в браузере показывает Method not allowed.: это нормально. URL принимает только запросы от PayPlug.

Покупатель видит ошибку при выборе PayPlug: включите Logging и посмотрите поле Log. Неверный ключ даёт This payment method is temporarily unavailable. Please choose another payment method.; другие сообщения называют поле оплаты, которое отклонил PayPlug.

Заказ в статусе PayPlug payment on hold после оплаты: прочитайте примечания в блоке PayPlug payment (см. Статусы заказа), затем обработайте заказ или верните платёж.

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

Возврат не проходит с сообщением Unexpected response from PayPlug.: PayPlug ответил без корректного возврата. Ничего не записано. Проверьте возврат в портале PayPlug, прежде чем повторять попытку.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox PayPlug Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки модуля и журнал удаляются. Если выключено, все настройки сохраняются для последующей переустановки. Записи о платежах и возвратах PayPlug и статус заказа PayPlug payment on hold всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после переустановки. Существующие заказы сохраняют свои примечания об оплате и идентификаторы транзакций.

PayPlug — товарный знак его владельца. Модуль не связан с PayPlug и не одобрен PayPlug.