VibeFox Pesapal for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: корзина должна быть в KES, UGX, TZS, ZMW, RWF или USD. В других валютах способ оплаты скрыт на этапе оформления заказа. Корзина оплачивается в собственной валюте; модуль не конвертирует валюты. Суммы передаются в основных единицах валюты, округлённых до её точности (для UGX и RWF без десятичных знаков).

Учётная запись Pesapal: нужны ключ и секрет потребителя учётной записи мерчанта Pesapal. Ключи для тестовой и рабочей среды различаются. Ключи для тестовой среды (sandbox) берутся из демонстрационной учётной записи мерчанта на cybqa.pesapal.com (Pesapal также публикует демонстрационные ключи на своём портале разработчиков). Рабочие ключи берутся в вашей панели мерчанта Pesapal. Больше ничего в панели Pesapal настраивать не нужно: модуль сам регистрирует свой URL для уведомлений. Ваш магазин должен быть доступен из интернета, потому что Pesapal отправляет ему уведомления о платежах.

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

Установка

1. В панели администрирования откройте Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. После окончания загрузки нажмите Configure или позже найдите VibeFox Pesapal Pay Gateway в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии в верхней части страницы Configure и нажмите Activate (см. Лицензионный ключ).

4. Введите ключ и секрет потребителя для тестовой среды, включите Enable/Disable, нажмите Save и оформите тестовый заказ.

5. Введите ключ и секрет потребителя для рабочей среды, выключите Sandbox mode и нажмите Save, чтобы принимать реальные платежи.

При установке модуль создаёт статус заказа Pesapal payment on hold. PrestaShop включает новый платёжный модуль для всех валют, стран и групп клиентов. Ограничить это можно в разделе Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями бейдж показывает режим: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. или LIVE — Real payments on pay.pesapal.com. Предупреждение появляется, когда не заполнены ключи текущего режима (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout. или то же для рабочей среды), а также когда Pesapal не поддерживает валюту магазина по умолчанию.

Pesapal

Enable/Disable: Enable Pesapal включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель на этапе оформления заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Pesapal (M-Pesa, Airtel Money, cards). Обязательное поле: пустое название не сохраняется, остаётся прежнее.

Description: текст под способом оплаты на этапе оформления заказа. По умолчанию: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

Учётные данные API

В этом разделе объясняется, где взять ключи, и есть ссылки на cybqa.pesapal.com и pesapal.com. Введите ключи для тестовой и рабочей среды, каждый в своё поле.

Sandbox mode: Use the Pesapal sandbox (no real money). Когда включено, новые платежи идут через cybqa.pesapal.com с ключами тестовой среды. Выключите, чтобы принимать реальные платежи на pay.pesapal.com с рабочими ключами. По умолчанию: включено.

Sandbox consumer key: ключ потребителя вашей демонстрационной учётной записи мерчанта для тестовой среды. Используется только в режиме sandbox.

Sandbox consumer secret: секрет потребителя вашей учётной записи мерчанта для тестовой среды. Используется только в режиме sandbox.

Live consumer key: ключ потребителя из вашей панели мерчанта Pesapal. Используется, когда режим sandbox выключен.

Live consumer secret: секрет потребителя из вашей панели мерчанта Pesapal. Используется, когда режим sandbox выключен.

Сохранённые ключи и секреты больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved consumer keys and secrets: отметьте флажок и нажмите Save, чтобы удалить все четыре сохранённых ключа и секрета.

Сохранение настроек удаляет кэшированные токены доступа Pesapal. Смена режима или ключей никогда не использует токен доступа или ID уведомления другого режима или других ключей. Платёж, начатый в одном режиме, всегда проверяется в этом режиме, даже после переключения.

Уведомления о платежах (IPN)

IPN URL: показывает URL уведомлений вашего магазина. С понятными URL он выглядит так: https://your-shop/module/wcp_pesapal_pay/webhook, возможно, с кодом языка, например /en/. URL автоматически регистрируется в Pesapal при первом платеже, отдельно для тестовой и рабочей среды и для каждой пары ключей, так что ничего настраивать не нужно. После первого платежа в разделе появляется Registered IPN ID: с ID, который вернул Pesapal; до этого там написано Not registered yet for the current mode and keys. URL должен быть доступен из интернета: без брандмауэра и парольной защиты перед ним. Он продолжает работать, когда магазин на обслуживании, и не блокируется ограничением по странам вашего магазина.

