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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіша (перевірено на 4.1.0.3).

PHP: 8.0 або новіша.

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

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

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

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

Завантажувальний файл — це один zip-архів із пакетами для обох версій OpenCart. Розпакуйте його на комп'ютері. Він містить README.txt, пакет для OpenCart 3 wcp_payplug_gateway-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_payplug_gateway.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ один і той самий для обох версій.

OpenCart 3

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

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox PayPlug Gateway і натисніть Install (зелена кнопка +). Вашому адміністратору потрібне право змінювати список платіжних розширень.

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

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

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

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_payplug_gateway.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з імені файлу, і перейменований пакет не працює.

2. Пакет з'явиться у списку встановлених розширень на тій самій сторінці. Натисніть біля нього Install (зелена кнопка +).

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox PayPlug Gateway, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і секретні ключі PayPlug так само, як у кроках 3–5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише URL сповіщень (див. Сповіщення).

Нове встановлення починається з вимкненим способом оплати та увімкненим тестовим режимом.

Конфігурація

Усі налаштування розміщені на сторінці розширення: Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, коли спосіб оплати увімкнено, але секретний ключ поточного режиму порожній, а також коли валюта магазину за замовчуванням не EUR. В обох випадках спосіб оплати приховується під час оформлення замовлення (за іншої валюти за замовчуванням — поки вибрано цю валюту). Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження Title має містити від 1 до 128 символів, Sort Order має бути цілим числом, Total має бути числом не менше 0, а статуси замовлень мають існувати; інакше нічого не зберігається, і сторінка показує помилки. Секретний ключ у неправильному форматі не зберігається, а інші налаштування зберігаються: сторінка показує Settings saved, except the secret key shown in red. і, наприклад, Test Secret Key must start with "sk_test_". The previous value was kept.

Checkout

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

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

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay securely by card via PayPlug.

Sort Order: позиція PayPlug серед способів оплати під час оформлення замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати PayPlug лише для платіжних адрес у вибраній географічній зоні. За замовчуванням: All zones. Географічні зони налаштовуються в System > Localisation > Geo Zones.

Total: сума замовлення у валюті магазину за замовчуванням, яку має досягти замовлення, щоб пропонувався PayPlug. Залиште поле порожнім, щоб пропонувати PayPlug за будь-якої суми. Сам PayPlug приймає від 0,99 до 20 000,00 EUR за платіж.

API-ключі

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

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

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

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

Збережені ключі більше не показуються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений ключ, позначте Clear the saved key on save під полем і натисніть Save.

Сповіщення

Notification URL: адреса, яку розширення надсилає PayPlug з кожним платежем. У OpenCart 3 вона має вигляд https://your-store/index.php?route=extension/payment/wcp_payplug_gateway/webhook, в OpenCart 4 — https://your-store/index.php?route=extension/wcp_payplug_gateway/payment/wcp_payplug_gateway.webhook. Вона формується з адреси вітрини вашої інсталяції OpenCart. У порталі PayPlug нічого вводити не потрібно. Кожне сповіщення перевіряється повторним зчитуванням платежу через API PayPlug, тож платежі підтверджуються, навіть коли покупець не повертається до магазину. URL має бути доступним з інтернету; інакше замовлення підтверджуються лише тоді, коли покупець повертається з PayPlug.

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Замовлення отримує статус лише після того, як PayPlug повідомить про платіж, — сповіщенням або поверненням покупця; платіж завжди повторно зчитується з PayPlug. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

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

PayPlug Payment On Hold Status: платіж потребує вашої перевірки (див. Статуси замовлень). За замовчуванням: Pending, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

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

Refunded Status: встановлюється після повного повернення платежу зі сторінки замовлення. За замовчуванням: Refunded.

Додатково

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

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

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

Імпорт / Експорт

Export: Download JSON зберігає налаштування у файл JSON. Секретні ключі не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені секретні ключі залишаються.

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням PayPlug). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to the secure PayPlug payment page to pay by card.; у тестовому режимі також Test mode: no real payment will be made. OpenCart створює замовлення на цьому кроці, ще без статусу. В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення. Коли покупець натискає Confirm Order, розширення створює платіж PayPlug на суму замовлення в копійках і надсилає покупця на сторінку оплати PayPlug. Адреси платника та доставки, електронна пошта й мова замовлення передаються в PayPlug. Там покупець сплачує карткою.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження PayPlug: розширення зчитує платіж через API PayPlug, коли надходить сповіщення і коли покупець повертається. Потім замовлення отримує свій статус звичайним для OpenCart способом, із звичайними листами про замовлення та оновленням залишків, а покупець бачить сторінку успішного оформлення замовлення OpenCart з повідомленням 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. Якщо замовлення має статус помилки оплати, сторінка каже Your PayPlug payment was not completed. Please contact us about this order. Якщо під час повернення покупця запитати PayPlug не вдалося, сторінка Payment confirmation показує той самий текст «підтверджуємо» та кнопку 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. Кошик зберігається. В OpenCart 4 ці повідомлення показуються над сторінкою оформлення замовлення.

OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order, а OpenCart 4 оновлює замовлення оформлення (нова спроба — це новий платіж PayPlug для того самого замовлення), тож розширення спершу перевіряє попередні спроби для того самого кошика. Якщо одну з них тим часом сплатили, використовується цей платіж без створення нового, і покупець переходить на сторінку успіху. Якщо спроба цього замовлення ще відкрита на ту саму суму, використовується та сама сторінка оплати. Інакше стару сторінку закривають у PayPlug і створюють новий платіж. Пізній платіж за закритою сторінкою все одно фіксується. Зміна кошика, зокрема нової кількості, вважається новим кошиком, якому потрібен власний платіж.

