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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: кошик має бути у валюті, яку приймає 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. В адмін-панелі перейдіть до Modules > Module Manager і натисніть Upload a module. Виберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox Paystack Payment у списку модулів і натисніть Configure.

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

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

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

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

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

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox Paystack Payment > Configure. Кожен розділ із полями має власну кнопку Save, яка зберігає всю сторінку. Над полями вікно статусу показує режим: Тестовий режим: реальні кошти не списуються. або Робочий режим: приймаються реальні платежі. Воно також попереджає, коли секретний ключ поточного режиму порожній, коли в поле секретного ключа введено публічний ключ (pk_...), коли в робочому режимі стоїть тестовий ключ (sk_test_...) або в тестовому режимі — робочий ключ (sk_live_...), і коли Paystack не приймає валюту за замовчуванням вашого магазину. Доки існує проблема з ключем, спосіб оплати приховано в оформленні замовлення.

Paystack

Перший розділ має назву Paystack і позначку TEST або LIVE поточного режиму.

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: використовує тестовий секретний ключ для нових платежів, і реальні кошти не списуються. Вимкніть його, щоб приймати справжні платежі з робочим секретним ключем. Платежі, здійснені в іншому режимі, для перевірки та повернень і далі використовують ключ свого режиму. За замовчуванням: увімкнено. Поки він увімкнений, покупці бачать під способом оплати напис ТЕСТОВИЙ РЕЖИМ УВІМКНЕНО. Реальні списання не здійснюватимуться.

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

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

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

Clear saved secrets: позначте ключ і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Webhook

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

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

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

Замовлення

Autocomplete Order: якщо увімкнено, оплачені замовлення отримують статус Delivered замість Payment accepted, однією зміною статусу. За замовчуванням: вимкнено.

Додатково

Debug log: записує події Paystack і виклики API в logs/paystack_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки та попередження записуються завжди. Ключі та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Paystack) і підтверджує замовлення. Модуль запускає транзакцію Paystack на суму кошика у валюті кошика з e-mail покупця та надсилає покупця на розміщену сторінку оплати Paystack. Там покупець сплачує одним із каналів, увімкнених у вашому обліковому записі Paystack. На платіжній сторінці показано номер кошика та ім'я покупця. На цьому етапі замовлення ще не існує.

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

Якщо платіж ще обробляється, наприклад банківський переказ, замовлення створюється в статусі Awaiting Paystack payment під час повернення покупця, а сторінка підтвердження показує Ваш платіж підтверджується Paystack. Ви отримаєте листа, щойно його буде підтверджено. Webhook завершує замовлення пізніше. Якщо Paystack недоступний під час повернення покупця, сторінка Payment confirmation просить покупця не платити повторно та пропонує Check again і Back to checkout; webhook створює замовлення, щойно він надійде. Для замовлення на утриманні сторінка підтвердження показує Ваш платіж отримано, і замовлення перевіряється. Ми зв'яжемося з вами, якщо щось знадобиться.

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

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

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

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

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

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

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

Замовлення ще немає: покупця надіслано до Paystack, і він не сплатив, покинув сторінку Paystack або Paystack ще не підтвердив платіж. Існує лише кошик.

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

Payment accepted або Delivered: платіж підтверджено. Статус — Доставлено, якщо увімкнено Autocomplete Order. Платіж записується з посиланням Paystack (pscart_...) як ідентифікатор транзакції. Примітка показує суму, посилання, номер транзакції, режим (тестовий або робочий), канал оплати, тип картки та останні цифри для платежів карткою, а також комісії Paystack, сплачені покупцем, якщо вони були.

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

Помилка оплати: Paystack повідомляє, що остання спроба оплати замовлення в статусі Awaiting Paystack payment завершилася помилкою або була скасована. Помилка давнішої спроби не змінює замовлення.

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

Блок Paystack payment

Сторінка замовлення показує блок Paystack payment з посиланням, ідентифікатором транзакції, режимом із позначкою Test mode для тестових платежів, статусом платежу, каналом і карткою, датою платежу, сплаченими та поверненими сумами, історією повернень і Payment notes замовлення.

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

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

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

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

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

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

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

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

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

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

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

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

Платіж пройшов, але замовлення не створено: webhook не дійшов до вашого магазину, а покупець не повернувся. У панелі Paystack перевірте, що Test Webhook URL і Live Webhook URL точно збігаються з URL, показаним у Webhook URL, і що їх не блокує брандмауер або захист паролем. Увімкніть Debug log і перегляньте поле Log на наявність відхилених webhook-повідомлень.

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

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

Webhook відповідає Verification failed, Busy, retry later або Order could not be created, retry later: транзакцію не вдалося зчитати через API Paystack у цей момент, кошик у цей самий час оброблявся під час повернення покупця, або замовлення не вдалося створити (наприклад, тому що модуль вимкнено). Paystack надішле webhook повторно. Журнал показує причину.

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

URL webhook у браузері показує Empty body: це нормально. URL приймає лише запити від Paystack.

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

Замовлення має статус Paystack payment on hold після оплати: прочитайте примітки про оплату в блоці Paystack payment (див. Статуси замовлення), потім виконайте замовлення або поверніть кошти за платіж.

Замовлення залишається в статусі Awaiting Paystack payment: Paystack ще не підтвердив платіж. Перевірте транзакцію в панелі Paystack і налаштування webhook. Якщо покупець так і не завершив оплату, змініть статус вручну.

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

Розробники можуть змінити запит транзакції та список валют за допомогою хуків модуля actionWcpPaystackPaymentRequest, actionWcpPaystackSupportedCurrencies і actionWcpPaystackCurrencyDecimals.

Видалення

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

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