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

Вимоги

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

PHP: 8.0 або новіша версія.

Сервіс Autopay: потрібні Service ID і Shared key (хеш-ключ) вашого сервісу Autopay. Вони показані в портальному кабінеті мерчанта Autopay: portal.autopay.eu для робочого режиму та testportal.autopay.eu для тестів. Тестові сервіси мають власні Service ID і Shared key; попросіть Autopay відкрити такий сервіс. Хеш-функція сервісу має бути SHA-256.

Валюта: валюта замовлення має бути PLN, EUR, GBP, USD або CZK і прийматися вашим сервісом Autopay.

Доступний магазин: Autopay має мати змогу надсилати сповіщення у ваш магазин, тому магазин має бути доступний з інтернету без базової автентифікації та без брандмауера, який блокує POST-запити. Режим обслуговування не блокує сповіщення, оскільки OpenCart пропускає запити платіжних розширень.

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

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

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

OpenCart 3

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

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

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

4. Введіть Service ID і Shared key (тестовий і робочий) та виберіть валюти вашого сервісу.

5. У порталі Autopay задайте для вашого сервісу ITN URL, URL повернення та хеш-функцію SHA-256 (див. Налаштування).

6. Увімкніть Enable/Disable і натисніть Save. Перевірте замовлення в тестовому режимі, а потім вимкніть Test mode для реальних платежів.

OpenCart 4

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

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

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

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

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

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

Усі параметри розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо Service ID або Shared key вибраного середовища порожні (тоді спосіб оплати приховано під час оформлення замовлення), і якщо типова валюта магазину не вибрана в Currencies (тоді спосіб оплати приховано в цій валюті). Поки увімкнено тестовий режим, вона показує Test mode is on: payments go to the Autopay test environment (testpay.autopay.eu), no real money is taken. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження Title має містити від 1 до 128 символів, Sort Order має бути цілим числом, Total має бути числом 0 або більше, а Service ID може містити лише літери, цифри, дефіси та підкреслення. Якщо в якомусь полі помилка, нічого не зберігається, і сторінка вказує на це поле.

Autopay

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

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

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

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

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

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

Сервіс Autopay

Service ID і Shared key показано в портальному кабінеті мерчанта Autopay (portal.autopay.eu або testportal.autopay.eu, посилання наведено в цьому розділі).

Test mode: використовує тестове середовище Autopay (testpay.autopay.eu) і тестові облікові дані, наведені нижче. За замовчуванням: увімкнено. Вимкніть його, щоб приймати реальні платежі на pay.autopay.eu з робочими обліковими даними. Поки режим увімкнено, покупці бачать Test mode: no real payment is taken. на кроці Confirm Order.

Service ID (production): числовий ідентифікатор сервісу на portal.autopay.eu.

Shared key (production): хеш-ключ робочого сервісу. Зберігайте його в таємниці.

Service ID (test): числовий ідентифікатор сервісу на testportal.autopay.eu.

Shared key (test): хеш-ключ тестового сервісу.

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

Currencies: валюти, які приймає ваш сервіс Autopay: PLN, EUR, GBP, USD, CZK. Autopay зазвичай відкриває окремий сервіс для кожної валюти. Спосіб оплати пропонується лише тоді, коли валюта оформлення замовлення вибрана тут. За замовчуванням: PLN.

Адреси ITN та повернення

Введіть ці адреси в портал Autopay для вашого сервісу — і для робочого, і для тестового режиму. Точні адреси показано в полі Addresses цього розділу, вони формуються з адреси вітрини вашої інсталяції OpenCart:

Це адреси для OpenCart 3. В OpenCart 4 вони такі:

Скопіюйте адреси точно так, як їх показують налаштування. Без URL ITN замовлення ніколи не підтверджуються: OpenCart залишає замовлення без статусу, доки Autopay не підтвердить платіж. Кожне ITN перевіряється за хешем SHA-256, обчисленим із Shared key сервісу, вказаного в сповіщенні. Сповіщення без дійсного хешу або з невідомим Service ID відхиляються. Сповіщення застосовується до замовлення, лише якщо його платіж було розпочато з тим самим сервісом Autopay, тож тестове сповіщення ніколи не підтверджує робочий платіж. Сповіщення щодо платежів, розпочатих до перемикання Test mode, і далі перевіряються правильним ключем, доки обидві облікові дані збережено.

