VibeFox PayPlug for PrestaShop — Допомога

Вимоги

PrestaShop: від 8.0 до 9.x.

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

Валюта та суми: євро (EUR), від 0,99 до 20 000,00 за платіж, стандартні значення PayPlug. За іншої валюти кошика або поза цими межами спосіб оплати приховується.

Обліковий запис PayPlug: потрібні секретні ключі вашого облікового запису PayPlug: тестовий ключ (sk_test_...) та/або робочий ключ (sk_live_...). Інші ключі не потрібні, і в PayPlug нічого налаштовувати для сповіщень не треба. Ваш магазин має бути доступним з інтернету, щоб отримувати сповіщення; інакше замовлення створюються, коли покупець повертається з PayPlug.

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

Встановлення

1. У панелі адміністратора перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

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

3. Вставте ліцензійний ключ VibeFox у License key у блоці ліцензії вгорі сторінки Configure і натисніть Activate (див. Ліцензійний ключ).

4. Вставте секретні ключі з порталу PayPlug (див. Налаштування).

5. Увімкніть Enable/Disable і натисніть Save. Перевірте оплату з увімкненим Test Mode, а потім вимкніть його, щоб приймати справжні платежі.

Під час встановлення модуль створює статус замовлення PayPlug payment on hold. PrestaShop вмикає новий платіжний модуль для всіх валют, країн і груп клієнтів. Їх можна обмежити в Payment > Preferences.

Налаштування

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox PayPlug Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, коли спосіб оплати увімкнено, але секретний ключ поточного режиму порожній, а також коли валюта магазину за замовчуванням не EUR. В обох випадках спосіб оплати приховується під час оформлення замовлення.

Оформлення замовлення

Enable/Disable: Enable PayPlug Gateway вмикає або вимикає спосіб оплати. За замовчуванням: off.

Title: назва способу оплати, яку бачить покупець під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: PayPlug. Обов'язкове поле.

Description: текст під способом оплати під час оформлення замовлення. За замовчуванням: Pay securely by card via PayPlug.

Ключі API

Секретні ключі знаходяться в порталі PayPlug у розділі Developers > API keys. У цьому розділі є посилання на портал.

Test Mode: використовує тестовий секретний ключ для нових платежів. Справжні платежі не проводяться. Платежі, зроблені в іншому режимі, для перевірки статусу та повернень і далі використовують ключ свого режиму. За замовчуванням: on. Поки режим увімкнено, покупці бачать під способом оплати напис Test mode: no real payment will be made.

Test Secret Key: ваш тестовий секретний ключ PayPlug. Він починається з sk_test_.

Live Secret Key: ваш робочий секретний ключ PayPlug. Він починається з sk_live_.

Ключ з неправильним префіксом не зберігається. Сторінка показує, наприклад, Test Secret Key must start with "sk_test_". The previous value was kept. Збережені ключі більше не відображаються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved keys: відмітьте ключ і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Notification URL: адреса, яку модуль передає в PayPlug з кожним платежем. З увімкненими зрозумілими URL вона виглядає так: https://your-shop/module/wcp_payplug_gateway/webhook. У порталі PayPlug нічого вводити не потрібно. URL має бути доступним з інтернету; інакше замовлення створюються, коли покупець повертається з PayPlug.

Замовлення

Order Status After Payment: статус замовлення, який встановлюється після успішної оплати. Статус встановлюється одразу, без другої зміни статусу.

Додатково

Logging: записує виклики API і сповіщення у файл logs/ppg_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки та попередження записуються завжди. Секретні ключі, дані картки та дані покупця ніколи не записуються. За замовчуванням: off.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб очистити його.

Delete Data on Uninstall: якщо увімкнено, налаштування модуля та його журнал видаляються під час видалення модуля. Ідентифікатори платежів PayPlug, збережені в замовленнях, і статус замовлення PayPlug payment on hold зберігаються. За замовчуванням: off.

Оформлення замовлення

