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

Вимоги

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

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

Обліковий запис Quickpay: потрібні два значення з менеджера Quickpay: ключ API користувача API (для створення платежів, захоплення та повернення коштів) і приватний ключ облікового запису (для перевірки підпису callback-запитів Quickpay). Більше в Quickpay нічого налаштовувати не потрібно. Ваш магазин має бути доступним з інтернету, без захисту паролем, щоб callback-запити Quickpay могли до нього дійти.

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

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

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

OpenCart 3

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

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

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

4. Вставте ключ API та приватний ключ з менеджера Quickpay і натисніть Test API key (див. Налаштування).

5. Виберіть режим захоплення та статус замовлення після оплати, увімкніть Enable/Disable і натисніть Save. Поки ваш обліковий запис Quickpay працює в тестовому режимі, увімкніть Test payments і зробіть платіж тестовою карткою Quickpay.

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Quickpay Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Доки ключ API і приватний ключ не збережено обидва, сторінка показує Quickpay needs setup: enter the API key and the private key. Until both are saved the payment method is hidden at checkout. Поки Test payments увімкнено, сторінка нагадує вимкнути його, коли ваш обліковий запис Quickpay перейде в робочий режим. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

Quickpay

Enable/Disable: Enable Quickpay вмикає або вимикає спосіб оплати. Типово: off.

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

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

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

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

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

Облікові дані API Quickpay

У менеджері Quickpay (manage.quickpay.net, на сторінці є посилання на нього) відкрийте Settings > Integration. Скопіюйте ключ API користувача API (Settings > Users) і приватний ключ облікового запису.

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

API key: ключ API користувача API Quickpay. Використовується для створення платежів, захоплення та повернення коштів.

Private key: приватний ключ облікового запису. Використовується для перевірки підпису (HMAC-SHA256) callback-запитів Quickpay. Без нього жоден платіж не може бути підтверджений, а callback-запити відхиляються.

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

Test API key: ця кнопка перевіряє ключ, введений у поле API key (або збережений, якщо поле порожнє), автентифікованим запитом до Quickpay, без збереження. Вона відповідає Connection successful — the API key is valid., Quickpay rejected the API key., API key is not configured. або Connection failed: з причиною.

Test payments: приймає платежі, зроблені тестовими картками Quickpay. Окремого sandbox у Quickpay немає: поки ваш обліковий запис Quickpay працює в тестовому режимі, платежі виконуються тестовими картками і позначаються як тестові. Вмикайте лише під час тестування. Коли вимкнено, тестовий платіж ніколи не позначає замовлення оплаченим. Коли увімкнено, покупці бачать на кроці Confirm Order напис Test mode: Quickpay test cards are accepted. Типово: off.

Оплата

Capture: коли гроші списуються з картки.

Order status after payment: який статус отримує оплачене замовлення після того, як Quickpay підтвердить захоплений платіж.

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

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

"Payment accepted" status: захоплений платіж підтверджено, сума та валюта збігаються. Типово: Processing.

"Delivered (completed)" status: використовується замість попереднього, коли Order status after payment має значення Delivered (completed). Типово: Complete.

"Quickpay payment on hold" status: платіж лише авторизовано і очікується захоплення, сума або валюта не збігаються, або захоплення не вдалося. Типово: Pending, бо в OpenCart немає статусу On hold; примітка до замовлення пояснює причину. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

Cancelled status: встановлюється, коли платіж замовлення на утриманні скасовано в Quickpay. Коли ви переводите замовлення цього розширення в цей статус, його неоплачене посилання на оплату видаляється в Quickpay (див. Замовлення та повернення коштів). Типово: Canceled.

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

Додатково

Debug log: записує у файл qpg_debug.log.php у папці логів OpenCart (storage/logs). Файл не можна відкрити через веб; при досягненні 5 МБ його переміщують до qpg_debug.old.log.php. Помилки та попередження, наприклад відхилені callback-запити та помилки API Quickpay, записуються завжди. Увімкніть це, щоб записувати також деталі кожного запиту та callback-запиту. Ключі API, дані картки та дані покупців ніколи не записуються. Типово: off.

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

Delete data: якщо увімкнено, під час видалення розширення видаляються налаштування шлюзу та журнал. Дані замовлень (платежі Quickpay, повернення, примітки) завжди зберігаються. Типово: off.

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

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

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

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

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

