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

Вимоги

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

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

Валюта: лише євро (EUR). Валюта EUR має бути увімкнена у вашому магазині, а спосіб оплати показується лише тоді, коли покупець платить у EUR. ifthenpay приймає суми від 0,01 до 99 999,99 EUR.

Обліковий запис ifthenpay: зареєструйтеся на ifthenpay.com. Вам потрібен ключ способу оплати, який ви пропонуєте: Multibanco, MB WAY або Credit Card (формат ABC-123456). Ключі показані в бекофісі ifthenpay (backoffice.ifthenpay.com) або надсилаються ifthenpay, коли спосіб оплати активують для вашого облікового запису. ifthenpay також має активувати callback для вашого ключа (див. Налаштування), а ваш магазин має бути доступним з інтернету.

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

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

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

OpenCart 3

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

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

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

4. Виберіть Payment Method, введіть його ключ ifthenpay і натисніть Save, щоб Callback URL відповідав обраному способу.

5. Скопіюйте Anti-phishing Key і Callback URL з розділу Callback і попросіть ifthenpay активувати callback для вашого ключа (у бекофісі або через підтримку ifthenpay).

6. Увімкніть Enable/Disable і натисніть Save.

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Без ключа обраного способу оплати він не показується на оформленні замовлення. Поки шлюз увімкнено без цього ключа, сторінка показує ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

ifthenpay

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

Title: назва способу оплати, що показується на оформленні замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: ifthenpay. Якщо залишити поле порожнім, на оформленні замовлення буде показано ifthenpay.

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay via Multibanco, MB WAY or Credit Card. Змініть його, щоб він відповідав способу оплати, який ви пропонуєте.

Payment Method: спосіб оплати, що пропонується на оформленні замовлення. Потрібен лише ключ цього способу.

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

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

Total: сума оформлення замовлення у валюті магазину за замовчуванням, яку має досягти замовлення, щоб пропонувався ifthenpay. Залиште поле порожнім, щоб пропонувати ifthenpay за будь-якої суми. Сам ifthenpay пропонується лише тоді, коли покупець платить у EUR, на суму від 0,01 до 99 999,99 EUR.

Ключі ifthenpay

Ключі (формат ABC-123456) показано в бекофісі ifthenpay (розділ містить посилання туди) або надсилає ifthenpay, коли спосіб оплати активують для вашого облікового запису.

Multibanco Key: ваш ключ ifthenpay Multibanco (MB) для динамічних референсів.

MB WAY Key: ваш ключ ifthenpay MB WAY.

Credit Card Key: ваш ключ ifthenpay Credit Card. Він також перевіряє підпис повернення покупця зі сторінки картки.

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

Callback

Callback повідомляє вашому магазину, що платіж здійснено. Попросіть ifthenpay активувати callback для кожного ключа, який ви використовуєте, з anti-phishing ключем і Callback URL із цього розділу. Замовлення Multibanco та MB WAY підтверджуються лише callback; платежі карткою підтверджуються також підписаним поверненням зі сторінки картки.

Anti-phishing Key: створюється розширенням і показується для копіювання. ifthenpay надсилає його назад у кожному callback; callback без нього відхиляються.

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

Anti-phishing ключ у кожному callback порівнюється з вашим. Відсутній або неправильний ключ отримує відповідь 403, і замовлення не змінюється. Callback також має відповідати платежу цього розширення: для Multibanco — за установою та референсом, для MB WAY — за замовленням і одним із його запитів MB WAY, для Credit Card — за замовленням і одним із його запитів картки. Без працюючого callback замовлення Multibanco та MB WAY ніколи не підтверджуються, а платежі карткою підтверджуються лише підписаним поверненням. Callback працює також тоді, коли магазин у режимі технічного обслуговування: OpenCart 3 пропускає запити платіжних розширень, а в OpenCart 4 розширення додає стартову дію, яка пропускає callback і повернення покупця зі сторінки картки.

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Для Multibanco та MB WAY замовлення отримує статус очікування, щойно ifthenpay видає референс або надсилає запит MB WAY; для Credit Card замовлення отримує статус лише з callback або підписаного повернення. Замовлення позначається оплаченим лише тоді, коли сума збігається із сумою замовлення до копійки. Кожне з полів нижче перелічує ваші статуси замовлень OpenCart.

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

Awaiting payment status: видано референс Multibanco або надіслано запит MB WAY, і покупець ще має сплатити. Реквізити Multibanco надсилаються з цим статусом — у листі про замовлення та в історії замовлень покупця. За замовчуванням: В очікуванні.

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

