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. Sandbox і live — окремі облікові записи з окремими ключами.

Ліцензійний ключ 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: покупець отримує код організації (entity) і референс для оплати в банкоматі або в інтернет-банкінгу (за замовчуванням). Пропонується для сум замовлення від 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 (live) або sandbox.eupago.pt (sandbox). Sandbox і live — окремі облікові записи з окремими ключами.

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 для модуля. Тексти блоку відповідають мові бекофісу (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад 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.