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

Вимоги

WordPress: 5.8 або новіший.

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

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

Валюта: замовлення має бути у валюті, яку приймає Paystack: NGN, USD, GHS, ZAR, KES, XOF, EGP або RWF, як увімкнено у вашому обліковому записі Paystack. В інших валютах спосіб оплати приховується. У XOF і RWF Paystack приймає лише цілі суми.

Обліковий запис Paystack: потрібні секретні ключі вашого облікового запису Paystack: тестовий секретний ключ (sk_test_...) та/або робочий секретний ключ (sk_live_...). Публічні ключі (pk_...) не потрібні, бо оплата відбувається на захищеній сторінці Paystack. У панелі Paystack також вказується URL webhook вашого магазину (див. розділ «Налаштування»). Ваш сайт має бути доступним з інтернету, щоб отримувати webhook-повідомлення.

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

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

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

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

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

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

5. Вставте секретні ключі з панелі Paystack і вкажіть URL webhook у панелі Paystack (див. розділ «Налаштування»).

6. Увімкніть Enable/Disable і збережіть. Залиште Test Mode увімкненим, доки не здійсните тестовий платіж, а потім вимкніть його, щоб приймати реальні платежі.

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

Усі налаштування розміщені на одній сторінці: WooCommerce > Settings > Payments > Paystack. Над полями блок статусу показує режим: Тестовий режим: реальні кошти не списуються. або Робочий режим: приймаються реальні платежі. Він також попереджає, коли секретний ключ поточного режиму порожній, коли публічний ключ (pk_...) введено в поле секретного ключа, коли в робочому режимі вказано тестовий ключ (sk_test_...) або в тестовому режимі робочий ключ (sk_live_...), а також коли Paystack не приймає валюту вашого магазину. Поки існує проблема з ключем, спосіб оплати приховано на оформленні замовлення. У списку способів оплати Paystack позначається як такий, що потребує налаштування, доки для поточного режиму не задано секретний ключ.

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

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

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

Description: текст під способом оплати на оформленні замовлення. За замовчуванням: Pay securely using your debit card, credit card, or bank account via Paystack.

API-ключі

Скопіюйте секретні ключі з панелі Paystack, сторінка Settings > API Keys & Webhooks. У розділі є посилання на неї.

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

Test Secret Key: ваш тестовий секретний ключ Paystack. Починається з sk_test_.

Live Secret Key: ваш робочий секретний ключ Paystack. Починається з sk_live_.

Webhook

Webhook повідомляє вашому магазину, що платіж здійснено, навіть якщо покупець не повернувся до магазину. У панелі Paystack, на сторінці Settings > API Keys & Webhooks, вкажіть URL із цього розділу як у полі Test Webhook URL, так і в полі Live Webhook URL. Він має такий вигляд: https://your-site/wc-api/paystack_p_webhook/. Скопіюйте URL точно так, як його показано в налаштуваннях.

Paystack підписує кожне webhook-повідомлення вашим секретним ключем, тож більше нічого налаштовувати не потрібно. Тестові webhook-повідомлення перевіряються тестовим секретним ключем, робочі — робочим секретним ключем. Webhook-повідомлення без дійсного підпису відхиляються. Плагін використовує подію charge.success:

На інші події відповідається OK, і вони ігноруються. Без webhook замовлення підтверджується лише тоді, коли покупець повертається до магазину після оплати. Банківські перекази та платежі USSD, які завершуються пізніше, підтверджуються лише webhook-повідомленням.

Замовлення

Autocomplete Order: Automatically mark orders as completed after successful payment. Якщо опцію увімкнено, оплачені замовлення переходять у статус «Виконано» замість «В обробці», з однією зміною статусу та одним листом покупцю. За замовчуванням: вимкнено.

Додатково

Debug log: Log Paystack events and API calls for debugging записує подробиці до WooCommerce > Status > Logs, джерело wcp_paystack_payment. Помилки записуються завжди. Ключі та дані покупців ніколи не записуються в журнал. За замовчуванням: вимкнено.

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

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

Покупець обирає спосіб оплати (за замовчуванням Paystack) і оформлює замовлення. У тестовому режимі на оформленні замовлення відображається ТЕСТОВИЙ РЕЖИМ УВІМКНЕНО. Реальних списань не буде. Плагін створює транзакцію Paystack на суму замовлення у валюті замовлення з поштовою адресою для рахунку та надсилає покупця на захищену сторінку оплати Paystack. Там покупець оплачує одним із каналів, увімкнених у вашому обліковому записі Paystack.

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

