VibeFox GoPay for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: GoPay принимает CZK, EUR, PLN, USD, GBP, HUF, RON и BGN. При другой валюте корзины способ оплаты скрыт на этапе оформления заказа.

Учётная запись GoPay: нужны GoID, Client ID и Client Secret вашей учётной записи мерчанта GoPay. Они находятся в настройках интеграции аккаунта. Тестовый аккаунт (sandbox) имеет собственные учётные данные. Для уведомлений в учётной записи GoPay ничего настраивать не нужно, но ваш магазин должен быть доступен из интернета.

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

Установка

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

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

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

4. Введите GoID, Client ID и Client Secret для sandbox, оставьте Test Mode включённым, включите Enable/Disable и нажмите Save.

5. Оформите тестовый заказ. Когда всё заработает, введите учётные данные рабочего режима и выключите Test Mode.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox GoPay Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Sandbox mode — test payments only или Production mode — real payments. Она предупреждает, если не заполнены GoID, Client ID или Client Secret текущего режима, а также если GoPay не принимает валюту магазина по умолчанию. В обоих случаях GoPay не предлагается на этапе оформления заказа. При сохранении кэшированные токены доступа GoPay очищаются, поэтому новые учётные данные начинают использоваться сразу.

GoPay

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

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

Description: описание способа оплаты, которое показывается при оформлении заказа. По умолчанию: Pay securely via GoPay - cards, wallets, bank transfers.

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

GoID, Client ID и Client Secret отображаются в вашей учётной записи мерчанта GoPay (настройки интеграции). Тестовый аккаунт (sandbox) имеет собственные учётные данные. Документация по API находится на doc.gopay.com.

Test Mode: отправляет платежи на gw.sandbox.gopay.com с учётными данными sandbox. Реальные деньги не списываются. Выключите, чтобы принимать реальные платежи с учётными данными рабочего режима. По умолчанию: включено.

Sandbox GoID: GoID вашей тестовой учётной записи GoPay (sandbox).

Sandbox Client ID: OAuth Client ID тестовой учётной записи.

Sandbox Client Secret: OAuth Client Secret тестовой учётной записи.

Production GoID: ваш идентификатор мерчанта GoPay (GoID).

Production Client ID: OAuth Client ID из GoPay.

Production Client Secret: OAuth Client Secret из GoPay.

GoID состоит только из цифр, например 8123456789. Если введено что-то другое, страница показывает ошибку, а предыдущее значение сохраняется.

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

Clear saved client secrets: отметьте флажок и нажмите Save, чтобы удалить оба сохранённых Client Secret. Пустое поле сохраняет сохранённое значение.

Оплата

Payment Page Language: язык страницы оплаты GoPay. По умолчанию: Automatic (site language, then billing country). Автоматический режим использует язык корзины покупателя; если GoPay его не поддерживает, решает страна выставления счёта, а в остальных случаях используется английский. Также можно зафиксировать один из 19 языков: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian или Russian.

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

Платежи, которые не соответствуют заказу, платежи после отмены и предварительно авторизованные платежи всегда переводятся в GoPay payment on hold.

Уведомления о платежах

Уведомление сообщает вашему магазину, что платёж совершён. Notification URL показан в этом разделе и передаётся в GoPay с каждым платежом, поэтому в учётной записи GoPay ничего настраивать не нужно. При использовании понятных URL он выглядит так: https://your-shop/module/wcp_gopay_gateway/webhook, возможно с кодом языка, например /en/. URL должен быть доступен из интернета: без защиты паролем и без межсетевого экрана перед ним. Он работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по стране в вашем магазине.

Уведомления GoPay содержат только ID платежа и не имеют подписи. Каждое уведомление проверяется запросом к API GoPay о состоянии платежа с учётными данными того режима, в котором был совершён платёж, и платёж должен быть создан модулем для корзины вашего магазина. Если состояние не удаётся получить от GoPay, магазин отвечает ошибкой, и GoPay повторяет уведомление. Без уведомлений заказ создаётся только тогда, когда покупатель возвращается в магазин после оплаты.

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