Дополнительно

Debug log: Log Pesapal requests and notifications. Записывает подробности в logs/pesapal_p_debug.log.php в папке модуля. Файл нельзя открыть из веба. Ошибки и предупреждения записываются всегда, даже когда переключатель выключен. Ключи, токены и данные покупателей не записываются никогда. По умолчанию: выключено.

Log: показывает размер журнала и его последние записи. Нажмите Clear log, чтобы очистить его.

Delete data: Delete the module settings and logs when the module is uninstalled. Данные Pesapal, сохранённые в заказах (идентификаторы отслеживания, примечания), относятся к истории платежей и всегда сохраняются. Отключение модуля ничего не удаляет. По умолчанию: выключено.

Оформление заказа

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Pesapal (M-Pesa, Airtel Money, cards)) и видит его описание. После подтверждения модуль создаёт запрос на платёж Pesapal на сумму корзины в валюте корзины с платёжными данными из адреса выставления счёта и отправляет покупателя на платёжную страницу Pesapal. Описание платежа, которое передаётся в Pesapal, — Cart, номер корзины и название магазина. Там покупатель платит одним из способов, которые предлагает Pesapal, например M-Pesa, Airtel Money, MTN, картой или банковским переводом. На этом этапе заказа ещё не существует.

Заказ отмечается как оплаченный только после подтверждения Pesapal. Уведомления Pesapal и возврат покупателя не содержат ни платёжных данных, ни подписи, поэтому модуль им не доверяет: для каждого из них он запрашивает статус транзакции у Pesapal аутентифицированным запросом между серверами, в том режиме, в котором был начат платёж. Кроме того, он проверяет, что транзакция принадлежит этой корзине и что оплаченные сумма и валюта совпадают с корзиной. После этого заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа.

Платежи через мобильные деньги могут занять некоторое время. Если Pesapal ещё не подтвердил платёж, когда покупатель возвращается, страница Payment confirmation показывает Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. с кнопками Check again и Back to checkout. Уведомление от Pesapal создаёт заказ, как только платёж подтверждён. Если заказ был переведён в статус ожидания, страница подтверждения показывает Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

Если покупатель отменяет платёж на странице Pesapal, он возвращается к оформлению заказа с сообщением The Pesapal payment was cancelled. You can try again or choose another payment method. Если платёж не прошёл, появляется сообщение The Pesapal payment was not successful. Please try again or choose another payment method. Корзина сохраняется, и покупатель может оплатить снова. Каждая попытка оплаты корзины запоминается, поэтому платёж, сделанный позже на более старой странице Pesapal этой корзины, тоже принимается.

Если Pesapal не может начать платёж, покупатель остаётся на этапе оформления заказа с коротким сообщением, например Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (неверные ключи) или Pesapal could not start the payment:, после которого идёт причина от Pesapal. Техническая причина записывается в журнал. Сумма заказа должна быть больше нуля.

В модуле нет платёжной формы на вашем сайте (покупатель всегда платит на странице Pesapal), нет сохранённых карт, подписок и регулярных платежей, а также конвертации валют.

Заказы и возвраты

Статусы заказа

Заказа ещё нет: покупатель был отправлен в Pesapal и не оплатил, платёж не прошёл или Pesapal ещё не подтвердил платёж. Существует только корзина.

Payment accepted: Pesapal сообщает, что платёж завершён, и сумма и валюта совпадают. Платёж записывается с идентификатором отслеживания Pesapal в качестве ID транзакции, а примечание показывает сумму, способ оплаты, код подтверждения Pesapal и идентификатор отслеживания. Каждый платёж применяется только один раз.

Pesapal payment on hold: оплаченные сумма или валюта отличаются от корзины (примечание Pesapal amount/currency mismatch — held for review), либо деньги поступили по заказу, который был отменён. Фактически оплаченная сумма записывается в заказ, если она в валюте заказа. Проверьте платёж в панели Pesapal, затем завершите заказ или верните платёж.

