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

Вимоги

WordPress: 6.2 або новіша версія.

WooCommerce: 7.1 або новіша, встановлений та активний. Плагін не активується без нього.

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

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку wcp_quickpay_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Quickpay > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки та натисніть Activate.

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

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

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

Усі параметри розташовані на одній сторінці: WooCommerce > Settings > Payments > Quickpay. Доки не введено API-ключ і приватний ключ, Quickpay у списку способів оплати позначається як такий, що потребує налаштування, і приховується на оформленні замовлення, бо платіж неможливо ні створити, ні підтвердити.

Загальні

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

Title: назва способу оплати, яку бачать покупці на оформленні замовлення. За замовчуванням: Quickpay.

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

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

У панелі Quickpay (manage.quickpay.net) відкрийте Settings > Integration. Скопіюйте API-ключ користувача API (Settings > Users) і приватний ключ облікового запису. У розділі також показано URL зворотного виклику вашого магазину, який має вигляд https://your-site/wc-api/qpg_quickpay/. Він надсилається автоматично з кожним платежем, тож у Quickpay нічого налаштовувати не потрібно.

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

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

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

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

Оплата

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

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

Додатково

Debug log: Enable logging. Журнал знаходиться в WooCommerce > Status > Logs, джерело wcp_quickpay_gateway. Помилки та попередження, як-от відхилені зворотні виклики та помилки API Quickpay, записуються завжди. Увімкніть, щоб записувати також кожен запит і зворотний виклик. API-ключі, дані картки та дані покупця ніколи не записуються в журнал. За замовчуванням: вимкнено.

Delete data: Delete the gateway settings and logs when the plugin is deleted. Деактивація плагіна нічого не видаляє. Дані замовлень (ідентифікатори платежів Quickpay, примітки) завжди зберігаються. За замовчуванням: вимкнено.

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

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

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

Якщо покупець скасовує оплату у вікні Quickpay під час оформлення замовлення, неоплачене замовлення скасовується стандартним способом WooCommerce, а кошик відновлюється. На сторінці Pay for order скасування повертає покупця на цю сторінку, тож замовлення лишається доступним для оплати. Невдалий або скасований платіж можна повторити: нова спроба повторно використовує платіж Quickpay замовлення з новим посиланням, тож старе посилання ніколи не можна оплатити паралельно. Коли неоплачене замовлення скасовується, його посилання на оплату видаляється в Quickpay.

Якщо платіж не вдається розпочати, покупець бачить 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.

Спосіб оплати працює на класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

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

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

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

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

Processing or Completed: Quickpay підтвердив захоплений платіж із правильною сумою та валютою. Статус відповідає Order status after payment. У примітці до замовлення показано ідентифікатор платежу Quickpay (позначений TEST для тестових платежів), і він зберігається як ідентифікатор транзакції замовлення.

On hold: платіж лише авторизовано й очікує Capture Quickpay payment; або Quickpay повідомив суму чи валюту, відмінні від суми замовлення (наприклад, замовлення було змінено після початку оплати або в панелі Quickpay захоплено іншу суму); або захоплення не вдалося, і сума досі лише зарезервована. Примітка до замовлення пояснює це, також коли замовлення вже було «На утриманні».

Failed: спробу оплати відхилено. Покупець може оплатити знову.

Cancelled: покупець скасував оплату у вікні Quickpay, замовлення скасували ви або тайм-аут резервування запасів WooCommerce, або платіж скасовано в панелі Quickpay.

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

Захоплення

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

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

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Quickpay. Повні та часткові повернення підтримуються для захоплених платежів. Quickpay обробляє повернення асинхронно: примітка повідомляє, що повернення запитано, а зворотний виклик додає остаточний результат, confirmed або FAILED з причиною. Якщо Quickpay одразу відхиляє повернення, WooCommerce показує помилку, і повернення не фіксується. Авторизований платіж, який ніколи не захоплювали, повернути не можна; скасуйте його в панелі Quickpay.

Платежі та повернення, зроблені безпосередньо в панелі Quickpay, лише відзначаються в замовленні. Вони автоматично не фіксуються як повернення WooCommerce. За потреби створіть ручне повернення в WooCommerce без Refund via Quickpay.

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі WooCommerce > Settings > Payments > Quickpay. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, та ваш домен. Використовуйте Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб вилучити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

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

Коли ліцензія спливає, плагін продовжує працювати, але оновлення та підтримка потребують продовження. Статус автоматично перевіряється у фоновому режимі.

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

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

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

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

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

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

Журнал показує Callback: order #… is locked by another request.: інший зворотний виклик цього самого замовлення якраз застосовувався. Зворотний виклик отримує відповідь з помилкою, тому не вважається обробленим. Якщо замовлення лишається без змін, перевірте платіж у панелі Quickpay.

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

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

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

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

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

Блок ліцензії показує помилку: дотримуйтесь повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі vibefox.net і натисніть Check now. Якщо адресу сайту змінено, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу та журнали плагіна (файли журналів, зокрема ротовані, і записи журналу в базі даних) видаляються лише якщо було увімкнено Delete data. Інакше вони зберігаються для повторного встановлення. Існуючі замовлення зберігають свої примітки про оплату та ідентифікатори транзакцій.

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