Logging: записывает события GoPay в файл logs/gopay_p_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки и предупреждения записываются всегда. Учётные данные, токены, данные карт, а также e-mail и имя покупателя никогда не записываются. По умолчанию: выключено.

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию GoPay) и подтверждает выбор. Модуль создаёт платёж GoPay на сумму корзины в валюте корзины, с товарами, доставкой и подарочной упаковкой, и отправляет покупателя на страницу оплаты GoPay. Там GoPay предлагает способы оплаты, включённые в вашей учётной записи GoPay, например банковские карты, банковские переводы и электронные кошельки. Имя, e-mail, телефон и адрес покупателя для выставления счёта передаются в GoPay; пустые поля не отправляются. В GoPay платёж отображается как Order PS- и номер корзины. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается как оплаченный только после подтверждения GoPay: уведомлением или запросом к API GoPay при возврате покупателя. Уведомление и возврат, пришедшие одновременно, обрабатываются по очереди, поэтому создаётся только один заказ. Затем покупатель видит стандартную страницу подтверждения заказа. Если заказ перешёл в GoPay payment on hold, на странице добавляется сообщение Your payment is being reviewed. We will contact you if anything else is needed.

Если GoPay ещё не подтвердил платёж, когда покупатель возвращается (например, банковский перевод в пути или GoPay недоступен), страница Payment confirmation показывает GoPay has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. с кнопкой Check again.

Если платёж не был завершён, отменён или истёк, покупатель возвращается к оформлению заказа с сообщением The GoPay payment was not completed. You can try again or choose another payment method. или The GoPay payment was cancelled or has expired. You can try again or choose another payment method. Корзина сохраняется, а новая попытка создаёт новый платёж GoPay. Корзина, для которой уже есть заказ, никогда не списывается повторно.

Если GoPay не может начать платёж, покупатель остаётся на этапе оформления заказа с коротким сообщением, например GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. или GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. Техническая причина записывается в журнал.

Способ оплаты покупатель выбирает на странице GoPay; в PrestaShop выбрать его нельзя. Модуль не поддерживает подписки и регулярные платежи, сохранённые карты, встроенную платёжную форму, а также списание или отмену предварительной авторизации из PrestaShop.

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

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

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

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

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

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

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

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

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

Возвраты

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

Модуль не создаёт кредитные накладные (credit slips). Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через GoPay.

Возвраты, выполненные в учётной записи GoPay, поступают через уведомления. Полный возврат переводит заказ в статус Refunded; частичный возврат добавляет примечание. В историю возвратов блока они не добавляются.

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

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

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

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

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

GoPay не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, для текущего режима заполнены GoID, Client ID и Client Secret, и что валюта корзины — одна из CZK, EUR, PLN, USD, GBP, HUF, RON или BGN. Страница настроек показывает предупреждение, когда учётные данные не заполнены. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

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

Notification answers Order not found: платёж создан не этим магазином, или его корзина была удалена.

Notification answers Payment state could not be verified: API GoPay недоступен, либо учётные данные этого режима отсутствуют или неверны. GoPay повторяет уведомление.

Notification answers Busy, retry later: корзину в тот же момент обрабатывал другой запрос, либо заказ не удалось создать (например, модуль отключён). GoPay повторяет уведомление. Включите Logging, чтобы увидеть причину.

Покупатель видит ошибку при выборе GoPay: включите Logging и посмотрите поле Log. Частая причина — неверные учётные данные или данные другого режима. Сообщение о платёжных данных означает, что GoPay не принял e-mail, телефон или адрес.

Тестовые платежи не подтверждают реальный заказ: sandbox и рабочий режим разделены. Каждый платёж проверяется в том режиме, в котором был создан. Переключите Test Mode на нужный режим и используйте его учётные данные.

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

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

Для разработчиков: хук actionGopayPaymentPayload изменяет запрос на оплату до его отправки в GoPay.

Удаление

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

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