На етапі оплати покупець обирає спосіб оплати (за замовчуванням PayPlug, з логотипом PayPlug). У тестовому режимі опція показує Test mode: no real payment will be made. Після підтвердження модуль створює платіж PayPlug на суму кошика в центах і надсилає покупця на сторінку оплати PayPlug. Адреси для виставлення рахунку та доставки, електронна пошта і мова кошика передаються в PayPlug. Там покупець оплачує карткою. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після того, як PayPlug його підтвердить: модуль зчитує платіж з API PayPlug, коли надходить сповіщення і коли покупець повертається. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з повідомленням Your payment with PayPlug has been received. Якщо замовлення на утриманні, сторінка повідомляє We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Якщо замовлення має статус Payment error або скасоване без оплати, сторінка повідомляє Your PayPlug payment was not completed. Please contact us about this order. Якщо під час повернення покупця не вдалося запитати PayPlug, сторінка Payment confirmation показує той самий текст «we are confirming» і кнопку Check again; сповіщення створить замовлення, щойно воно надійде.

Якщо покупець скасовує оплату на сторінці PayPlug, сторінка оплати закривається в PayPlug, тож її не можна помилково оплатити пізніше. Покупець повертається до оформлення замовлення з повідомленням: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. або, якщо платіж залишився відкритим, Your PayPlug payment was not completed. You can try again or choose another payment method. Кошик зберігається.

Коли покупець оплачує той самий кошик повторно, модуль спочатку перевіряє попередню спробу. Якщо її оплатили тим часом, замовлення створюється без нового платежу. Якщо вона ще відкрита на ту саму суму, використовується та сама сторінка оплати. Інакше стара сторінка закривається в PayPlug і створюється новий платіж.

Якщо PayPlug не може розпочати оплату, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад PayPlug could not accept your billing details (postcode). Please check them and try again. або The payment provider could not be reached. Please try again in a moment. Технічна причина записується в журнал.

Сповіщення працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

Платежі списуються одразу. Модуль не підтримує розстрочку Oney, збережені картки для оплати в один клік, вбудовану форму оплати, підписки та відкладене списання.

Замовлення та повернення коштів

Статуси замовлення

No order yet: покупця надіслано до PayPlug, і він не оплатив, або PayPlug ще не підтвердив платіж. Існує лише кошик.

Payment accepted or Delivered: платіж підтверджено. Статус відповідає Order Status After Payment. Платіж записується з ідентифікатором платежу PayPlug (pay_...) як ID транзакції, а примітка показує платіж PayPlug і його режим.

PayPlug payment on hold: оплачена сума або валюта відрізняється від кошика (примітка amount/currency mismatch, наприклад кошик змінили після початку оплати); або тестовий платіж був зроблений, поки магазин працював у робочому режимі, тож грошей не отримано і платіж не записується; або платіж надійшов для скасованого замовлення; або платіж авторизовано, але не списано (спишіть його в порталі PayPlug; замовлення позначиться оплаченим, коли PayPlug повідомить про оплату). Примітка пояснює, що перевірити.

Payment error: авторизований платіж замовлення на утриманні не пройшов або був скасований.

Refunded: платіж повністю повернено через модуль.

Якщо друга спроба оплати вже оплаченого кошика теж пройшла, замовлення не змінюється. Примітка просить повернути дубльований платіж у порталі PayPlug. Оплачене, скасоване або повернене замовлення ніколи не відкривається знову через пізніше сповіщення.

Блок платежу PayPlug

Сторінка замовлення показує блок PayPlug payment з ідентифікатором платежу PayPlug, статусом платежу, сплаченою і поверненою сумою, позначкою Test mode для тестових платежів, історією повернень і PayPlug notes замовлення.

Повернення коштів