Якщо покупець скасовує оплату на сторінці Paystack або залишає її без оплати, замовлення продовжує очікувати оплати. Покупець повертається на оформлення замовлення або на сторінку Pay for order з повідомленням, наприклад Оплату скасовано. Ви можете спробувати ще раз або обрати інший спосіб оплати., Оплату не завершено. Ви можете спробувати ще раз або обрати інший спосіб оплати. або Ваш платіж відхилено. Ви можете спробувати ще раз або обрати інший спосіб оплати. Покупець може оплатити те саме замовлення знову. Попередня сторінка оплати замовлення залишається чинною: якщо платіж за нею пройде пізніше, його все одно буде прийнято.

Сторінка отриманого замовлення відкривається лише для покупця цього замовлення: за підписаним посиланням повернення, у сесії оформлення, яка створила замовлення, або в обліковому записі покупця. Усіх інших перенаправляють на оформлення замовлення з нейтральним повідомленням, і сторінка замовлення не показується.

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

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

Плагін не має вбудованої або спливаючої платіжної форми, збережених карток, підписок, розподілених платежів чи субрахунків і не пропонує вибір платіжних каналів у WooCommerce.

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

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

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

Processing or Completed: платіж підтверджено. Статус «Виконано», якщо увімкнено Autocomplete Order. У примітці до замовлення вказано суму, посилання Paystack, номер транзакції, режим (тестовий або робочий), платіжний канал, тип картки та останні цифри для платежів карткою, а також комісії Paystack, сплачені покупцем. Ідентифікатор транзакції замовлення — це посилання Paystack (order_...).

On hold: сплачені сума або валюта не збігаються із замовленням (примітка Paystack amount or currency mismatch), або платіж надійшов після скасування замовлення. У примітці до замовлення пояснюється, що потрібно перевірити. Виконайте замовлення або поверніть кошти.

Failed: Paystack повідомляє, що остання спроба оплати замовлення в очікуванні завершилася невдачею або була відкликана. Невдача більш ранньої спроби не змінює замовлення. Покупець може оплатити знову.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Paystack. Підтримуються повні та часткові повернення. Кнопка повернення пропонується лише для замовлень, оплачених через перевірену транзакцію Paystack. Повернення надсилається на транзакцію, якою сплачено замовлення, із секретним ключем режиму (тестового або робочого), у якому її було проведено, тож цей ключ має бути заданий. У XOF і RWF повернення мають бути цілими сумами. Paystack ставить повернення в чергу: примітка до замовлення показує статус, який повертає Paystack, наприклад pending, та ідентифікатор повернення. Якщо Paystack не приймає повернення, WooCommerce показує Paystack refund failed: з причиною, і повернення не реєструється.

Повернення, оформлені в панелі Paystack, а також остаточний статус повернень, які Paystack поставив у чергу, не синхронізуються з WooCommerce. За потреби зафіксуйте їх вручну.

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

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

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

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

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

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

Paystack не з’являється на оформленні замовлення: перевірте, що ліцензія активна, що Enable/Disable увімкнено, що для поточного режиму задано правильний секретний ключ (Test Secret Key з sk_test_... у тестовому режимі, Live Secret Key з sk_live_... у робочому режимі) і що валюта замовлення підтримується Paystack. Блок статусу вгорі налаштувань вказує на проблему.

Платіж пройшов, але замовлення залишається у статусі Pending payment: webhook не дійшов до магазину, а покупець не повернувся. У панелі Paystack перевірте, що Test Webhook URL і Live Webhook URL збігаються з URL із налаштувань, і що жоден режим обслуговування, файрвол чи захист паролем його не блокує. Перегляньте WooCommerce > Status > Logs, джерело wcp_paystack_payment, на наявність відхилених webhook-повідомлень.

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

Webhook відповідає Secret key not configured: жодного секретного ключа не задано. Введіть секретні ключі в налаштуваннях.

Webhook відповідає Verification failed або Busy, retry later: транзакцію в цей момент не вдалося зчитати через API Paystack, або замовлення в цей час оновлювалося поверненням покупця. Замовлення не змінюється, і Paystack надішле webhook повторно.

Webhook відповідає OK - unknown reference: платіж стосувався не замовлення цього магазину, наприклад сторінки оплати Paystack або іншої інтеграції в тому самому обліковому записі. Його ігнорують.

Покупець бачить Payment gateway is not properly configured: секретний ключ поточного режиму відсутній або неправильний. Виправте його, дотримуючись блоку статусу вгорі налаштувань.

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

Повернення не виконується з повідомленням про режим: платіж було проведено в тестовому або робочому режимі, а секретний ключ цього режиму не налаштовано. Введіть його й повторіть спробу. Повідомлення No verified Paystack payment was found for this order означає, що замовлення не було сплачено через перевірену транзакцію Paystack. Оформіть повернення в панелі Paystack.

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

Видалення

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

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