Додатково

Test Mode: Credit Card і Multibanco використовують тестові (sandbox) адреси ifthenpay; реальні кошти не списуються, і ви використовуєте тестові ключі, які надає ifthenpay. MB WAY не має sandbox: тестуйте його тестовим ключем ifthenpay. На кроці Confirm Order показується значок TEST MODE. За замовчуванням: вимкнено.

Debug Log: запити API та callback записуються у файл ifthenpay_p_debug.log.php у папці логів OpenCart (storage/logs). Файл не можна відкрити через веб, його ротують при досягненні 5 МБ. Помилки записуються завжди. Ключі, anti-phishing ключ і повні номери телефонів ніколи не записуються в журнал. За замовчуванням: вимкнено.

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

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

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням ifthenpay). На кроці Confirm Order покупець бачить ваш опис і підказку щодо способу оплати. OpenCart створює замовлення на цьому кроці, ще без статусу.

В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення.

Multibanco. Покупець бачить You will receive a Multibanco reference to complete the payment. Коли покупець натискає Confirm Order, розширення створює динамічний референс Multibanco на суму замовлення, і замовлення отримує Awaiting payment status. На сторінці успішного оформлення замовлення показано Multibanco Payment Details: установа, референс і сума, з текстом Please use these details to pay at any Multibanco ATM or through your online banking. Ті самі дані надсилаються в листі про замовлення та відображаються в історії замовлень покупця. Якщо для замовлення вже видано референс на ту саму суму, він використовується повторно. Замовлення оплачується, коли ifthenpay надсилає callback про платіж.

