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

Вимоги

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

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

Обліковий запис EveryPay: вам потрібні ім'я користувача API, секрет API та назва рахунку обробки (processing account) вашого інтернет-магазину. Вони відображаються в EveryPay Merchant Portal, у налаштуваннях інтернет-магазину. Демо-портал (тестовий режим) і робочий портал мають окремі облікові дані. Способи оплати, якими може користуватися покупець (картки, Apple Pay, Google Pay, банківські посилання), — це ті, що увімкнені для вашого облікового запису EveryPay.

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

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

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

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

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

OpenCart 3

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

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

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

4. Введіть тестове ім'я користувача API, тестовий секрет API та назву рахунку обробки з демо-порталу. Скопіюйте Callback notification URL в Merchant Portal (див. Налаштування).

5. Увімкніть Enable/Disable і натисніть Save. Оформіть тестове замовлення в тестовому режимі, потім введіть робочі облікові дані та вимкніть Test Mode.

OpenCart 4

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

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

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

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

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

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

Усі налаштування містяться на сторінці розширення: Extensions > Extensions > Payments > VibeFox EveryPay Payment > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка показує Test mode is on: payments go to the EveryPay demo environment, no real money is charged., поки увімкнено тестовий режим. Вона попереджає, якщо спосіб оплати увімкнено, але для поточного режиму не вказано ім'я користувача API, секрет API або рахунок обробки (тоді спосіб оплати приховано на оформленні замовлення), а також якщо валюта рахунку обробки відрізняється від валюти магазину за замовчуванням. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження Title має містити не більше 128 символів, Sort Order — ціле число, Total — число не менше нуля, а вибрані географічна зона та статуси замовлень мають існувати. Інакше помилка вказує на поле, і нічого не зберігається. Пробіли та розриви рядків у іменах користувачів, секретах і назві рахунку видаляються.

EveryPay

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

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

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay securely by card or bank link on the EveryPay payment page.

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

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

Total: сума кошика в валюті магазину за замовчуванням, яку має досягти замовлення, щоб пропонувався EveryPay. Залиште поле порожнім, щоб пропонувати EveryPay за будь-якої суми.

Обліковий запис EveryPay

Ім'я користувача API, секрет API та назва рахунку обробки відображаються в EveryPay Merchant Portal (налаштування інтернет-магазину): демо-портал для тестового режиму та робочий портал для реальних платежів (розділ містить посилання на обидва). Тестове та робоче середовища мають окремі облікові дані.

Test Mode: платежі надсилаються в демо-середовище EveryPay з тестовими обліковими даними; реальні кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі з робочими обліковими даними. Поки режим увімкнено, покупець бачить TEST MODE: EveryPay demo environment, no real money is charged. на кроці Confirm Order.

Test API Username: ім'я користувача API демо-середовища.

Test API Secret: секрет API демо-середовища.

Live API Username: ім'я користувача API робочого середовища.

Live API Secret: секрет API робочого середовища.

Processing Account Name: ваш рахунок обробки EveryPay, наприклад EUR3D1. Рахунок визначає валюту списання: спосіб оплати пропонується лише для замовлень у цій валюті.

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

Сповіщення про платежі (callback)

Callback повідомляє вашому магазину, що платіж завершено, тож замовлення підтверджуються, навіть якщо покупець закрив браузер. Скопіюйте URL, який показано в Callback notification URL, у поле callback-сповіщень вашого інтернет-магазину в EveryPay Merchant Portal — і в демо-порталі, і в робочому порталі. В OpenCart 3 URL має такий вигляд: https://your-store/index.php?route=extension/payment/wcp_everypay_payment/callback, в OpenCart 4 — https://your-store/index.php?route=extension/wcp_everypay_payment/payment/wcp_everypay_payment.callback. Він формується з адреси вітрини вашої інсталяції OpenCart. Копіюйте URL точно так, як він показаний у налаштуваннях.

Callback містить лише посилання на платежі. Розширення ніколи не довіряє йому саме по собі: воно запитує статус платежу в API EveryPay з обліковими даними того режиму, в якому було здійснено платіж. Callback для платежу, який цей магазин не створював, відхиляється без жодного запиту до EveryPay. Callback працює й тоді, коли магазин перебуває в режимі обслуговування, оскільки OpenCart 3 пропускає запити платіжних розширень, а на OpenCart 4 розширення додає для цього startup action (також для повернення покупця). Без callback замовлення отримає статус, коли покупець повернеться до магазину або коли ви натиснете Check EveryPay payment status на сторінці замовлення.

Замовлення

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

Order Status After Payment: статус замовлення, який встановлюється після перевіреного списаного або авторизованого платежу. За замовчуванням: В обробці.

Manual Review Status: платіж було здійснено, але сума або валюта не відповідають замовленню, замовлення було скасовано тим часом або воно використовує інший спосіб оплати. Примітка пояснює причину, і замовлення не позначається як оплачене. За замовчуванням: Очікування, оскільки в OpenCart немає статусу On hold. Власний статус можна створити в System > Localisation > Order Statuses і вибрати його тут.

