VibeFox Eupago for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: евро (EUR). Eupago принимает платежи только в евро, поэтому для корзин в других валютах способ оплаты скрывается при оформлении заказа.

Аккаунт Eupago: нужны API-ключ вашего канала Eupago и ключ Webhook 2.0, который вы создаёте в бэк-офисе Eupago (см. Настройки). Рабочий бэк-офис — clientes.eupago.pt, тестовый (sandbox) — sandbox.eupago.pt. Тестовая и рабочая среды — это разные аккаунты с разными ключами.

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

Установка

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

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

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

4. Введите API-ключ вашего канала Eupago, создайте Webhook 2.0 в бэк-офисе Eupago и вставьте его ключ (см. Настройки).

5. Выберите Payment Method, включите Enable/Disable и нажмите Save. Оформите тестовый заказ в режиме sandbox, затем выключите Sandbox Mode.

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

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Eupago Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Когда способ оплаты включён, страница предупреждает над полями, если API-ключ текущего режима пуст (тогда способ оплаты скрывается при оформлении заказа), либо показывает Sandbox mode: no real payments are taken., пока включён режим sandbox.

Eupago

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

Title: название способа оплаты, которое видят покупатели при оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Eupago. Обязательное поле: пустое название выводит Enter a title for the payment method.

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

Payment Method: единственный способ Eupago, который предлагается при оформлении заказа.

Multibanco: покупатель получает код организации и реф-номер для оплаты в банкомате или интернет-банке (по умолчанию). Предлагается для сумм заказа от 1 € до 999 999,99 €.

MB WAY: покупатель вводит номер телефона MB WAY при оформлении заказа и подтверждает оплату в приложении MB WAY.

Credit Card: покупатель перенаправляется на страницу карт Eupago.

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

Processing (default): заказ получает статус Payment accepted.

Completed: заказ получает статус Delivered, одним изменением статуса.

Аккаунт Eupago

Получите API-ключ вашего канала и ключ Webhook 2.0 в бэк-офисе Eupago: clientes.eupago.pt (рабочая среда) или sandbox.eupago.pt (тестовая среда). Тестовая и рабочая среды — это разные аккаунты с разными ключами.

Sandbox Mode: использует sandbox.eupago.pt и тестовые ключи. Реальные платежи не списываются. По умолчанию: включено. Выключите, чтобы принимать реальные платежи рабочими ключами. Пока режим включён, покупатели видят SANDBOX / TEST MODE под способом оплаты.

Live API Key: API-ключ вашего рабочего канала Eupago (clientes.eupago.pt).

Live Webhook Key: ключ шифрования вашего рабочего Webhook 2.0. Обязательное поле: уведомления без действительной подписи отклоняются.

Sandbox API Key: API-ключ вашего тестового канала (sandbox.eupago.pt).

Sandbox Webhook Key: ключ шифрования вашего тестового Webhook 2.0.

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

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

URL вебхука

Вебхук сообщает вашему магазину, что оплата произведена. В бэк-офисе Eupago создайте Webhook 2.0 с URL, который показан в этом разделе, методом POST и включённым шифрованием. С понятными URL он выглядит так: https://your-shop/module/wcp_eupago_gateway/webhook, возможно, с кодом языка, например /pt/. Копируйте URL точно так, как он показан в настройках. Создайте один вебхук в бэк-офисе sandbox и другой в рабочем бэк-офисе.

Скопируйте ключ каждого вебхука в поле Sandbox Webhook Key или Live Webhook Key. Вебхуки без действительной подписи отклоняются. Незашифрованный вебхук принимается, только если Eupago подписывает его, поэтому держите шифрование включённым. Уведомление должно быть подписано ключом того режима, в котором была начата оплата, поэтому уведомление из sandbox никогда не оплачивает рабочий платёж. Модуль реагирует на следующие статусы уведомлений:

PAID: оплата произведена. Заказ отмечается оплаченным после всех проверок.

CANCELED: оплата отменена. Заказ в ожидании переходит в статус Canceled.

EXPIRED: срок оплаты истёк. Заказ в ожидании переходит в статус Canceled.

ERROR: оплата не прошла. Заказ в ожидании переходит в статус Payment error.

Другие статусы не требуют действий. Устаревший GET-callback Eupago на тот же URL тоже принимается; он аутентифицируется API-ключом и всегда сообщает об оплате. Без уведомлений заказы никогда не отмечаются оплаченными: модуль не опрашивает Eupago, а возвращение покупателя не оплачивает заказ. Вебхук работает, когда магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

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

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

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

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

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

Покупатель выбирает способ оплаты (по умолчанию Eupago) на шаге оплаты и оформляет заказ. Дальнейшие действия зависят от Payment Method.

Multibanco: при оформлении заказа покупатель видит You will receive Multibanco payment details after placing the order. Модуль создаёт реф-номер Multibanco на сумму корзины. Заказ сразу создаётся в статусе Awaiting Eupago payment, как любой заказ PrestaShop, и корзина очищается. На странице «Подтверждение заказа» показываются Multibanco Payment Details: код организации, реф-номер и сумма. Те же данные добавляются в строку оплаты в письме с подтверждением заказа. Покупатель платит в банкомате или интернет-банке.

MB WAY: при оформлении заказа покупатель вводит MB WAY Phone Number, которое заполняется телефоном из адреса для выставления счёта. Португальские номера можно вводить без +351. Неверный номер выводит Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). Модуль отправляет запрос на оплату в приложение MB WAY и создаёт заказ в статусе Awaiting Eupago payment. На странице «Подтверждение заказа» покупателя просят открыть приложение MB WAY на замаскированном номере телефона и подтвердить запрос в течение 5 минут.