В OpenCart 4 замовлення залишається в оформленні, доки не буде показано сторінку успіху. Якщо це замовлення тим часом закрили без оплати (наприклад, ви його скасували або його авторизований платіж не пройшов), покупця повертають до оформлення з повідомленням Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order. Наступна Confirm Order оплачує нове замовлення. Якщо це замовлення вже було оплачено для попереднього кошика, а кошик відтоді змінився, покупця повертають до оформлення, і наступна Confirm Order оплачує нове замовлення поточного кошика. Закрите замовлення ніколи не показується як оплачене.

Якщо PayPlug не може розпочати платіж, покупець залишається на кроці Confirm Order з коротким повідомленням, наприклад 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. Технічна причина записується в журнал.

Сповіщення працює також тоді, коли магазин у режимі обслуговування, тому що OpenCart пропускає запити платіжних розширень (в OpenCart 4 розширення для цього додає власну стартову дію, яка також пропускає повернення покупця з PayPlug).

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

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

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

Без статусу (відсутнє замовлення): покупця перенаправили до PayPlug, і він не сплатив, або PayPlug ще не підтвердив платіж. У Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders. Якщо платіж не пройшов, спробу закривають, і покупець може сплатити знову.

Order Status After Payment (за замовчуванням Processing): платіж підтверджено. Примітка показує платіж PayPlug і його режим.

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

Payment Error Status (за замовчуванням Failed): авторизований платіж замовлення на утриманні не пройшов або був скасований. OpenCart повідомляє покупця про цю зміну.

Refunded Status (за замовчуванням Refunded): платіж повністю повернено через розширення.

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

Примітки — це записи в History замовлення, які покупець не бачить.

Вкладка VibeFox PayPlug Gateway

У Sales > Orders відкрийте замовлення, оплачене через PayPlug. Внизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox PayPlug Gateway показує PayPlug payment ID з позначкою Test mode для тестових платежів, Status платежу, суми Paid / refunded, форму повернення, історію повернень (з режимом кожного повернення) та PayPlug notes замовлення. Вкладка показується користувачам, які мають доступ до розширення.

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

На вкладці VibeFox PayPlug Gateway введіть Amount (сума, яку ще не повернуто, уже підставлена), за бажанням Reason (optional), і натисніть Refund via PayPlug. Підтвердьте запитання Refund this amount through PayPlug? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право змінювати розширення (налаштовується в System > Users > User Groups). Повернення можливе лише до суми, яку PayPlug фактично списав, тож після розбіжності суми можна повернути те, що сплатив покупець, а не суму замовлення. Повернення проводиться за платежем, яким фактично оплачено замовлення, з секретним ключем того режиму (тестового чи робочого), у якому було здійснено платіж, тож цей ключ має бути налаштований. Якщо PayPlug не приймає повернення, вкладка показує помилку, і жодне повернення не фіксується. Успішне повернення додається до історії повернень та приміток із ідентифікатором повернення PayPlug і причиною. Повне повернення встановлює замовленню Refunded Status без сповіщення покупця і без повернення товарів на склад, як і ручна зміна статусу. Часткове повернення статус не змінює. Повернення доступні, щойно PayPlug повідомив, що платіж оплачено.

Повернення товарів у Sales > Returns не повертають гроші через PayPlug.

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

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

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

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

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

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

PayPlug не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, для поточного режиму задано секретний ключ (Test Secret Key у тестовому режимі, Live Secret Key у робочому), валюта оформлення — EUR, а сума замовлення становить від 0,99 до 20 000,00 EUR. Також перевірте, що платіжна адреса входить до вибраної Geo Zone і що замовлення досягає Total, заданого в налаштуваннях. Розробники можуть змінити валюти та ліміти через події OpenCart ppg_supported_currencies і ppg_amount_limits (значення в копійках), а запит на оплату — через ppg_payment_data.

Платіж пройшов, але замовлення залишається без статусу: сповіщення не дійшло до вашого магазину, а покупець не повернувся. Перевірте, що магазин доступний з інтернету за 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.

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

Покупець повертається і бачить Payment verification failed.: посилання для повернення не відповідає жодній спробі оплати замовлення, наприклад його відкрили в іншому браузері. Перевірте платіж у порталі PayPlug; сповіщення все одно встановить статус замовлення.

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

На вкладці немає форми повернення: вкладка пояснює причину: платіж ще не оплачено, його повністю повернено, ваша група користувачів не має права змінювати розширення, або секретний ключ режиму платежу не налаштовано.

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

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox PayPlug Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total та статуси замовлень у розділі Orders, які під час повторного встановлення повертаються до значень за замовчуванням. Подія OpenCart розширення також видаляється (в OpenCart 4 також його події та стартова дія, які пропускають сповіщення й повернення покупця в режимі обслуговування). Якщо Delete Data on Uninstall увімкнено, видаляються інші налаштування (назва, опис, тестовий режим, секретні ключі, логування) та журнал. Якщо вимкнено, вони зберігаються для повторного встановлення. Записи про платежі та повернення PayPlug завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

В OpenCart 4, щоб видалити також файли розширення, після деінсталяції перейдіть до Extensions > Installer, натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox PayPlug Gateway у списку встановлених розширень, а потім Delete (червона кнопка «кошик»), щоб видалити завантажений пакет.

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