Cancelled Order Status: платіж, що надійшов для замовлення з цим статусом, передається на ручну перевірку замість оплати замовлення. За замовчуванням: Скасовано.

Додатково

Debug log: записує події оплати у wc_evp_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити через веб; при розмірі 5 МБ його переміщують до wc_evp_debug.old.log.php. Помилки та попередження завжди записуються. Секрети API, адреси електронної пошти та дані карток ніколи не записуються. За замовчуванням: вимкнено.

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

Delete data on uninstall: якщо увімкнено, під час видалення розширення видаляються налаштування шлюзу та журнал. Дані платежів EveryPay за замовленнями завжди зберігаються. За замовчуванням: вимкнено.

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням EveryPay). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to the secure EveryPay payment page. OpenCart створює замовлення на цьому кроці, все ще без статусу. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення. Коли покупець натискає Confirm Order, розширення створює разовий платіж EveryPay на суму замовлення у валюті замовлення, з електронною адресою покупця та його платіжною адресою, і надсилає покупця на сторінку оплати EveryPay. Мова сторінки оплати відповідає мові магазину покупця (англійська, естонська, російська, латвійська, литовська, фінська або німецька; інакше англійська). Там покупець платить одним із способів, увімкнених для вашого облікового запису EveryPay.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після того, як EveryPay його підтвердить: розширення запитує статус платежу в API EveryPay під час повернення покупця та через callback. Далі замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків, а покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо EveryPay ще обробляє платіж або його API в цей момент недоступний, сторінка Payment confirmation показує Your payment is being confirmed by EveryPay. You will receive an e-mail as soon as the order is confirmed. і кнопку Check again; callback встановить статус замовлення, щойно EveryPay підтвердить платіж.

Якщо платіж не вдався, покупець повертається до оформлення замовлення з повідомленням Your EveryPay payment was not successful. Please try again or choose another payment method. Якщо покупець залишив сторінку оплати, не заплативши, повідомлення таке: The EveryPay payment was not completed. You can try again or choose another payment method. Кошик зберігається, а замовлення залишається без статусу. На OpenCart 4 ці повідомлення показуються над сторінкою оформлення замовлення.

OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 оновлює замовлення оформлення, тож нова спроба оплачує те саме замовлення новим платежем EveryPay. EveryPay не може скасувати платіж після його створення. Тому перед новим платежем розширення перевіряє через API EveryPay відкриті спроби цього замовлення та інших замовлень того самого кошика. Якщо одна з них уже оплачена або інше замовлення того самого кошика вже оплачене, покупець переходить на сторінку успіху без другого платежу. Кожна спроба запам'ятовується, тож платіж, зроблений за старим посиланням, також розпізнається. Якщо покупець усе ж оплачує друге замовлення того самого кошика (наприклад, із двох відкритих вкладок браузера), це замовлення не отримує статусу, покупець бачить сторінку успіху замовлення, а оплачене замовлення отримує примітку з проханням повернути другий платіж у EveryPay Merchant Portal.

OpenCart 4 зберігає замовлення в оформленні, доки не буде показано сторінку успіху. Якщо це замовлення було закрито без оплати (наприклад, ви його скасували), покупця повертає до оформлення з повідомленням Your previous order was cancelled. Please confirm the order again., і наступне Confirm Order оплачує нове замовлення кошика. Якщо це замовлення вже оплачене, але кошик відтоді змінився, зокрема нова кількість, з'являється повідомлення Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. Оплачене замовлення ніколи не показується як оплачене для іншого кошика.

Якщо EveryPay не може розпочати платіж, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, наприклад EveryPay is temporarily unavailable. Please try again in a moment or choose another payment method. Деталі записано в журналі.

Розширення приймає лише разові платежі. У ньому немає повернень і захоплень (capture) з магазину, збережених карток або платежів в один клік, підписок і регулярних платежів, вбудованих полів картки та мультивалютності.

Замовлення

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

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

Order Status After Payment (default Processing): EveryPay повідомив, що платіж списано або авторизовано. Примітка показує суму, валюту та посилання на платіж. Для авторизованого платежу примітка повідомляє, що кошти зарезервовано: якщо ваш рахунок не захоплює автоматично, захопіть платіж у EveryPay Merchant Portal. Коли платіж пізніше буде розрахованим, одна примітка про це повідомить.

Manual Review Status (default Pending): платіж потребує ручної перевірки. Оплачена сума або валюта не відповідають замовленню, замовлення мало Cancelled Order Status до надходження платежу, або замовлення тепер використовує інший спосіб оплати. Примітка пояснює це і повідомляє, що замовлення не було позначено як оплачене. Перевірте платіж у Merchant Portal і вручну виконайте замовлення або поверніть кошти. Наступні callback за цим платежем не завершують замовлення автоматично; правильний платіж за іншою спробою того самого замовлення його, однак, оплачує.

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

