VibeFox Eupago for OpenCart — Помощь

Требования

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

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

Настройка

Все параметры находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Eupago Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Когда способ оплаты включён, страница предупреждает над настройками, если API-ключ текущего режима пуст (тогда способ оплаты скрывается при оформлении заказа), или показывает Sandbox mode: no real payments are taken., пока включён режим песочницы. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении название не должно быть пустым и не может превышать 128 символов, способ оплаты обязательно выбирается, Sort Order должен быть целым числом, Total — числом не меньше нуля, а геозона и статусы заказов должны существовать. В противном случае ошибка указывает на проблему, например Enter a title for the payment method (1 to 128 characters)., и ничего не сохраняется.

Eupago

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely via Eupago.

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

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

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

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, чтобы предлагался Eupago. Оставьте поле пустым, чтобы предлагать Eupago при любой сумме. Независимо от этого поля Eupago предлагается только при оплате в EUR, а Multibanco — только для сумм от 1 € до 999 999,99 €.

Аккаунт Eupago

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

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

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 the saved key on save под полем и нажмите Save.

URL вебхука

Вебхук сообщает вашему магазину, что платёж произведён. В бэкофисе Eupago создайте Webhook 2.0 с URL, который указан в этом разделе, методом POST и включённым шифрованием. В OpenCart 3 URL выглядит так: https://your-store/index.php?route=extension/payment/wcp_eupago_gateway/webhook, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_eupago_gateway/payment/wcp_eupago_gateway.webhook. Он формируется из адреса витрины вашей установки OpenCart. Копируйте URL точно так, как он показан в настройках. Создайте один вебхук в бэкофисе песочницы и другой — в боевом бэкофисе.

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

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

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Для Multibanco и MB WAY заказ получает статус ожидания, как только Eupago выдал референс или запрос MB WAY. При оплате картой заказ получает статус только по уведомлению от Eupago. Заказ отмечается оплаченным, только когда приходит проверенное уведомление и его режим, референс, сумма и валюта совпадают с заказом. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

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

Awaiting payment status: референс Multibanco или запрос MB WAY выданы, и покупатель ещё должен оплатить. Реквизиты Multibanco отправляются с этим статусом (в письме о заказе и в истории заказов покупателя). По умолчанию: Ожидает оплаты.

Manual review status: Eupago сообщил о платеже, который не соответствует заказу (сумма, валюта, референс), о платеже после отмены заказа или о платеже по заказу, корзина которого уже была оплачена. Примечание объясняет причину. По умолчанию: Ожидает оплаты, потому что в OpenCart нет статуса «На удержании». Вы можете создать собственный статус в разделе System > Localisation > Order Statuses и выбрать его здесь.

Cancelled status: Eupago сообщил, что текущий платёж заказа в ожидании отменён или истёк. По умолчанию: Отменён.

Failed status: Eupago сообщил об ошибке текущего платежа заказа в ожидании (ERROR). По умолчанию: Не удался.

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

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

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

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

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

Export: Download JSON сохраняет настройки в файл JSON. API-ключи и ключи вебхука не экспортируются.

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Eupago). OpenCart создаёт заказ на шаге Confirm Order, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Что происходит, когда покупатель нажимает Confirm Order, зависит от Payment Method.

Multibanco: покупатель видит You will receive Multibanco payment details after placing the order. Расширение создаёт референс Multibanco на сумму заказа в евро, и заказ получает статус Awaiting payment status. Письмо о заказе и история заказов покупателя получают комментарий Multibanco Payment Details с номером организации, референсом и суммой. Страница успешного оформления заказа показывает те же данные. Покупатель платит в банкомате или в интернет-банке.

MB WAY: покупатель вводит MB WAY Phone Number, которое заполняется телефоном из заказа. Португальские номера можно вводить без +351. В OpenCart 4 телефон по умолчанию не запрашивается, поэтому поле обычно пустое, и покупатель вводит номер сам. Неверный номер выводит Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). Расширение отправляет запрос на оплату в приложение MB WAY, и заказ получает Awaiting payment status. Страница успеха просит покупателя открыть приложение MB WAY на замаскированном номере телефона и подтвердить запрос в течение 5 минут. Если Eupago отклоняет запрос, покупатель остаётся на шаге Confirm Order с сообщением The MB WAY payment could not be started. Check that the phone number is associated with MB WAY and try again.

