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

Вимоги

PrestaShop: 8.0 – 9.x.

PHP: 8.0 або новіша версія. Модуль не встановлюється на старіших версіях PHP.

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

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

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

1. У back office перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Quickpay Gateway у списку модулів і натисніть Configure.

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

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

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

Під час встановлення модуль створює один статус замовлення: Quickpay payment on hold. PrestaShop вмикає новий платіжний модуль для всіх валют, країн і груп клієнтів. Модуль прив'язується до країн, які активні на момент встановлення. Змінити їх усі можна в Payment > Preferences.

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

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox Quickpay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Поки не збережено API-ключ і приватний ключ, сторінка показує Quickpay потребує налаштування: введіть API-ключ і приватний ключ. Поки обидва не збережено, спосіб оплати прихований під час оформлення замовлення. Поки увімкнено Test payments, сторінка нагадує вимкнути його, коли ваш обліковий запис Quickpay перейде в робочий режим.

Quickpay

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

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

Description: текст під способом оплати під час оформлення замовлення. За замовчуванням: Pay securely by card or MobilePay on the Quickpay payment page.

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

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

Callback URL: показує URL зворотного виклику вашого магазину. За зрозумілих URL він має такий вигляд: https://your-shop/module/wcp_quickpay_gateway/callback. Quickpay викликає його після кожної операції з платежем (авторизація, захоплення, повернення, скасування). Він надсилається з кожним платежем автоматично, тож у Quickpay нічого налаштовувати не потрібно.

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

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

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

Очищення збережених секретів: позначте API key або Private key і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Test payments: приймає платежі, зроблені тестовими картками Quickpay. Окремої пісочниці в Quickpay немає: поки обліковий запис Quickpay у тестовому режимі, платежі проводяться тестовими картками й позначаються як тестові. Вмикайте цей параметр лише під час тестування. Коли він вимкнений, тестовий платіж ніколи не позначає замовлення оплаченим. Коли він увімкнений, під час оформлення замовлення під способом оплати показується Тестовий режим: приймаються тестові картки Quickpay. За замовчуванням: вимкнено.

Test API key: ця кнопка перевіряє ключ, введений у поле API key (або збережений, якщо поле порожнє), запитом до Quickpay з автентифікацією, без збереження ключа. Відповіді: Підключення успішне — API-ключ дійсний., Quickpay відхилив API-ключ., API-ключ не налаштовано. або Не вдалося підключитися: і причина.

Оплата

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

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

Додатково

Debug log: пише у logs/qpg_debug.log.php у папці модуля. Файл не можна відкрити з веб. Помилки й попередження, як-от відхилені зворотні виклики та помилки API Quickpay, завжди записуються. Увімкніть цей параметр, щоб також записувати деталі кожного запиту й зворотного виклику. API-ключі, дані карток і дані покупців ніколи не записуються. За замовчуванням: вимкнено.

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

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

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

На кроці оплати покупець обирає спосіб оплати (за замовчуванням Quickpay, із значком картки) і підтверджує вибір. Модуль створює платіж Quickpay для кошика у валюті кошика та посилання на оплату на суму кошика, після чого надсилає покупця до вікна оплати Quickpay. На цьому етапі замовлення ще немає. Покупець платить у цьому вікні одним зі способів, увімкнених у вашому вікні оплати Quickpay. E-mail покупця передається до Quickpay. Вікно оплати відкривається мовою покупця, якщо Quickpay її пропонує (данська, німецька, англійська, іспанська, фінська, французька, італійська, нідерландська, норвезька, польська, шведська), інакше — англійською.

Після оплати покупець повертається до вашого магазину. Саме повернення нічого не позначає як оплачене. Замовлення позначається оплаченим лише після підтвердження Quickpay: підписаний зворотний виклик створює замовлення, щойно захоплена сума й валюта збігаються з кошиком. Далі покупець бачить стандартну сторінку підтвердження замовлення. За Authorize only замовлення створюється у статусі Quickpay payment on hold, а платіж ви захоплюєте пізніше. Якщо зворотний виклик ще не надійшов, коли покупець повернувся, сторінка Payment confirmation показує повідомлення Ваш платіж підтверджується Quickpay. Ви отримаєте лист, щойно замовлення буде підтверджено. з кнопками Check again і Back to checkout.

