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

Вимоги

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

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

Магазин у Barion: вам потрібні POSKey (секретний ключ) вашого магазину та адреса електронної пошти гаманця Barion, на який надходять платежі. Обидва значення є на порталі Barion: secure.barion.com для робочого режиму, secure.test.barion.com для тестового, у розділі My stores та у вашому магазині. Тестові та робочі облікові дані відрізняються.

Валюта: валюта замовлення має бути HUF, EUR, USD або CZK. Для інших валют спосіб оплати приховується на етапі оформлення замовлення.

Доступний магазин: Barion викликає ваш магазин після кожного платежу, тому сайт має бути доступним з інтернету, без брандмауера чи базової автентифікації перед ним. Режим обслуговування не блокує зворотний виклик: OpenCart 3 пропускає запити розширень оплати, а в OpenCart 4 розширення додає для цього стартову дію.

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

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

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

OpenCart 3

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

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

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

4. Введіть тестовий POSKey і e-mail тестового гаманця, залиште увімкненим Test Mode, увімкніть Enable/Disable і натисніть Save. Оформіть тестове замовлення.

5. Коли все працює, введіть робочі облікові дані та вимкніть Test Mode.

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Barion Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо для поточного режиму не вказано POSKey або e-mail отримувача (тоді спосіб оплати приховується на етапі оформлення замовлення), а також якщо валюта за замовчуванням вашого магазину не підтримується Barion; наводиться список підтримуваних валют. Поки тестовий режим увімкнено, відображається повідомлення Test mode is on: payments go to the Barion sandbox (api.test.barion.com), no real money is charged. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

Barion

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

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

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.

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

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

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

Облікові дані магазину в Barion

