VibeFox SimplePay for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта магазина: HUF, EUR или USD. SimplePay не принимает другие валюты, и способ оплаты не предлагается для корзин в них.

Учётные записи мерчанта SimplePay: SimplePay выдаёт отдельную учётную запись мерчанта для каждой валюты, а также отдельные учётные записи для рабочего и тестового режимов (sandbox). Для каждой учётной записи нужны её MERCHANT и SECRET KEY из кабинета мерчанта SimplePay (admin.simplepay.hu для рабочего режима, sandbox.simplepay.hu для тестового), account > Technical data. Если вы продаёте только в HUF, достаточно учётной записи HUF. Никакие другие ключи не нужны.

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

Установка

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

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

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

4. Введите MERCHANT и SECRET KEY ваших учётных записей SimplePay для каждой валюты, в которой вы продаёте: тестовые учётные записи (sandbox) для проверки и рабочие учётные записи для реальных платежей (см. раздел «Настройка»).

5. Скопируйте IPN URL, показанный на странице Configure, в каждую учётную запись мерчанта (рабочую и тестовую) в кабинете мерчанта SimplePay.

6. Включите Enable/Disable и нажмите Save. Проверьте платёж при включённом Sandbox mode, а затем выключите Sandbox mode, чтобы принимать реальные платежи.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox SimplePay Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если основная валюта магазина не поддерживается SimplePay или для неё нет учётной записи мерчанта в текущем режиме. В обоих случаях способ оплаты не предлагается для корзин в этой валюте. Пока включён тестовый режим, страница показывает Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged.

SimplePay (OTP)

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

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

Description: текст, который отображается под способом оплаты на оформлении заказа. По умолчанию: Pay securely with your credit or debit card via SimplePay. Венгерские мерчанты могут указать здесь декларацию о передаче данных SimplePay (со ссылкой).

Sandbox mode: использует тестовую среду SimplePay (sandbox) для тестовых платежей с тестовыми учётными записями. Переключаются одновременно адрес API и учётные записи мерчанта. Реальные деньги не списываются. По умолчанию: включено. Выключите, чтобы принимать реальные платежи с рабочими учётными записями. Пока режим включён, покупатели видят под способом оплаты Sandbox mode: no real payment is taken. Заказы, начатые в тестовом режиме, всегда возвращаются в тестовом режиме.

Рабочие учётные записи мерчанта

Учётные записи, которые используются, когда Sandbox mode выключен. Заполните учётные записи для валют, в которых продаёт ваш магазин. Значения MERCHANT и SECRET KEY находятся в кабинете мерчанта SimplePay (admin.simplepay.hu), account > Technical data. Учётная запись используется только тогда, когда заполнены оба поля.

HUF account — Merchant ID: MERCHANT вашей рабочей учётной записи HUF.

HUF account — Secret key: SECRET KEY вашей рабочей учётной записи HUF.

EUR account — Merchant ID и EUR account — Secret key: то же для вашей рабочей учётной записи EUR.

USD account — Merchant ID и USD account — Secret key: то же для вашей рабочей учётной записи USD.

Тестовые учётные записи мерчанта

Учётные записи, которые используются, когда Sandbox mode включён. Поля такие же, как для рабочих учётных записей: HUF account — Merchant ID, HUF account — Secret key и такие же пары для EUR и USD. Значения возьмите в кабинете тестового мерчанта SimplePay (sandbox.simplepay.hu), account > Technical data.

Сохранённые секретные ключи больше не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

IPN URL

IPN — это сообщение, которое SimplePay отправляет в ваш магазин при изменении статуса платежа. Именно так обычно создаётся заказ. В разделе показан IPN URL вашего магазина. При использовании понятных URL он выглядит так: https://your-shop/module/wcp_simplepay_gateway/ipn, возможно, с кодом языка, например /en/. Укажите этот URL для каждой учётной записи мерчанта, рабочей и тестовой, в кабинете мерчанта SimplePay. Копируйте URL точно так, как он показан в настройках, потому что перенаправленный IPN теряется.

IPN должен быть подписан SECRET KEY той учётной записи мерчанта, которую он называет, в том режиме (тестовом или рабочем), в котором был запущен платёж. IPN без верной подписи отклоняются. Модуль подтверждает каждый верный IPN для SimplePay в подписанной форме, которую требует SimplePay. Используются следующие статусы IPN:

Статусы отклонённых, отменённых и просроченных платежей записываются только для последней попытки оплаты корзины, у которой ещё нет заказа. Остальные статусы записываются в журнал и ничего не меняют. Без IPN заказ создаётся только тогда, когда покупатель возвращается в магазин после успешной оплаты.

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

Заказы

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

Платёж на сумму или в валюте, отличных от заказа, всегда переводит заказ в статус SimplePay payment on hold.

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

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

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

Delete Data on Uninstall: если включено, при удалении модуля удаляются настройки шлюза и журнал. Данные заказов (транзакции и возвраты SimplePay) всегда сохраняются. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию SimplePay (Card Payment)) и видит примечание You will be redirected to the SimplePay payment page to pay by card. После подтверждения модуль запускает платёж картой SimplePay на сумму корзины в валюте корзины через учётную запись мерчанта этой валюты в текущем режиме и отправляет покупателя на платёжную страницу SimplePay. E-mail покупателя и, если он заполнен полностью, адрес для выставления счёта передаются в SimplePay. Платёжная страница использует язык магазина, если SimplePay его поддерживает, иначе английский. Начатый платёж можно оплатить в течение 30 минут. На этом этапе заказа ещё нет.