Refunded: Pesapal сообщает, что платёж, оплативший заказ, был отменён. Отмена другой попытки лишь отмечается в заказе.

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

Блок оплаты Pesapal

На странице заказа показан блок Pesapal payment с бейджем Sandbox или Live, идентификатором отслеживания, референсом мерчанта, статусом Pesapal, способом оплаты, кодом подтверждения, запрошенной и оплаченной суммой, причиной проверки, всеми Payment attempts корзины и Payment notes заказа. Блок предназначен только для чтения.

Возвраты

Модуль не отправляет возвраты в Pesapal. Верните платёж в панели Pesapal, а затем вручную зафиксируйте возврат в PrestaShop.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Pesapal Pay Gateway — это первый блок на странице Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-pesapal и ссылка 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.

Без активного ключа Pesapal не показывается покупателям на этапе оформления заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в административную панель, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его на этапе оформления заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а уведомления Pesapal о существующих платежах, включая отмены, по-прежнему применяются.

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

Устранение неполадок

Pesapal не появляется на этапе оформления заказа: проверьте, что лицензия активна, Enable/Disable включено, введены ключ и секрет потребителя текущего режима (Sandbox consumer key и Sandbox consumer secret в режиме sandbox, Live consumer key и Live consumer secret в рабочем режиме) и валюта корзины — KES, UGX, TZS, ZMW, RWF или USD. Предупреждения в верхней части настроек указывают на проблему. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя. Разработчики могут изменить список валют с помощью хука actionPesapalSupportedCurrencies.

Платёж прошёл, но заказ не создан: уведомление от Pesapal не дошло до вашего магазина, а покупатель не вернулся. Проверьте, что URL из IPN URL доступен из интернета (без брандмауэра и парольной защиты перед ним). Включите Debug log и посмотрите поле Log на странице модуля.

Как магазин отвечает на уведомления: обработанное уведомление получает ответ HTTP 200. Если модуль не может его обработать, он отвечает ошибкой, и Pesapal отправит уведомление повторно позже: 400 (отсутствует или некорректен идентификатор отслеживания), 404 (ни одна корзина этого магазина не имеет такого идентификатора), 409 (транзакция принадлежит другому референсу мерчанта; ничего не меняется), 502 (API Pesapal в этот момент недоступен или не заполнены ключи того режима, в котором начат платёж) и 503 (корзина в это же время обновлялась при возврате покупателя или заказ не удалось создать, например потому, что модуль отключён).

Покупатель видит Pesapal is not available at the moment: Pesapal отклонил ключ или секрет потребителя текущего режима. Проверьте, что ключи соответствуют режиму: ключи тестовой среды работают только в sandbox, рабочие ключи — только в рабочем режиме. В журнале видна ошибка Pesapal.

Покупатель видит Pesapal is temporarily unavailable: Pesapal был недоступен или не удалось зарегистрировать URL уведомлений. Прочитайте журнал и повторите попытку.

После переключения платежи предыдущего режима не подтверждаются: платёж проверяется ключами того режима, в котором он был начат. Сохраняйте ключи этого режима, пока его платежи не подтверждены.

После оплаты заказ в статусе Pesapal payment on hold: прочитайте примечания в блоке Pesapal payment. Оплаченные сумма или валюта отличались от корзины, либо платёж поступил после отмены заказа. Проверьте платёж в панели Pesapal, затем обработайте заказ или верните платёж.

Удаление

Откройте Modules > Module Manager, нажмите меню рядом с VibeFox Pesapal Pay Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Кэшированные токены доступа Pesapal и зарегистрированные ID уведомлений удаляются всегда. Если включено Delete data, удаляются также настройки модуля и журнал. Если выключено, все настройки сохраняются для будущей переустановки. Попытки оплаты Pesapal и статус заказа Pesapal payment on hold всегда сохраняются. Существующие заказы сохраняют свои примечания об оплате, ID транзакций и идентификаторы отслеживания Pesapal.

Pesapal — торговая марка её владельца. Этот модуль не связан с Pesapal и не одобрен им.