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 и задайте webhook URL в панели 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_...) как ID транзакции. Примечание показывает сумму, референс, номер транзакции, режим (тестовый или боевой), канал оплаты, тип карты и последние цифры для оплаты картой, а также комиссии Paystack, если они были оплачены покупателем.

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

Ошибка оплаты: Paystack сообщает, что последняя попытка оплаты заказа в статусе Awaiting Paystack payment завершилась ошибкой или была отменена. Ошибка более ранней попытки не меняет заказ.

Если приходит второй платёж по корзине, заказ которой уже оплачен, заказ не меняется. Примечание просит вас вернуть повторный платёж в панели Paystack. Платёж, который приходит для заказа в другом статусе, например Отправлен, только отмечается в заказе.

Блок Paystack payment

На странице заказа есть блок Paystack payment с референсом, ID транзакции, режимом со значком Test mode для тестовых платежей, статусом платежа, каналом и картой, датой платежа, оплаченными и возвращёнными суммами, историей возвратов и Payment notes заказа.

Возвраты

В блоке Paystack payment введите сумму (подставляется сумма, которая ещё не возвращена), при желании причину, и нажмите Refund via Paystack. Подтвердите вопрос Вернуть эту сумму через Paystack? Это действие нельзя отменить. Поддерживаются полные и частичные возвраты. Нужно право редактировать заказы; доступ к страницам модулей не требуется. Возврат отправляется на транзакцию, которой был оплачен заказ, с секретным ключом того режима (тестового или боевого), в котором она проходила, поэтому этот ключ должен быть настроен. Возвраты делаются на ту сумму и в той валюте, которые списал Paystack, поэтому для заказа на удержании после расхождения суммы или валюты можно вернуть не больше того, что покупатель фактически оплатил, а не сумму заказа. В XOF и RWF возвраты должны быть целыми суммами. Paystack ставит возвраты в очередь: примечание и история возвратов показывают статус, который вернул Paystack, например pending, и ID возврата. Если 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 всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

Paystack — товарный знак его правообладателя. Этот модуль не аффилирован с Paystack и не одобрен Paystack.