VibeFox Eupago for WooCommerce — Помощь

Требования

WordPress: 6.0 или новее.

WooCommerce: 7.0 или новее, установлен и активен.

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

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

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

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_eupago_gateway в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Eupago > Manage или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

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

6. Выберите Payment Method, включите Enable/Disable, сделайте тестовый заказ в режиме sandbox, затем снимите галочку с Sandbox Mode.

Настройка

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

Общие

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

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

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

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

Order Status After Payment: статус заказа, который устанавливается после подтверждения оплаты: Processing (по умолчанию) или Completed. Статус устанавливается сразу, с одним изменением статуса и одним письмом.

Аккаунт Eupago

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

Sandbox Mode: Enable sandbox/test mode использует sandbox.eupago.pt и ключи sandbox. Реальные платежи не принимаются. По умолчанию: on. Снимите галочку, чтобы принимать реальные платежи рабочими ключами.

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.

URL вебхука

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

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

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

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

Debug Log: Enable logging записывает вызовы API и уведомления в WooCommerce > Status > Logs, источник wcp_eupago_gateway. Ключи, письма и полные номера телефонов не записываются. Ошибки записываются всегда. По умолчанию: off.

Delete Data on Uninstall: Delete all plugin data when uninstalling. Если отмечено, настройки шлюза и журналы удаляются при удалении плагина. Заказы и их платёжные данные сохраняются. По умолчанию: off.

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

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

Multibanco: при оформлении заказа покупатель видит You will receive Multibanco payment details after placing the order. Плагин создаёт реф-номер Multibanco на сумму заказа. Заказ переходит в статус «На удержании», остатки уменьшаются, корзина очищается. Страница «Заказ получен» показывает 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. Заказ переходит в статус «На удержании», остатки уменьшаются, корзина очищается. На странице «Заказ получен» покупателю предлагается открыть приложение MB WAY и подтвердить запрос в течение 5 минут.

Credit Card: при оформлении заказа покупатель видит You will be redirected to a secure payment page to enter your card details. Покупатель отправляется на страницу оплаты картой Eupago на португальском, испанском или английском языке в зависимости от языка сайта. Заказ остаётся в статусе «Ожидает оплаты», корзина сохраняется. После оплаты покупатель возвращается на страницу «Заказ получен», где показано Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed., до прихода уведомления. Если оплата картой не прошла или прервана, покупатель попадает на страницу Pay for order с сообщением 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 проверенным уведомлением. Покупатель может снова оплатить неоплаченный заказ со страницы Pay for 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. Заказ не меняется, подробности есть в журнале.

Способ оплаты работает на классическом оформлении заказа, в блоке оформления заказа и на странице Pay for order. Совместим с WooCommerce High-Performance Order Storage (HPOS). Тексты для покупателя переведены на португальский язык.

Плагин предлагает один способ оплаты Eupago на установку. Нет возвратов из WooCommerce, сохранённых карт, подписок или предавторизации, нет PayShop, Cofidis Pay, Bizum и других способов Eupago, нет SMS-напоминаний, срока действия Multibanco и опроса статуса.

Заказы

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

Pending payment: начат платёж картой, но Eupago его ещё не подтвердил.

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

Processing or Completed: оплата подтверждена. Статус соответствует Order Status After Payment. В примечании к заказу показаны способ оплаты, ID транзакции Eupago и реф-номер. ID транзакции заказа — это ID транзакции Eupago.

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

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

Failed: Eupago сообщил об ошибке для текущей попытки оплаты неоплаченного заказа.

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

Возвраты: возвраты из WooCommerce не поддерживаются. Верните деньги покупателю в бэк-офисе Eupago и зафиксируйте возврат в WooCommerce кнопкой Refund manually.

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > Eupago. Вставьте ключ в поле License key и нажмите Activate. Блок показывает статус, например дату, до которой лицензия активна, и ваш домен. Используйте Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает слот домена. Освободите слот в вашем аккаунте vibefox.net.

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

Когда лицензия истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется снова автоматически в фоновом режиме.

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

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

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

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

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

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

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

Устаревший callback отвечает Invalid API key: API-ключ, который прислала Eupago, не совпадает с Live API Key или Sandbox API Key.

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

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в аккаунте vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Для разработчиков документация плагина описывает фильтры eupago_p_icon (иконка при оформлении заказа) и eupago_p_card_language (язык страницы оплаты картой Eupago: PT, EN или ES).

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза и журналы удаляются, только если была включена опция Delete Data on Uninstall. Иначе они сохраняются для повторной установки. Заказы и их реф-номера Eupago сохраняются всегда. Существующие заказы сохраняют примечания об оплате и ID транзакций.

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