Credit Card: при оформлении заказа покупатель видит You will be redirected to a secure payment page to enter your card details. Покупатель переходит на страницу карт Eupago на португальском, испанском или английском языке в зависимости от языка корзины. Заказа пока нет, корзина сохраняется. Заказ создаётся только тогда, когда Eupago подтверждает оплату. Если уведомление пришло к моменту возвращения покупателя, он видит обычную страницу «Подтверждение заказа». Иначе страница Payment confirmation показывает Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. и кнопку Check again. Если оплата картой не удалась или отменена, покупатель возвращается к оформлению заказа с сообщением The card payment was not completed. You can try again or choose another payment method. или The card payment was cancelled. You can try again or choose another payment method.

Для любого способа заказ отмечается оплаченным только после того, как Eupago подтвердит оплату проверенным уведомлением. Платёжные данные показываются только пока заказ находится в статусе Awaiting Eupago payment. Если Eupago позже сообщает, что оплата отменена, истекла или не прошла, а заказ не был оплачен, на странице «Подтверждение заказа» выводится Your Eupago payment was not completed. Please contact us about this order.

Если Eupago не может начать оплату, покупатель остаётся на оформлении заказа с коротким сообщением, например The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. Заказ не создаётся, подробности записаны в журнал. Для корзины в другой валюте выводится Eupago only supports payments in EUR.

Модуль предлагает один способ Eupago на установку. Он не поддерживает возвраты из PrestaShop, сохранённые карты, подписки или предавторизацию, PayShop, Cofidis Pay, Bizum и другие способы Eupago, а также SMS-напоминания, срок действия Multibanco и опрос статуса.

Заказы

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

No order yet: начат платёж картой, и Eupago его ещё не подтвердил. Существует только корзина.

Awaiting Eupago payment: создан реф-номер Multibanco или запрос MB WAY. В примечании указаны код организации и реф-номер или замаскированный номер телефона.

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

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

Canceled: Eupago сообщил, что платёж отменён или истёк, для текущей попытки оплаты заказа в ожидании.

Payment error: Eupago сообщил об ошибке в текущей попытке оплаты заказа в ожидании.

Если Eupago сообщает о другом платеже по заказу, который уже оплачен (например, была оплачена и более ранняя реф-квитанция Multibanco), заказ не меняется. Примечание просит вас проверить дубликат платежа и вернуть его в бэк-офисе Eupago. Уведомление об оплате никогда не переоткрывает заказ, который был оплачен, а затем отменён или возвращён.

Блок платежей Eupago

На странице заказа показан блок Eupago payment со всеми попытками оплаты корзины: дата, способ, метка Sandbox для тестовых платежей, сумма, код организации и реф-номер Multibanco или замаскированный телефон MB WAY, ID транзакции Eupago и статус. Пока заказ находится в статусе Eupago payment on hold, блок выводит предупреждение Manual review. Ниже раздел Eupago notes содержит примечания модуля к заказу, сначала самые новые.

Возвраты

Возвраты из PrestaShop не поддерживаются. Верните деньги покупателю в бэк-офисе Eupago и вручную обновите заказ в PrestaShop. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Eupago.

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

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

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

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

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

Eupago не появляется при оформлении заказа: проверьте, что лицензия действует, Enable/Disable включено и задан API-ключ текущего режима (Sandbox API Key в режиме sandbox, Live API Key в рабочем режиме). Валюта корзины должна быть EUR, а в Payment > Preferences модуль должен быть разрешён для евро, страны покупателя и группы покупателя. При Multibanco сумма заказа должна быть от 1 € до 999 999,99 €.

Оплата прошла, но заказ остаётся в статусе Awaiting Eupago payment или заказ не создан: уведомление Eupago не приходит или отклоняется. В бэк-офисе Eupago того режима, который вы используете, проверьте, что Webhook 2.0 существует, что его URL точно совпадает с показанным в Webhook URL, что метод POST и шифрование включено. Проверьте, что его ключ находится в нужном поле (Sandbox Webhook Key или Live Webhook Key). Включите Debug Log и посмотрите поле Log на странице модуля. Если уведомление не приходит совсем, проверьте платёж в бэк-офисе Eupago.

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

Вебхук отвечает Webhook key not configured: ни один ключ вебхука не задан. Eupago повторит уведомление после того, как вы вставите ключ.

Вебхук отвечает Decryption failed: подпись действительна, но тело не удалось расшифровать. Проверьте настройки Webhook 2.0 в бэк-офисе Eupago.

Вебхук отвечает Environment mismatch: уведомление подписано ключом другого режима, не того, в котором начата оплата. Уведомление из sandbox никогда не оплачивает рабочий платёж, и наоборот. Проверьте, что тестовый и рабочий ключи не перепутаны.

Вебхук отвечает Order not found: уведомление относится к корзине без платежа Eupago этого магазина, например к оплате из другого магазина с тем же каналом Eupago.

Вебхук отвечает Busy or Retry: корзина в этот момент обрабатывалась другим запросом, либо заказ не удалось создать (например, модуль выключен). Eupago повторит уведомление. Причина указана в журнале.

Устаревший callback отвечает Invalid API key: API-ключ, присланный Eupago, не совпадает с Live API Key или Sandbox API Key. Тот же ответ появляется, если открыть URL вебхука в браузере; это нормально.

Покупатель видит The MB WAY payment could not be started: проверьте, что номер телефона привязан к MB WAY, и попробуйте снова.

Заказ в статусе Eupago payment on hold после оплаты: прочитайте Eupago notes в блоке Eupago payment. Сумма или валюта отличались, реф-номер был неизвестен, либо оплата пришла после отмены заказа. Проверьте платёж в бэк-офисе Eupago, затем завершите заказ или верните деньги покупателю.

Удаление

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

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