Розширення обробляє в ITN такі статуси платежів:

Orders

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Замовлення отримує статус лише тоді, коли Autopay підтверджує платіж (ITN SUCCESS). Невдалий або покинутий платіж залишає його без статусу. У OpenCart 4 неоплачене замовлення, створене під час оформлення, може отримати статус Voided, який OpenCart 4 встановлює, коли покупець повертається до кроку Confirm Order; розширення сприймає таке замовлення як замовлення без статусу, а пізніший ITN SUCCESS все одно позначить його оплаченим. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Order Status After Payment: статус, що встановлюється, коли Autopay підтверджує платіж з очікуваними сумою та валютою. За замовчуванням: Processing.

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

Advanced

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

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

Import / Export

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

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

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

На кроці Payment Method покупець вибирає спосіб оплати (за замовчуванням Autopay). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to the secure Autopay payment page to complete the payment. OpenCart створює замовлення на цьому кроці, ще без статусу. Коли покупець натискає Confirm Order, браузер надсилає до Autopay підписану форму платежу: сума замовлення у валюті замовлення, номер замовлення OpenCart як OrderID, опис Order з номером і електронна адреса покупця. На сторінці Autopay покупець обирає спосіб оплати та платить.

Замовлення позначається оплаченим лише після того, як Autopay підтверджує його підписаним ITN, а сума та валюта збігаються із замовленням. Тоді замовлення отримує статус стандартним способом OpenCart, зі звичайними листами про замовлення та оновленням залишків на складі. Після оплати покупець повертається до вашого магазину. Адреса повернення підписана, але ніколи не змінює замовлення. Якщо замовлення вже має статус, покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо ITN ще не надійшло, сторінка Payment confirmation показує Thank you. Your payment is being confirmed by Autopay — your order is confirmed as soon as Autopay reports the payment, and you will receive an e-mail. з кнопками Check again і Back to checkout.

Якщо Autopay повідомив про невдалий платіж, покупець повертається до оформлення замовлення з повідомленням The payment was not completed. You can try again or choose another payment method. Кошик зберігається. Кожна нова спроба створює нове замовлення OpenCart (в OpenCart 4 покупець оплачує те саме замовлення знову, з новою спробою під тим самим OrderID). Якщо інше замовлення з того самого кошика (ті самі товари в тому самому візиті) вже оплачено, покупець переходить на сторінку успіху замість повторної оплати. Нова покупка після завершеної є новим кошиком і оплачується звичайним способом. Якщо платіж неможливо розпочати, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, наприклад Autopay payments are not configured. Please choose another payment method or contact the store. або про те, що Autopay не може приймати платежі в цій валюті.

На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення. Повідомлення про платіж, який не завершено, показується над сторінкою оформлення. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його. Якщо магазин тим часом закрив це замовлення (наприклад, ви його скасували), покупець повертається до оформлення з повідомленням The payment was not completed. You can try again or choose another payment method., або, якщо замовлення було оплачено через Autopay, з повідомленням Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. Якщо замовлення оформлення вже оплачено для іншого кошика, повідомлення таке: Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. Наступне натискання Confirm Order оплачує нове замовлення. Зміна кошика, зокрема нова кількість товару, вважається новим кошиком, якому потрібна окрема оплата. ITN також працює, коли магазин перебуває в режимі обслуговування: для цього в OpenCart 4 розширення додає стартову дію (startup action).

Розширення не підтримує повернення коштів з OpenCart, підписки та регулярні платежі, збережені картки, код BLIK або форму картки на сторінці оформлення замовлення, вибір банку чи платіжного каналу на сторінці оформлення замовлення, і використовує один Service ID на середовище.

Замовлення

Order statuses

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