POSKey і e-mail гаманця отримайте на порталі Barion: secure.barion.com (робочий) або secure.test.barion.com (тестовий), My stores, ваш магазин (портали пов'язано посиланнями в цьому розділі). Тестовий режим використовує лише тестові облікові дані, робочий — лише робочі.

Test Mode: використовує тестові облікові дані, наведені нижче, і пісочницю Barion (api.test.barion.com). Реальні кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати справжні платежі. Поки режим увімкнено, покупці на кроці Confirm Order бачать Test mode: no real payment is taken.

Test POSKey: секретний ключ (POSKey) вашого магазину в тестовій системі Barion (secure.test.barion.com, My stores).

Test Payee Email: адреса електронної пошти вашого тестового гаманця Barion, на який надходять тестові платежі.

Live POSKey: секретний ключ (POSKey) вашого магазину в робочій системі Barion (secure.barion.com, My stores).

Live Payee Email: адреса електронної пошти вашого гаманця Barion, на який надходять платежі.

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

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

Замовлення

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

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

Awaiting Barion Payment Status: покупець завершив дії на сторінці Barion, але Barion ще обробляє платіж. За замовчуванням: Очікує оплати.

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

Payment Failed Status: замовлення, що очікує оплати, платіж Barion за яким не вдався. За замовчуванням: Невдалий.

Payment Canceled Status: замовлення, що очікує оплати, платіж Barion за яким було скасовано або він прострочився. За замовчуванням: Скасовано.

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

Додатково

Logging: записує запити та зворотні виклики Barion у файл barion_p_debug.log.php у папці логів OpenCart (storage/logs). Відкрити файл через веб не можна. Секретні ключі та e-mail гаманців не записуються. За замовчуванням: вимкнено. Поки журнал вимкнено, нічого не записується, зокрема помилки.

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

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

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

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

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

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

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

Після оплати покупець повертається до вашого магазину, а Barion також викликає URL зворотного виклику. Жоден із цих запитів сам по собі нічого не позначає як оплачене: розширення запитує в Barion стан платежу з POSKey того режиму, у якому платіж було ініційовано. Замовлення позначається як оплачене лише після підтвердження Barion і лише якщо сума та валюта відповідають замовленню. Посилання повернення містить випадковий токен спроби оплати, і перевіряються лише платежі, ініційовані для цього замовлення. Далі замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків. В OpenCart 4 браузер не надсилає сесію магазину, коли Barion повертає покупця, тож розширення спочатку показує коротку сторінку, яка знову відкриває ту саму адресу повернення з вашого магазину: покупець зберігає кошик і вхід до облікового запису.

Якщо платіж пройшов успішно, покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо платіж ще обробляється в Barion, замовлення отримує статус Awaiting Barion Payment Status, а сторінка успіху показує Your payment is being confirmed by Barion. You will receive an e-mail as soon as it is confirmed. Якщо Barion недоступний під час повернення покупця або платіж здійснено, але ще не застосовано, сторінка Payment confirmation показує той самий текст і кнопку Check again; зворотний виклик встановлює статус замовлення, щойно Barion підтверджує платіж.

Якщо платіж не було завершено (скасовано, прострочено або не вдалося), замовлення залишається без статусу, кошик зберігається, і покупець повертається до оформлення замовлення з повідомленням Payment was not completed. Please try again. Якщо посилання повернення не відповідає замовленню, повідомлення буде Payment verification failed. В OpenCart 4 ці повідомлення показуються над сторінкою оформлення замовлення. В OpenCart 3 кожна нова спроба створює нове замовлення OpenCart. В OpenCart 4 одне замовлення зберігається для оформлення і оновлюється, тож нова спроба — це новий платіж Barion за тим самим замовленням. Barion не може скасувати розпочатий платіж, тому перед новим платежем розширення перевіряє в Barion попередні відкриті платежі кошика: якщо один з них оплачено або він ще обробляється, його замовлення підтверджується, і покупець переходить на сторінку успіху без повторної оплати. Якщо інше замовлення того самого кошика (ті самі товари в тому самому візиті) вже оплачено, покупець також переходить на сторінку успіху без нового платежу; нова покупка після завершеної — це новий кошик. Пізній платіж за попередньою спробою того самого замовлення все одно його підтверджує, а попередня спроба, що прострочується, замовлення не скасовує. Якщо покупець оплачує два замовлення одного кошика (дві вкладки), другий платіж не підтверджує його замовлення: оплачене замовлення отримує примітку про те, що отримано другий платіж за той самий кошик, щоб ви могли повернути його в порталі Barion.

В OpenCart 4 замовлення зберігається на етапі оформлення доти, доки не буде показано сторінку успішного оформлення. Якщо це замовлення тим часом було закрито без оплати (наприклад, очікувану оплату скасовано в Barion або ви скасували замовлення), наступне натискання Confirm Order повертає покупця до оформлення з повідомленням Payment was not completed. Please try again., і оформлення тоді створює нове замовлення з кошика. Якщо замовлення вже має статус і кошик відтоді змінився (інші товари або кількості), замовлення виходить з оформлення, а змінений кошик отримує нове замовлення і власний платіж.

Якщо платіж не вдається розпочати, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою: The Barion payment could not be started. Please try again or choose another payment method., Barion does not support payments in валюта замовлення, Barion payment is not available at the moment. Please choose another payment method. або Barion cannot process an order with a zero total. Подробиці записуються в журнал, якщо увімкнено Logging.

Розширення приймає лише негайні платежі. Воно не підтримує платежі з резервуванням або відкладеним списанням, підписки та періодичні платежі, збережені картки, Barion Pixel і додаткові дані 3-D Secure; 3-D Secure обробляє Barion на своїй сторінці оплати.

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

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

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

Awaiting Barion Payment Status (за замовчуванням Pending): Barion повідомляє, що платіж ще обробляється. Примітка показує PaymentId Barion, суму і, у тестовому режимі, (test mode). Замовлення переходить у статус оплаченого, коли Barion підтверджує платіж.

Order Status After Payment (за замовчуванням Processing): Barion підтвердив платіж. Примітка показує суму, PaymentId і транзакцію Barion.

Barion Payment On Hold Status (за замовчуванням Pending): Barion повідомив суму або валюту, що відрізняються від суми замовлення. Примітка показує обидві суми. Перевірте платіж у порталі Barion, а потім виконайте замовлення або поверніть платіж у порталі Barion.

Payment Canceled Status (за замовчуванням Canceled): остання спроба оплати замовлення, що очікує, була скасована або прострочена в Barion.

Payment Failed Status (за замовчуванням Failed): остання спроба оплати замовлення, що очікує, не вдалася.

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

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

Вкладка VibeFox Barion Gateway

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

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

На вкладці VibeFox Barion Gateway введіть суму (підставляється сума, яку ще не повернуто), за бажанням Reason (optional), і натисніть Refund via Barion. Підтвердьте запитання Повернути цю суму через Barion? Цю дію неможливо скасувати. Підтримуються повне та часткове повернення. Вам потрібне право змінювати розширення (встановлюється в System > Users > User Groups). Причина передається в Barion як коментар. Повернення в HUF мають бути цілими сумами. Повернення надсилається в тому режимі (тестовому або робочому), у якому було здійснено платіж, тож POSKey цього режиму має бути вказано. Якщо Barion не приймає або не підтверджує повернення, вкладка показує помилку, і повернення не реєструється. Успішне повернення додається до історії повернень і приміток разом із транзакцією та статусом Barion. Повне повернення встановлює замовленню Refunded Status без сповіщення покупця і без повернення товарів на склад, як і при ручній зміні статусу. Часткове повернення статус не змінює.

Повернення доступні після того, як Barion підтвердив платіж і замовлення оплачено ним. Платіж із розбіжністю суми або валюти не можна повернути з OpenCart; поверніть його в порталі Barion. Повернення товарів у Sales > Returns не повертає гроші через Barion.

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

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

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

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

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

Barion не з'являється на етапі оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, у поточному режимі вказано POSKey і e-mail отримувача (на сторінці налаштувань з'являється попередження, якщо чогось бракує), а валюта замовлення — HUF, EUR, USD або CZK. Також перевірте, що платіжна адреса належить до вибраної Geo Zone і що замовлення досягає Total, заданого в налаштуваннях.