Якщо покупець скасовує оплату у вікні оплати, посилання на оплату видаляється в Quickpay, а покупець повертається до оформлення замовлення з повідомленням Оплату скасовано. Ви можете спробувати ще раз або обрати інший спосіб оплати. Якщо картку відхилено, повідомлення: Оплату не завершено. Ви можете спробувати ще раз або обрати інший спосіб оплати. Кошик зберігається. Нова спроба повторно використовує платіж Quickpay кошика з новим посиланням, тож старе посилання ніколи не можна оплатити паралельно. Поки платіж за кошиком авторизований і чекає на захоплення, другий платіж не розпочинається; покупець бачить сторінку Payment confirmation.

Якщо оплату не вдається розпочати, покупець залишається на оформленні замовлення з повідомленням Не вдалося розпочати оплату Quickpay. Спробуйте ще раз або оберіть інший спосіб оплати. Технічна причина записується до журналу. Якщо ключів немає, повідомлення: Quickpay зараз недоступний. Оберіть інший спосіб оплати.

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

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

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

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

No order yet: покупця було перенаправлено до Quickpay, і він не сплатив, картку відхилено або платіж авторизовано й чекає на автоматичне захоплення. Існує лише кошик.

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

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

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

Refunded: платіж повністю повернено через модуль.

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

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

Блок Quickpay

Сторінка замовлення показує блок Quickpay payment з ID платежу, статусом платежу, сумою та сумою повернення, значок Test payment для тестових платежів, список усіх платежів Quickpay кошика (якщо їх більше одного), історію повернень і Quickpay notes замовлення. Для захоплення та повернень потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен.

Захоплення

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

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

У блоці Quickpay введіть суму (передзаповнюється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via Quickpay. Підтвердьте запитання Повернути цю суму через Quickpay? Цю дію не можна скасувати. Повні та часткові повернення підтримуються для захоплених платежів. Повернення виконуються в сумі та валюті, які захопив Quickpay, тож після розбіжності суми чи валюти ви можете повернути не більше того, що покупець реально заплатив, а не суму замовлення. Quickpay обробляє повернення асинхронно: в історії повернень з'являється requested, а зворотний виклик переводить його в confirmed або failed і додає результат до приміток. Якщо Quickpay одразу відхиляє повернення, блок показує помилку, і повернення не записується. Повне повернення переводить замовлення у статус Refunded; часткове повернення статус не змінює. Авторизований платіж, який ніколи не захоплювали, повернути не можна; скасуйте його в менеджері Quickpay.

Модуль не створює credit slips. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Quickpay.

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

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Quickpay Gateway — перший блок на сторінці Modules > Module Manager > VibeFox Quickpay Gateway > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен), а також кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-payment-quickpay і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену в обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль працює за останнім відомим статусом.

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

Без активного ключа Quickpay не показується покупцям під час оформлення замовлення. Якщо платіж все одно розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли в адмін-панель, тому спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але не можна протестувати під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: вже розпочаті платежі й далі підтверджуються, а захоплення та повернення працюють.

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

Вирішення проблем

Quickpay не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, а API key і Private key збережено. Без обох ключів спосіб оплати прихований. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

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

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

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

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

Журнал показує Could not lock the cart або Cannot create the order: саме в цей момент застосовувався інший зворотний виклик того самого кошика, або замовлення не вдалося створити (наприклад, модуль вимкнено). Зворотний виклик отримує відповідь з помилкою, тому Quickpay надішле його знову.

Тестовий платіж не позначив замовлення оплаченим: Test payments вимкнено. У журналі (і в примітці, якщо замовлення існує) написано, що тестовий платіж не прийнято. Вмикайте налаштування під час тестів і вимикайте, коли обліковий запис перейде в робочий режим.

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

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

Покупець бачить «Не вдалося розпочати оплату Quickpay.»: подивіться поле Log на сторінці модуля. Там показано помилку Quickpay, наприклад валюту, яку ваш обліковий запис Quickpay не приймає.

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

Розробники можуть змінювати параметри посилання на оплату Quickpay через хук actionQpgQuickpayLinkData.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Quickpay Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data увімкнено, налаштування шлюзу та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Платежі Quickpay, повернення та статус замовлення Quickpay payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають примітки про оплату та ID транзакцій.

Quickpay є торговою маркою відповідного власника. Цей модуль не пов'язаний з Quickpay і не схвалений Quickpay.