Після оплати покупець повертається до вашого магазину. Саме повернення нічого не позначає оплаченим. Замовлення позначається оплаченим лише після підтвердження Quickpay: підписаний callback-запит встановлює статус замовлення, коли захоплена сума та валюта збігаються із замовленням. Далі замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків, і покупець бачить сторінку успішного оформлення замовлення OpenCart. За Authorize only замовлення натомість отримує статус "Quickpay payment on hold" status, а платіж ви захоплюєте пізніше. Якщо callback ще не надійшов, коли покупець повертається, сторінка Payment confirmation показує Your payment is being confirmed by Quickpay. You will receive an e-mail as soon as the order is confirmed. з кнопками Check again і Back to checkout. Коли callback Quickpay пізніше переводить замовлення зі статусу "Quickpay payment on hold" status в оплачений статус або в Cancelled status, покупець отримує лист.

Якщо покупець скасовує оплату у вікні Quickpay, посилання на оплату видаляється в Quickpay, і покупець повертається на оформлення замовлення з повідомленням The payment was cancelled. You can try again or choose another payment method. Якщо картку відхилено, повідомлення таке: The payment was not completed. You can try again or choose another payment method. Кошик зберігається. Нова спроба того самого замовлення отримує нове посилання на той самий платіж Quickpay. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; посилання на оплату попередніх замовлень того самого кошика тоді видаляються, щоб старе посилання ніколи не могло бути оплачене паралельно. Поки платіж кошика авторизовано й очікує захоплення, другий платіж не розпочинається; покупець бачить сторінку Payment confirmation.

На OpenCart 4 повідомлення про скасування та відмову показуються над сторінкою оформлення. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його щоразу, коли показується крок Confirm Order, тож після скасування або відмови те саме замовлення оплачується новим посиланням на той самий платіж Quickpay. Якщо це замовлення було закрито без оплати, покупця повертають на оформлення з повідомленням Ваше попереднє замовлення скасовано без оплати. Будь ласка, підтвердіть замовлення ще раз, щоб оплатити новим замовленням., а наступне Confirm Order оплачує нове замовлення. Якщо замовлення оформлення вже має статус, але кошик відтоді змінився, включно з новою кількістю, покупця повертають на оформлення, а новий кошик оплачується новим замовленням.

Якщо платіж не вдалося розпочати, покупець залишається на кроці Confirm Order з повідомленням The Quickpay payment could not be started. Please try again or choose another payment method. над кнопкою. Технічна причина записується в журнал. Якщо ключі відсутні, повідомлення таке: Quickpay is not available at the moment. Please choose another payment method.

Callback і повернення покупця також працюють, коли магазин у режимі обслуговування: OpenCart 3 пропускає запити розширень оплати, а на OpenCart 4 розширення додає для них власну дію запуску.

Розширення приймає лише разові платежі. Немає підписок і регулярних платежів, збережених карток і часткового захоплення, у Quickpay не передаються позиції кошика чи рахунку, і немає окремих способів MobilePay, Apple Pay або Klarna: покупець обирає серед способів вашого вікна оплати Quickpay.

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

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

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

"Payment accepted" або "Delivered (completed)" status: Quickpay підтвердив захоплений платіж з правильною сумою та валютою. Статус відповідає Order status after payment. Примітка показує номер платежу Quickpay (позначений TEST для тестових платежів).

"Quickpay payment on hold" status (типово Pending): платіж лише авторизовано і очікує Capture Quickpay payment; або Quickpay повідомив суму чи валюту, відмінні від суми замовлення (наприклад, у менеджері Quickpay захоплено іншу суму); або захоплення не вдалося, і сума лише зарезервована. Примітка пояснює це. Коли захоплено гроші з іншою сумою, розширення фіксує суму, захоплену Quickpay, і повернення можливі в межах цієї суми.

Cancelled status: платіж замовлення на утриманні було скасовано в менеджері Quickpay.

Refunded status: платіж повністю повернено через розширення.

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

Коли ви переводите неоплачене замовлення цього розширення в Cancelled status в History замовлення, його посилання на оплату видаляється в Quickpay. Скасування авторизованого замовлення автоматично не звільняє зарезервовану суму: примітка нагадує скасувати платіж у менеджері Quickpay; інакше резерв закінчується, коли спливає строк авторизації.

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

Вкладка VibeFox Quickpay Gateway

У Sales > Orders відкрийте замовлення, оплачене через Quickpay. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox Quickpay Gateway показує Payment ID з позначкою Test payment для тестових платежів, Status платежу, Amount / refunded, список усіх платежів Quickpay замовлення (якщо їх більше одного), кнопку захоплення, форму повернення, історію повернень і Quickpay notes замовлення. Вкладка показується користувачам, які мають доступ до розширення. Захоплення та повернення потребують права змінювати розширення (налаштовується в System > Users > User Groups).