Платіж пройшов, але замовлення залишається без статусу: замовлення отримує статус, коли Barion викликає URL зворотного виклику або коли покупець повертається до вашого магазину. Переконайтеся, що сайт доступний з інтернету (без брандмауера чи базової автентифікації перед URL зворотного виклику). Перевірте, що POSKey режиму, у якому було зроблено платіж, є правильним, оскільки розширення запитує з ним стан платежу в Barion. Увімкніть Logging, щоб бачити зворотний виклик.

Зворотний виклик відповідає Busy, retry: замовлення в цей самий момент обробляло повернення покупця або не вдалося встановити статус замовлення. Barion викличе знову. Увімкніть Logging, щоб побачити причину.

Зворотний виклик відповідає API error: магазин не зміг прочитати стан платежу з Barion або POSKey режиму, у якому було зроблено платіж, не вказано. Перевірте цей POSKey.

Зворотний виклик відповідає Order not found: PaymentId не було ініційовано цим магазином. Виклики Barion для інших магазинів або тестових систем ігноруються.

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

Покупець бачить помилку після Confirm Order: увімкніть Logging і перегляньте поле Log на сторінці розширення. Неправильний POSKey або e-mail отримувача дають The Barion payment could not be started. This payment method is not available. Please reload the checkout page. означає, що сесія оформлення більше не відповідає замовленню, або спосіб оплати тим часом вимкнули: покупець має перезавантажити сторінку оформлення.

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

Чому не можна повернути 10.50 HUF: Barion обробляє HUF без десяткових знаків. Введіть ціле значення суми.

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

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

Видалення

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

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

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