VibeFox Pesapal for WooCommerce — Помощь

Требования

WordPress: 6.2 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Без него плагин не активируется.

PHP: 8.0 или новее.

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

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

VibeFox license key: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

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

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Pesapal > Manage, либо нажмите Settings под названием плагина на странице плагинов.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

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

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

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Pesapal. Над полями значок показывает среду: 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 помечается как тестовый режим, пока включена тестовая среда.

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

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

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

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 consumer secret: секрет потребителя вашей тестовой учётной записи мерчанта. Используется только в тестовой среде.

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

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

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

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

Debug log: Log Pesapal requests and notifications записывает подробности в WooCommerce > Status > Logs, источник wcp_pesapal_pay. Ошибки и предупреждения записываются всегда. Ключи, токены и данные покупателей никогда не записываются. По умолчанию: выключено.

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

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

Покупатель выбирает способ оплаты (по умолчанию Pesapal (M-Pesa, Airtel Money, cards)) и оформляет заказ. В тестовой среде блок «Оформление заказа» показывает Sandbox mode: no real money will be charged. Плагин создаёт запрос на оплату Pesapal на полную сумму заказа в его валюте с платёжными реквизитами заказа и добавляет заметку с указанием среды, суммы и идентификатора отслеживания Pesapal. Покупатель переходит на платёжную страницу Pesapal и платит одним из предложенных способов, например через M-Pesa, Airtel Money, MTN, картой или через банк.

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

После оплаты покупатель возвращается на страницу полученного заказа. Платежи через мобильные деньги могут занять некоторое время. Если платёж ещё не подтверждён, страница показывает 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. Уведомление Pesapal завершит заказ позже. Если заказ переведён на удержание, страница показывает Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

Если покупатель отменяет оплату на странице Pesapal, он возвращается на страницу Pay for order с сообщением 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. Технические подробности записываются в заметки заказа и журнал. Сумма заказа должна быть больше нуля.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с высокопроизводительным хранилищем заказов WooCommerce (HPOS).

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

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

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

Pending payment: покупатель перешёл в Pesapal и ещё не заплатил либо Pesapal ещё не подтвердил платёж.

Processing: Pesapal сообщает о завершённом платеже, а сумма и валюта совпадают. Заметка заказа показывает сумму, способ оплаты, код подтверждения Pesapal и идентификатор отслеживания. Идентификатор транзакции заказа — это идентификатор отслеживания Pesapal. Каждый платёж применяется один раз.

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

Failed: Pesapal сообщает о неудаче последней попытки оплаты. В заметке указана причина от Pesapal. Если покупатель повторяет попытку со страницы Pay for order и она тоже завершается неудачно, добавляется ещё одна заметка с причиной. Неудача более ранней попытки не меняет заказ. Покупатель может заплатить снова.

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

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

Возвраты

Плагин не отправляет возвраты в Pesapal. Верните платёж в панели Pesapal, затем вручную зарегистрируйте возврат в WooCommerce.

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

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

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает место для домена. Освободите его в своей учётной записи vibefox.net.

Без активного ключа Pesapal не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Авторизованные управляющие магазином по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание отображается на странице плагинов и страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются уведомлением Pesapal и возвратом покупателя.

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

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

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

Платёж прошёл, но заказ остаётся в статусе «Ожидание оплаты»: уведомление Pesapal не дошло до магазина, а покупатель не вернулся. Проверьте доступность URL из Payment notifications (IPN) из интернета (без режима обслуживания, межсетевого экрана или защиты паролем перед /wc-api/pesapal_pay/). Посмотрите WooCommerce > Status > Logs, источник wcp_pesapal_pay.

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

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

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

После оплаты заказ в статусе «На удержании»: прочитайте заметку заказа. Оплаченная сумма или валюта отличалась от заказа либо платёж поступил после его отмены. Проверьте платёж в панели Pesapal, затем обработайте заказ или верните платёж.

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

Удаление

Отключение плагина сохраняет все данные. Для удаления отключите и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина, кешированные токены доступа Pesapal и зарегистрированные идентификаторы уведомлений удаляются всегда. Настройки плагина и его журналы (файлы журналов, включая ротированные, и записи журнала в базе данных источника wcp_pesapal_pay) удаляются только при включённом Delete data. Иначе они остаются для последующей переустановки. Существующие заказы сохраняют заметки об оплате, идентификаторы транзакций и идентификаторы отслеживания Pesapal.

Pesapal — товарный знак соответствующего владельца. Этот плагин не связан с Pesapal и не одобрен Pesapal.