Захоплення

За Authorize only натисніть Capture Quickpay payment на вкладці та підтвердьте Capture the order total through Quickpay? Захоплюється вся сума замовлення; часткове захоплення недоступне. Якщо Quickpay підтверджує одразу, замовлення переходить у оплачений статус із Order status after payment без повідомлення покупця і без зміни залишків, як при ручній зміні статусу. Інакше примітка повідомляє, що захоплення запитано, а замовлення позначається оплаченим, коли callback Quickpay це підтвердить. Відхилене захоплення показується на вкладці та записується в примітку до замовлення.

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

На вкладці введіть Amount (сума, яку ще не повернуто, заповнюється автоматично), за бажанням Reason (optional), і натисніть Refund via Quickpay. Підтвердьте запитання Refund this amount through Quickpay? This cannot be undone. Для захоплених платежів підтримуються повні та часткові повернення. Повернення виконуються в сумі та валюті, які захопив Quickpay, а не в сумі замовлення. Quickpay обробляє повернення асинхронно: в історії повернень з’являється requested, а callback переводить його в confirmed або failed і додає результат до приміток. Невдале повернення не вважається поверненим. Якщо Quickpay відхиляє повернення одразу, вкладка показує помилку, і повернення не реєструється. Повне повернення переводить замовлення в Refunded status без повідомлення покупця і без повернення товарів на склад; часткове повернення статус не змінює. Авторизований платіж, який так і не захоплено, повернути не можна; скасуйте його в менеджері Quickpay.

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

Повернення, зроблені безпосередньо в менеджері Quickpay, лише додаються до приміток. Статус замовлення автоматично не змінюється. За потреби оновіть його вручну.

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

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

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

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

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

Quickpay не з’являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і збережено і API key, і Private key. Без обох ключів спосіб оплати приховується, а на сторінці налаштувань з’являється попередження. Також перевірте, що платіжна адреса входить до вибраної Geo Zone, і що замовлення досягає Total, вказаного в налаштуваннях.

Платіж пройшов, але замовлення залишається без статусу: callback Quickpay не дійшов до вашого магазину або був відхилений. Перевірте, що ваш магазин доступний з інтернету (без захисту паролем), і що Private key — приватний ключ того самого облікового запису Quickpay. Відхилені callback-запити завжди записуються в журнал на сторінці розширення. Увімкніть Debug log, щоб бачити кожен callback.

Журнал показує Callback rejected: invalid checksum.: приватний ключ у налаштуваннях не належить обліковому запису, який надіслав callback. Скопіюйте його знову з Settings > Integration у менеджері Quickpay.

Журнал показує Callback rejected: the private key is not configured.: введіть приватний ключ. Callback-запити без нього ніколи не приймаються.

Журнал показує Callback: no order found for payment …: callback стосується платежу Quickpay, який цей магазин не створював, наприклад платежу, зробленого поза OpenCart.

Журнал показує, що кошик заблоковано іншим запитом: інший callback цього самого кошика саме застосовувався. Callback отримує помилку, тож Quickpay надішле його знову.

Тестовий платіж не позначив замовлення оплаченим: Test payments вимкнено. Журнал і примітка до замовлення вказують, що тестовий платіж не прийнято. Увімкніть налаштування під час тестування та вимкніть, коли ваш обліковий запис перейде в робочий режим.

Замовлення в статусі утримання після оплати: прочитайте примітки на вкладці VibeFox Quickpay Gateway. Платіж може бути лише авторизований і очікувати Capture Quickpay payment, захоплена сума або валюта можуть не збігатися із замовленням, або захоплення не вдалося. Захопіть платіж, опрацюйте замовлення або поверніть платіж.

Test API key повідомляє Quickpay rejected the API key.: ключ невірний або належить користувачу без доступу до API. Скопіюйте ключ API користувача API з менеджера Quickpay.

Покупець бачить The Quickpay payment could not be started.: перегляньте поле Log на сторінці розширення. Там показано помилку Quickpay, наприклад валюту, яку ваш обліковий запис Quickpay не приймає.

Повернення не виконується: замовлення має мати захоплений платіж Quickpay. Повідомлення The Quickpay payment of this order has not been captured — there is nothing to refund. означає, що платіж лише авторизовано; захопіть його або скасуйте в менеджері Quickpay. Invalid refund amount: at most … означає, що сума перевищує залишок захопленого платежу.

Для розробників: перед створенням посилання на оплату розширення викликає подію OpenCart qpg_quickpay_link_data з параметрами посилання та замовленням.

Видалення

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

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

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