После успешного платежа покупатель возвращается в ваш магазин. Один только возврат заказ не оплачивает: модуль запрашивает у SimplePay статус транзакции подписанным запросом, поэтому заказ создаётся, даже если IPN пришёл с опозданием. Заказ отмечается оплаченным только после подтверждения SimplePay. Затем покупатель видит стандартную страницу подтверждения заказа с Successful transaction. SimplePay transaction ID: и ID. Если SimplePay ещё не подтвердил платёж, страница Payment confirmation показывает Your payment is being confirmed by SimplePay. SimplePay transaction ID: с ID и кнопку Check again; IPN создаст заказ, как только придёт.

Если платёж не прошёл, отменён или просрочен, покупатель возвращается на оформление заказа с сообщением SimplePay и ID транзакции, например Cancelled payment. You cancelled the payment или Timeout. The time allowed to complete the payment has expired. При неудачном платеже покупателю предлагается проверить введённые данные и обратиться в банк, выпустивший карту. Корзина сохраняется, и покупатель может попробовать снова. Каждая новая попытка получает собственный референс SimplePay: PS, номер корзины и номер попытки, например PS123-1, PS123-2.

Если SimplePay не может запустить платёж, покупатель видит The SimplePay payment could not be started. Please try again or choose another payment method. Если для валюты корзины нет учётной записи мерчанта, сообщение таково: SimplePay is not available for the currency of this order. Please choose another payment method. Техническая причина записывается в журнал.

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

Модуль принимает только разовые платежи картами, которые списываются на странице SimplePay. Нет сохранённых карт и оплаты в один клик, подписок и регулярных платежей, раздельных авторизации и списания.

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

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

Заказа пока нет: покупатель был отправлен в SimplePay и не оплатил, платёж не прошёл, был отменён или просрочен, либо SimplePay ещё не подтвердил платёж. Существует только корзина.

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

SimplePay payment on hold: сумма или валюта корзины были изменены после запуска платежа, поэтому оплаченная сумма отличается от суммы заказа. Платёж не записывается. Примечание показывает обе суммы. Проверьте заказ и выполните его или сделайте возврат платежа в кабинете мерчанта SimplePay. Если затем другая попытка оплаты той же корзины пройдёт на верную сумму, заказ перейдёт в оплаченный статус.

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

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

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

На странице заказа отображается блок SimplePay payment с ID транзакции, референсом заказа (orderRef), учётной записью мерчанта и режимом, статусом SimplePay, оплаченной и возвращённой суммами, значком Sandbox для тестовых платежей, попытками оплаты корзины (если их было больше одной), историей возвратов и SimplePay notes заказа.

Возвраты

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

Модуль не создаёт кредитных нот. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через SimplePay. Возвраты, сделанные в кабинете мерчанта SimplePay, не синхронизируются с PrestaShop. Регистрируйте их вручную.

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

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

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

Один ключ работает на одном домене: домен основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в своём аккаунте vibefox.net.

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

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

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

SimplePay не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, валюта корзины — HUF, EUR или USD, и для этой валюты заполнены Merchant ID и Secret key в текущем режиме: тестовые учётные записи, пока включён Sandbox mode, рабочие — пока он выключен. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: IPN не дошёл до магазина. В кабинете мерчанта SimplePay проверьте IPN URL учётной записи мерчанта, которую вы используете (рабочей или тестовой, валюта корзины). Он должен точно совпадать с URL, показанным в настройках, а ваш сервер должен быть доступен из интернета. Заказ также создаётся, когда покупатель возвращается в магазин после оплаты.

IPN отвечает Invalid signature: IPN указывает учётную запись мерчанта, которой нет в настройках, её Secret key неверен, либо он подписан учётной записью режима, отличного от режима платежа. Введите MERCHANT и SECRET KEY точно так, как их показывает кабинет мерчанта SimplePay. SimplePay повторяет неподтверждённые IPN.

IPN отвечает Order not found или Unknown transaction: IPN относится к платежу, который этот магазин не запускал. Ничего не меняется.

IPN отвечает Busy, retry: корзину в тот же момент обрабатывал другой запрос, либо заказ не удалось создать (например, модуль отключён). SimplePay повторяет IPN. Причина записывается в журнал.

Покупатель видит The SimplePay payment could not be started: посмотрите поле Log на странице модуля. Неверный секретный ключ даёт Invalid response signature from SimplePay. Check the secret key of the merchant account. Ошибки SimplePay записываются в журнал с их кодами.

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

Заказ переходит в статус SimplePay payment on hold после оплаты: прочитайте примечания в блоке SimplePay payment. Сумма или валюта корзины были изменены после запуска платежа. Выполните заказ или сделайте возврат платежа в кабинете мерчанта SimplePay.

Возврат не проходит: прочитайте сообщение в блоке. SimplePay refunds in HUF must be whole amounts. означает, что сумма в HUF содержала десятичные знаки. Если сообщение говорит, что учётная запись мерчанта этого платежа не настроена, введите заново учётную запись (валюту и режим), с которой был совершён платёж. Если SimplePay вернул другую сумму, сообщение просит проверить возврат в кабинете SimplePay.

Удаление

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

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