Order Status After Payment (default Processing): Autopay підтвердив платіж, сума та валюта збігаються. Примітка показує суму, ідентифікатор транзакції Autopay (remoteID) і дату платежу.

On Hold Status (default Pending): Autopay повідомив про суму або валюту, що відрізняються від суми замовлення. Замовлення не позначається оплаченим. Перевірте транзакцію в порталі Autopay і завершіть її або поверніть кошти вручну. Пізніше правильне сповіщення для цього замовлення позначить його оплаченим. Той самий статус застосовується, коли надходить платіж за замовленням, статус якого ви тим часом змінили, наприклад на скасовано: примітка просить перевірити залишки на складі та виконати замовлення або повернути платіж.

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

VibeFox Autopay Payment tab

У розділі Sales > Orders відкрийте замовлення, оплачене через Autopay. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox Autopay Payment показує OrderID at Autopay, Service ID і середовище з позначкою Test mode для тестових платежів, Amount, статус Payment attempt, Autopay transaction ID і Autopay notes замовлення. Вкладка лише для читання і показується користувачам, які мають доступ до розширення.

Refunds

Повернення коштів через Autopay не підтримуються. Поверніть платіж у порталі Autopay, а потім вручну оновіть замовлення в OpenCart.

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

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

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

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

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

Autopay не відображається під час оформлення замовлення: перевірте, що ліцензію активовано, Enable/Disable увімкнено, у вибраному середовищі є Service ID і Shared key, а валюта оформлення замовлення вибрана в Currencies. Сторінка налаштувань показує попередження, якщо чогось із цього бракує. Перевірте також, чи знаходиться платіжна адреса у вибраній Geo Zone і чи досягає замовлення Total, заданого в налаштуваннях.

Платіж пройшов, але замовлення залишається без статусу: Autopay не доставив ITN, або магазин його відхилив. Перевірте, що ITN URL, показаний у налаштуваннях, задано для сервісу в порталі Autopay (робочий або тестовий), що хеш-функція — SHA-256 і що Shared key розширення збігається з сервісом. Перевірте, що магазин доступний з інтернету. Увімкніть Logging і перегляньте поле Log на сторінці розширення.

Журнал показує ITN rejected: invalid hash: Shared key не збігається з сервісом, або хеш-функція сервісу не SHA-256.

Журнал показує, що service ID не налаштовано: сповіщення надійшло від сервісу, Service ID якого не введено в розширення, або його Shared key порожній.

Журнал показує could not lock the order, Autopay will retry: замовлення в цей момент обробляло інше сповіщення. Магазин відповідає так, щоб Autopay надіслав сповіщення повторно.

URL ITN у браузері показує METHOD_NOT_ALLOWED: це нормально. URL приймає лише POST-запити від Autopay.

Замовлення має статус утримання з приміткою про розбіжність: Autopay повідомив про суму або валюту, що відрізняються від суми замовлення. Перевірте транзакцію в порталі Autopay і вручну завершіть або поверніть замовлення.

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

Після оплати покупець потрапляє на головну сторінку: адресу повернення не вдалося перевірити, наприклад через те, що Service ID не введено в розширення. Замовлення не зачіпається; воно слідує за ITN.

Покупець бачить This payment method is not available. Please reload the checkout page.: сесія оформлення замовлення більше не відповідає замовленню, або спосіб оплати тим часом вимкнули чи він утратив облікові дані. Покупець перезавантажує оформлення замовлення.

Для розробників: перед підписанням платіжної форми розширення викликає подію OpenCart wc_ap_payment_params з параметрами форми та замовленням; через неї не можна змінити сервіс, номер замовлення, суму чи валюту.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox Autopay Payment. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень із розділу Orders. Розширення завжди видаляє інші налаштування шлюзу, включно з Service ID і Shared key, а також журнал. Опції зберегти налаштування немає. В OpenCart 4 також видаляються події розширення та його стартова дія, яка пропускає ITN у режимі обслуговування. Записи про платежі Autopay завжди зберігаються. Наявні замовлення зберігають свої платіжні примітки.

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

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