У блоці PayPlug payment введіть суму (підставляється сума, що ще не повернута), за бажанням причину, і натисніть Refund via PayPlug. Підтвердіть запитання Refund this amount through PayPlug? This cannot be undone. Підтримуються повні та часткові повернення. Вам потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Повернення здійснюються в межах суми, яку PayPlug фактично списав, тож після розбіжності суми можна повернути те, що сплатив покупець, а не суму замовлення. Повернення спрямовується на платіж, яким замовлення фактично оплачено, із секретним ключем режиму (тестового або робочого), в якому його було здійснено, тож цей ключ має бути налаштований. Якщо PayPlug відхиляє повернення, блок показує помилку і повернення не записується. Успішне повернення додається до історії повернень і приміток з ідентифікатором повернення PayPlug та причиною. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює. Повернення доступні, коли PayPlug повідомив, що платіж оплачено.

Модуль не створює кредитні ноти. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через PayPlug.

Повернення, зроблені в порталі PayPlug, надходять через сповіщення і додаються до приміток один раз. Вони не враховуються в блоці й не змінюють статус замовлення або кредитні ноти. За потреби внесіть їх вручну.

Ліцензійний ключ

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

Без активного ключа PayPlug не показується покупцям під час оформлення замовлення. Якщо оплату все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина магазину не знає, що ви увійшли в панель адміністратора, тож спосіб оплати приховується і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете протестувати його під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, які вже розпочато, як і раніше підтверджуються, а повернення працюють.

Коли термін ліцензії спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус перевіряється автоматично, поки ви працюєте в панелі адміністратора: раз на день протягом перших 14 днів після введення ключа, далі раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

PayPlug не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, у поточному режимі є секретний ключ (Test Secret Key у тестовому режимі, Live Secret Key у робочому режимі), валюта кошика — EUR, а сума кошика становить від 0,99 до 20 000,00 EUR. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця. Розробники можуть змінити валюти та ліміти за допомогою хуків actionWcpPayplugSupportedCurrencies та actionWcpPayplugAmountLimits (значення в центах).

Оплата пройшла, але замовлення не створено: сповіщення не дійшло до вашого магазину, і покупець не повернувся. Перевірте, що ваш магазин доступний з інтернету за Notification URL, вказаним у налаштуваннях, наприклад що його не блокують брандмауер або захист паролем. Увімкніть Logging і перегляньте поле Log на предмет відхилених сповіщень.

Сповіщення відповідає Verification failed.: платіж не вдалося зчитати з API PayPlug, наприклад тому що PayPlug не відповів або не задано секретний ключ режиму платежу. Замовлення не змінюється, і PayPlug надішле сповіщення повторно.

Сповіщення відповідає Temporarily unavailable.: кошик у цей самий момент оновлював інший запит, наприклад повернення покупця, або замовлення не вдалося створити (наприклад, модуль вимкнено). PayPlug надішле сповіщення повторно. Журнал показує причину.

Сповіщення відповідає Unknown payment. або Payment does not belong to the order.: платіж створено не цим магазином або не для цього кошика, наприклад платіж іншого магазину на тому самому обліковому записі PayPlug. Його ігнорують.

URL сповіщення в браузері показує Method not allowed.: це нормально. URL приймає лише запити від PayPlug.

Покупець бачить помилку під час вибору PayPlug: увімкніть Logging і перегляньте поле Log. Неправильний ключ дає This payment method is temporarily unavailable. Please choose another payment method.; інші повідомлення називають поле оплати, яке відхилив PayPlug.

Замовлення має статус PayPlug payment on hold після оплати: прочитайте примітки в блоці PayPlug payment (див. Статуси замовлення), потім обробіть замовлення або поверніть платіж.

Повернення не проходить з повідомленням про режим: платіж було зроблено в тестовому або робочому режимі, а секретний ключ цього режиму не налаштовано. Введіть його і повторіть спробу.

Повернення не проходить з повідомленням Unexpected response from PayPlug.: PayPlug відповів без коректного повернення. Нічого не записано. Перевірте повернення в порталі PayPlug, перш ніж повторювати спробу.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox PayPlug Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete Data on Uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для подальшого повторного встановлення. Записи про платежі та повернення PayPlug і статус замовлення PayPlug payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату та ідентифікатори транзакцій.

PayPlug є торговельною маркою її власника. Цей модуль не пов'язаний з PayPlug і не схвалений PayPlug.