MB WAY. Покупець вводить MB WAY phone number (912 345 678, +351 912 345 678 або 351#912345678 для інших країн); телефон із замовлення підставляється автоматично. Розширення надсилає запит на оплату на телефон, і замовлення отримує Awaiting payment status. На сторінці успішного оформлення замовлення написано A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. Замовлення оплачується, коли ifthenpay надсилає callback. Зберігається лише замаскований номер телефону. За замовчуванням OpenCart 4 не запитує телефон на оформленні замовлення; поле залишається порожнім, і покупець вводить номер.

Credit Card. Покупець бачить You will be redirected to a secure page to enter your card details. і перенаправляється на сторінку картки ifthenpay. Замовлення залишається без статусу, кошик зберігається. Після успішного платежу покупець повертається до вашого магазину. Повернення приймається лише за дійсного підпису ifthenpay, секрету цієї спроби та запиту картки за замовленням; тоді замовлення позначається оплаченим, і покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо повернення не вдається перевірити, нічого не змінюється, а сторінка Payment confirmation показує Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. з кнопками Check again і Back to checkout; callback підтверджує платіж, щойно надходить. Якщо платіж карткою не пройшов або скасовано, покупець повертається до оформлення замовлення з повідомленням The card payment was not completed. You can try again or choose another payment method. або The card payment was cancelled. You can try again or choose another payment method. Кожна спроба оплати карткою за замовленням зберігається, тож платіж, зроблений у раніше відкритій вкладці, також приймається. В OpenCart 4 ці повідомлення показуються над сторінкою оформлення замовлення.

Коли платіж підтверджено, замовлення отримує статус стандартним способом OpenCart, зі звичайними листами про замовлення. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 оновлює замовлення оформлення, тож після скасованого чи невдалого платежу карткою або відхиленого запиту MB WAY покупець оплачує те саме замовлення новою спробою. Якщо для того самого кошика вже є оплачене замовлення або замовлення, що очікує оплати Multibanco чи MB WAY, покупець переходить на сторінку успіху цього замовлення, а не починає новий платіж. Реквізити Multibanco та підказка MB WAY показуються на сторінці успіху лише тоді, коли замовлення очікує оплати. Зміна кошика, зокрема нова кількість, вважається новим кошиком, якому потрібен власний платіж.

В OpenCart 4 замовлення залишається в оформленні, доки не буде показано сторінку успіху. Якщо це замовлення тим часом закрито без оплати (наприклад, ви скасували замовлення, що очікує оплати Multibanco), покупець повертається до оформлення з повідомленням Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Якщо замовлення вже оформлено, а кошик відтоді змінився, повідомлення таке: Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. В обох випадках наступне Confirm Order оплачує нове замовлення кошика.

Якщо платіж не вдається розпочати, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, наприклад The Multibanco reference could not be created. Please try again or choose another payment method., The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. або The payment service is temporarily unavailable. Please try again in a few minutes. Технічна причина записується в журнал.

Розширення пропонує один спосіб ifthenpay за раз. Воно не підтримує Payshop, Cofidis Pay, Apple Pay, Google Pay, PIX або Pay-by-Link, підписки чи збережені картки, автоматичне закінчення терміну дії або скасування неоплачених референсів Multibanco, а також опитування статусу платежу.

Замовлення

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

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

Awaiting payment status (default Pending): видано референс Multibanco або надіслано запит MB WAY. Неоплачені референси та відхилені запити MB WAY не скасовують замовлення автоматично; за потреби скасуйте такі замовлення самостійно.

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

Payment on hold status (default Pending): отримана сума відрізнялася від суми замовлення (наприклад, кошик змінили після початку платежу карткою), платіж надійшов після скасування замовлення, або інше замовлення того самого кошика вже було оплачене. Примітка пояснює це, і покупця не просять платити знову. Перевірте платіж у бекофісі ifthenpay і вручну завершіть або поверніть замовлення. Пізніший правильний платіж за таким замовленням його не змінює.

Другий платіж за вже оплаченим замовленням лише додає примітку, щоб перевірити можливий дублікат платежу в бекофісі ifthenpay. Замовлення, яке ви перевели в інший статус (наприклад, повернено), ніколи не відкривається знову; натомість додається примітка.

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

Вкладка VibeFox ifthenpay Gateway

У Sales > Orders відкрийте замовлення, оплачене через ifthenpay. Унизу сторінки замовлення, поряд з History і Additional, вкладка VibeFox ifthenpay Gateway перелічує спроби оплати замовлення (дата, спосіб, позначка Sandbox для тестових платежів, сума, установа та референс Multibanco або замаскований телефон MB WAY, ID запиту ifthenpay і статус), попередження Payment on hold, поки замовлення утримується, і ifthenpay notes замовлення. Вкладка доступна лише для читання і показується користувачам, які мають доступ до розширення.

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

Повернення коштів з OpenCart не підтримуються. Поверніть платіж у бекофісі ifthenpay і вручну зафіксуйте його в OpenCart. Повернення товарів у Sales > Returns не повертають гроші через ifthenpay. Callback про повернення (DEVOLVIDO) лише додає примітку. Інші статуси, які повідомляє ifthenpay, також лише додають примітку.

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

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

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

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

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

ifthenpay не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, введено ключ обраного Payment Method, покупець платить у EUR, а сума становить від 0,01 до 99 999,99 EUR. Також перевірте, що платіжна адреса входить до вибраної Geo Zone, і що сума замовлення досягає значення Total з налаштувань.

Покупець заплатив, але замовлення залишається в статусі очікування або без статусу: callback не доходить до вашого магазину. Перевірте, що ifthenpay активувала Callback URL і anti-phishing ключ для ключа, який ви використовуєте, і що URL відповідає обраному способу. Магазин має бути доступним з інтернету, а не на localhost і не за логіном. Увімкніть Debug Log і перегляньте поле Log на сторінці розширення.

Callback відповідає 403 Forbidden: anti-phishing ключ у callback відсутній або відрізняється від вказаного в налаштуваннях. Надішліть ifthenpay ключ, який показано в налаштуваннях, ще раз.

Callback відповідає 503 Not configured: anti-phishing ключ ще не створено. Відкрийте налаштування розширення один раз; ifthenpay повторить callback.

Callback відповідає 503 Busy: це саме замовлення в цей момент обробляв інший запит. ifthenpay повторить callback.

Callback відповідає Order not found: референс або запит не належить до платежу цього розширення, або замовлення оформлено з іншим способом оплати.

Чому оплачене замовлення перевели в очікування? Отримана сума відрізнялася від суми замовлення, платіж надійшов після скасування замовлення, або інше замовлення того самого кошика вже було оплачене. Прочитайте примітки на вкладці VibeFox ifthenpay Gateway, перевірте платіж у бекофісі ifthenpay і вручну завершіть або поверніть замовлення.

Запит MB WAY не вдалося надіслати: номер телефону не прив'язаний до MB WAY або має неправильний формат. Використовуйте 912 345 678 або 351#912345678 для номерів інших країн.

Тестовий режим і MB WAY: у ifthenpay немає sandbox для MB WAY; використовуйте тестовий ключ, наданий ifthenpay.

Видалення

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

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

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