Вкладка VibeFox EveryPay Payment

У Sales > Orders відкрийте замовлення, оплачене через EveryPay. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox EveryPay Payment показує EveryPay payments of this order: Payment reference, Order reference, Mode (тестовий або робочий), Amount, EveryPay state, Result і Date кожної спроби. Нижче розміщено EveryPay notes замовлення. Вкладка показується користувачам, які мають доступ до розширення.

Check EveryPay payment status: кнопка на вкладці запитує через API статус кожного платежу EveryPay за замовленням, від нових до старих, з обліковими даними його режиму, застосовує результат, як описано вище, і додає одну примітку зі статусом кожного платежу. Потім вкладка перезавантажується. Потрібне право змінювати замовлення (System > Users > User Groups); право змінювати розширення не потрібне. Використовуйте кнопку, коли callback не надійшов, наприклад щоб побачити пізніше захоплення чи повернення. Статус, встановлений цією кнопкою, записується як ручна зміна статусу в адмінці, без листів про замовлення та оновлення залишків, як у процесі оформлення.

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

Повернення коштів і захоплення (capture) з магазину не підтримуються. Оформіть повернення в EveryPay Merchant Portal, а потім оновіть статус замовлення в OpenCart. Коли EveryPay повідомляє, що платіж повернено або оскаржено (chargeback), розширення лише додає примітку до замовлення; статус замовлення не змінюється. Повернення товарів у Sales > Returns не повертають гроші через EveryPay.

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

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

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

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

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

EveryPay does not appear at checkout: перевірте, що ліцензія активна, Enable/Disable увімкнено, ім'я користувача API, секрет API та Processing Account Name поточного режиму заповнені, і покупець платить у валюті рахунку обробки. У цих випадках сторінка налаштувань показує попередження. Також перевірте, що платіжна адреса входить до вибраної Geo Zone і що замовлення досягає Total, заданого в налаштуваннях.

The payment went through, but the order stays without a status: callback не працює. Перевірте, що URL з Callback notification URL вказано в Merchant Portal того режиму, який ви використовуєте (демо або робочого), і що він відкривається з інтернету. Замовлення також отримає статус, коли покупець повернеться до магазину після оплати. Подивіться поле Log на сторінці розширення: помилки завжди записуються.

Callback answers Unknown payment, Unknown payment reference, Payment cannot be verified or Payment does not belong to this order: платіж створено не цим магазином або не для цього замовлення, або відповідь EveryPay не відповідає йому. Нічого не змінюється.

Callback answers Missing or invalid payment_reference: запит не містив коректного посилання на платіж, наприклад коли URL відкрито в браузері.

Callback answers Not configured: відсутні облікові дані середовища, в якому створено платіж, наприклад тестовий платіж після видалення тестових облікових даних. Введіть їх знову; EveryPay повторить callback.

Callback answers Payment status unavailable, Busy, please retry or Processing error, please retry: API EveryPay було недоступно, замовлення в ту саму мить обробляв інший запит, або обробка не вдалася. Причину показано в журналі. EveryPay повторить callback.

The customer sees This payment method is not available right now: відсутні облікові дані або рахунок обробки поточного режиму.

The customer sees EveryPay is temporarily unavailable or Unable to start the EveryPay payment: EveryPay відхилив облікові дані або був недоступний. Перевірте ім'я користувача та секрет API поточного режиму.

The customer sees This payment method does not support the order currency: валюта замовлення відрізняється від валюти рахунку обробки.

The customer stays on the Payment confirmation page: EveryPay ще не завершив платіж. Замовлення отримає статус через callback або коли покупець натисне Check again після того, як EveryPay підтвердить платіж.

Order is in the review status: прочитайте EveryPay notes на вкладці VibeFox EveryPay Payment. Сума або валюта не збіглися, замовлення було скасовано до надходження платежу, або воно використовує інший спосіб оплати. Перевірте платіж у Merchant Portal і вручну виконайте замовлення або поверніть кошти.

Для розробників: перед створенням платежу розширення викликає події OpenCart wc_evp_oneoff_request (змінити запит на платіж) та wc_evp_locale (змінити мову сторінки оплати).

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox EveryPay Payment. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень із розділу Orders, які під час повторного встановлення повертаються до значень за замовчуванням. На OpenCart 4 також видаляються подія розширення (повідомлення на оформленні) та його startup action, який пропускає callback і повернення покупця в режимі обслуговування. Якщо перемикач Uninstall у розділі Advanced увімкнено, видаляються інші налаштування шлюзу (назва, опис, тестовий режим, облікові дані, рахунок обробки, журнал налагодження) та журнал. Якщо він вимкнений, їх зберігають для наступного повторного встановлення. Дані платежів EveryPay за замовленнями завжди зберігаються, тож пізні callback за старими замовленнями продовжують працювати після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

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

EveryPay — торгова марка її власника. Це розширення не афілійоване з EveryPay і не схвалене EveryPay.