Credit Card: покупатель видит You will be redirected to a secure payment page to enter your card details. Покупатель перенаправляется на страницу оплаты картой Eupago, на португальском, испанском или английском в зависимости от языка магазина. Заказ остаётся без статуса, корзина сохраняется. Если уведомление пришло к моменту возврата покупателя, он видит страницу успешного оформления заказа OpenCart. Иначе страница Payment confirmation показывает Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. с кнопками Check again и Back to checkout. Если оплата картой не прошла или прервана, покупатель возвращается к оформлению заказа с сообщением 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. На OpenCart 4 эти сообщения выводятся над страницей оформления заказа.

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

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order. OpenCart 4 обновляет заказ оформления, поэтому после отменённого или неуспешного платежа картой покупатель оплачивает тот же заказ новым платежом Eupago. Если более ранний заказ из той же корзины уже оплачен через Eupago, покупатель переходит на страницу успеха, и новый платёж не создаётся.

OpenCart 4 сохраняет заказ в оформлении заказа до показа страницы успеха. Если за это время этот заказ был закрыт без оплаты (например, истёк срок референса Multibanco, запрос MB WAY был отклонён или вы отменили заказ), покупатель возвращается к оформлению заказа с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., и следующий Confirm Order оплачивает новый заказ корзины. Если этот заказ уже оплачен или ожидает оплаты, но корзина с тех пор изменилась, в том числе новым количеством, сообщение: Your previous order is already paid or awaiting its payment. Please confirm the order again: the cart will be paid with a new order. Оплаченный заказ никогда не показывается как оплаченный для другой корзины.

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

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

Заказы

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

No status (missing order): покупатель был перенаправлен на оплату картой, Eupago ещё не подтвердил платёж или он не прошёл. В разделе Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Awaiting payment status (default Pending): создан референс Multibanco или запрос MB WAY. Примечание показывает номер организации и референс либо замаскированный номер телефона.

Order Status After Payment (default Processing): платёж подтверждён. Примечание показывает способ оплаты, идентификатор транзакции Eupago и референс.

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

Cancelled status (default Canceled): Eupago сообщил, что текущий платёж заказа в ожидании отменён или истёк.

Failed status (default Failed): Eupago сообщил об ошибке текущей попытки оплаты заказа в ожидании.

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

Вкладка VibeFox Eupago Gateway

В разделе Sales > Orders откройте заказ, оплаченный через Eupago. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Eupago Gateway перечисляет каждую попытку оплаты заказа: Date, Method (с меткой Sandbox для платежей в песочнице), Amount, Entity / reference / phone, Eupago transaction ID и Status. Для заказа на ручной проверке вкладка показывает предупреждение. Ниже Eupago notes перечисляет примечания расширения к заказу. Вкладка доступна только для чтения и показывается пользователям, у которых есть доступ к расширению.

Возвраты

Возвраты в этом расширении недоступны. Верните деньги покупателю в бэкофисе Eupago и вручную обновите заказ в OpenCart. Возвраты товаров в разделе Sales > Returns не возвращают деньги через Eupago.

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

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

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

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

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

Eupago does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включён и задан API-ключ текущего режима (Sandbox API Key в режиме песочницы, Live API Key в боевом режиме). Покупатель должен платить в EUR, а при Multibanco сумма заказа должна быть от 1 € до 999 999,99 €. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что заказ достигает Total, заданного в настройках.

The payment went through, but the order stays in the awaiting status or without a status: уведомление Eupago не приходит или отклоняется. В бэкофисе Eupago того режима, который вы используете, проверьте, что Webhook 2.0 существует, что его URL точно совпадает с указанным в Webhook URL, что метод — POST и шифрование включено. Проверьте, что его ключ введён в нужное поле (Sandbox Webhook Key или Live Webhook Key). Включите Debug Log и посмотрите поле Log на странице расширения. Если уведомление так и не приходит, проверьте платёж в бэкофисе Eupago.

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

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

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

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

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

Webhook answers Busy or Retry: заказ в тот же момент обрабатывался другим запросом, или обработка не удалась. Eupago повторит уведомление. Причина указана в журнале.

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

The customer sees This payment method is temporarily unavailable: не задан API-ключ текущего режима. Введите его в настройках.

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

Order is in the manual review status after payment: прочитайте Eupago notes на вкладке VibeFox Eupago Gateway. Сумма или валюта отличались, референс был неизвестен, платёж пришёл после отмены заказа или корзина уже была оплачена другим заказом. Проверьте платёж в бэкофисе Eupago, затем завершите заказ или верните деньги покупателю.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Eupago Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения также удаляется (на OpenCart 4 — его события и его действие запуска, которое пропускает вебхук и возврат покупателя в режиме обслуживания). Если Delete Data on Uninstall включено, удаляются остальные настройки шлюза (название, описание, способ оплаты, режим песочницы, ключи, журнал отладки) и журнал. Если опция выключена, они сохраняются для повторной установки. Платёжные записи Eupago по заказам всегда сохраняются, поэтому поздние уведомления по старым заказам продолжают работать после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

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

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