VibeFox Pesapal for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

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

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

Установка

Загружаемый файл — это один ZIP-архив с пакетами для обеих версий OpenCart. Распакуйте его на компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_pesapal_pay-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_pesapal_pay.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В административной панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_pesapal_pay-oc3-(version).ocmod.zip. Расширение не содержит модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Pesapal Pay Gateway и нажмите Install (зелёная кнопка +). Вашему пользователю администратора нужно право на изменение списка расширений оплаты.

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

4. Введите consumer key и consumer secret песочницы, включите Enable/Disable, нажмите Save и сделайте тестовый заказ.

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

OpenCart 4

1. В административной панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_pesapal_pay.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появляется в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Pesapal Pay Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с изображением карандаша).

4. Введите лицензионный ключ и ключи Pesapal так же, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только IPN URL (см. Уведомления о платежах).

Новая установка начинает работу с выключенным способом оплаты и включённым режимом песочницы.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками бейдж показывает режим: SANDBOX — тестовые платежи на cybqa.pesapal.com — реальные деньги не списываются. или LIVE — реальные платежи на pay.pesapal.com. Появляется предупреждение, если не заполнены ключи текущего режима (Введите consumer key и secret песочницы — до этого Pesapal не показывается на оформлении заказа., или аналогичное сообщение для боевой среды), а также если Pesapal не поддерживает валюту по умолчанию вашего магазина. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении пустой Title не принимается: сохраняется прежнее название с ошибкой, а остальные поля сохраняются. Sort Order должен быть целым числом (отрицательные значения допускаются), Total — числом не меньше 0, а Geo Zone и статусы заказов должны существовать; иначе это поле сохраняет прежнее значение и показывает ошибку. При сохранении кешированные токены доступа Pesapal сбрасываются.

Pesapal

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

Sort Order: место Pesapal среди способов оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Pesapal только для платёжных адресов из выбранной географической зоны. По умолчанию: All zones. Географические зоны настраиваются в разделе System > Localisation > Geo Zones.

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

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

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

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

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

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

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

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

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

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

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

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

OpenCart создаёт заказ на шаге Confirm Order без статуса (неполный заказ). Заказ получает статус только после того, как Pesapal сообщит, что платёж «Completed». Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Order Status After Payment: статус, который устанавливается, когда Pesapal подтверждает платёж. По умолчанию: Processing.

Pesapal Payment On Hold Status: платежи, сумма или валюта которых не совпадают с заказом, и платежи, полученные после отмены. Примечание объясняет причину. По умолчанию: Pending, так как в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Cancelled Order Status: платёж Pesapal, пришедший по заказу в этом статусе (или в статусе возврата), переводит заказ в удержание, а не открывает его тихо заново. По умолчанию: Canceled.

Refunded Status: устанавливается, когда Pesapal сообщает, что платёж по заказу отменён. По умолчанию: Refunded.

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

IPN URL: показывает URL уведомлений вашего магазина. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_pesapal_pay/ipn, в OpenCart 4 — так: https://your-store/index.php?route=extension/wcp_pesapal_pay/payment/wcp_pesapal_pay.ipn. Он формируется из адреса витрины вашей установки OpenCart. URL автоматически регистрируется в Pesapal при первом платеже — отдельно для песочницы и боевой среды и для каждого consumer key, так что настраивать ничего не нужно. После первого платежа раздел показывает Registered IPN ID: с ID, который вернул Pesapal; до этого там написано Для текущего режима и ключей ещё не зарегистрирован. URL должен быть доступен из интернета: перед ним не должно быть брандмауэра или парольной защиты. Он продолжает работать, пока магазин находится в режиме обслуживания, потому что OpenCart пропускает запросы расширений оплаты (в OpenCart 4 для этого расширение добавляет собственное стартовое действие, которое также пропускает возврат покупателя из Pesapal).

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

Debug log: записывает запросы и уведомления Pesapal в файл pesapal_p_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть из браузера; при достижении 5 МБ он переименовывается в pesapal_p_debug.old.log.php. Ошибки и предупреждения записываются всегда, даже когда переключатель выключен. Ключи, токены и данные покупателей никогда не записываются. По умолчанию: выключено.

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

Delete data: удаляет настройки расширения и журналы при его удалении. Данные Pesapal, сохранённые в заказах (ID отслеживания, примечания), относятся к истории платежей и всегда сохраняются. Отключение расширения ничего не удаляет. По умолчанию: выключено.

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. Consumer key и secret не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые consumer key и secret остаются без изменений.

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Pesapal (M-Pesa, Airtel Money, cards)). На шаге Confirm Order покупатель видит ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение создаёт запрос платежа Pesapal на сумму заказа в валюте заказа с платёжными данными из платёжного адреса (в OpenCart 4, если оформление не запрашивает платёжный адрес, — из адреса доставки) и перенаправляет покупателя на страницу оплаты Pesapal. Описание платежа, передаваемое в Pesapal, — Order, номер заказа и название магазина. Там покупатель платит одним из способов, которые предлагает Pesapal, например M-Pesa, Airtel Money, MTN, картой или банковским переводом. Примечание к заказу фиксирует запрос платежа.

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

Платежи через мобильные деньги могут занять некоторое время. Если Pesapal ещё не подтвердил платёж, когда покупатель возвращается, появляется страница Payment confirmation с сообщением Pesapal подтверждает ваш платёж. Вы получите письмо, как только платёж будет подтверждён, — повторно платить не нужно. и кнопками Check again и Back to checkout. Уведомление от Pesapal устанавливает статус заказа, как только платёж подтверждён. Если заказ был переведён в удержание, страница успешного оформления показывает Ваш платёж получен и проверяется магазином. Вы получите письмо, когда заказ будет подтверждён. Когда последующий платёж переводит заказ из статуса удержания в статус оплаченного, покупатель получает письмо.

Если покупатель отменяет платёж на странице Pesapal, он возвращается на оформление заказа с сообщением Платёж Pesapal был отменён. Вы можете попробовать снова или выбрать другой способ оплаты. Если платёж не прошёл, появляется сообщение Платёж Pesapal не был успешным. Попробуйте снова или выберите другой способ оплаты., а примечание к заказу указывает причину. Корзина сохраняется, и покупатель может оплатить снова. На OpenCart 4 эти сообщения показываются над страницей оформления заказа. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 обновляет заказ оформления, поэтому перед новым платежом расширение проверяет в Pesapal предыдущие попытки оплаты корзины: если одна из них тем временем оплачена, этот заказ получает статус, и покупатель переходит на страницу успешного оформления без повторной оплаты. Платёж, сделанный позже на более ранней странице Pesapal этой корзины, всё равно принимается. Изменение корзины, в том числе нового количества, считается новой корзиной, для которой нужна собственная оплата.

OpenCart 4 хранит заказ в оформлении, пока не будет показана страница успеха. Если этот заказ к тому времени закрыт (например, вы его отменили) либо оплачен по прежней корзине, которая с тех пор изменилась, покупатель возвращается в оформление с сообщением Ваш предыдущий заказ уже закрыт. Подтвердите заказ ещё раз: корзина будет оплачена новым заказом. Следующее нажатие Confirm Order оплачивает новый заказ. Закрытый заказ никогда не показывается как оплаченный.

Если Pesapal не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например Pesapal временно недоступен. Попробуйте через несколько минут или выберите другой способ оплаты., Pesapal сейчас недоступен. Выберите другой способ оплаты. (неверные ключи) или Pesapal не смог начать платёж: и причина от Pesapal. Техническая причина записывается в журнал и в примечания к заказу. Сумма заказа должна быть больше нуля.

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

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

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

Без статуса (неполный заказ): покупатель был отправлен в Pesapal и не оплатил, платёж не прошёл или Pesapal ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Order Status After Payment (по умолчанию Processing): Pesapal сообщает, что платёж «Completed», и сумма и валюта совпадают. Примечание показывает сумму, способ оплаты, код подтверждения Pesapal и ID отслеживания. Каждый платёж применяется только один раз.

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

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

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

Примечания — это записи в History заказа, которые покупатель не видит.

VibeFox Pesapal Pay Gateway tab

В Sales > Orders откройте заказ, оплаченный через Pesapal. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Pesapal Pay Gateway показывает ID отслеживания с меткой Sandbox или Live, справочный номер мерчанта, статус Pesapal, способ оплаты, код подтверждения, запрошенную и оплаченную сумму, причину проверки, все Payment attempts заказа (если их больше одной) и Payment notes. Вкладка только для чтения и показывается пользователям, имеющим доступ к расширению.

Возвраты

Расширение не отправляет возвраты в Pesapal. Верните платёж в личном кабинете Pesapal, затем вручную зафиксируйте возврат в OpenCart. Возвраты товаров в Sales > Returns не возвращают деньги через Pesapal.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Pesapal Pay Gateway — это первый блок в Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату окончания лицензии и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key, чтобы убрать ключ из этого магазина. Ниже находятся строка Product: opencart-payment-pesapal и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только пользователи-администраторы с правом Modify на расширение. Тексты блока следуют языку административной панели (включены английский и русский).

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

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

Без активного ключа Pesapal не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит Этот способ оплаты недоступен. Выберите другой. Пользователь-администратор, вошедший в административную панель в том же браузере, по-прежнему видит способ оплаты в магазине, помеченный как (без лицензии — видно только администраторам), чтобы вы могли настроить и протестировать расширение до покупки ключа. На OpenCart 4 этого предпросмотра нет: магазин не видит вход в административную панель, поэтому без действующего ключа способ оплаты скрыт для всех. После того как вы один раз открыли страницу Edit, на Dashboard административной панели появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а уведомления Pesapal о существующих платежах, включая отмены, по-прежнему применяются.

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

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

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

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

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

Покупатель видит сообщение «Pesapal сейчас недоступен»: Pesapal отклонил consumer key или secret текущего режима. Проверьте, что ключи соответствуют режиму: ключи песочницы работают только в песочнице, боевые — только в боевом режиме. В журнале видна ошибка Pesapal.

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

Покупатель видит сообщение «Этот способ оплаты недоступен. Обновите страницу оформления заказа.»: сессия оформления заказа больше не соответствует заказу, или способ оплаты тем временем выключили. Покупатель обновляет страницу оформления заказа.

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

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

Заказ в статусе удержания после оплаты: прочитайте примечания на вкладке VibeFox Pesapal Pay Gateway. Оплаченная сумма или валюта отличались от заказа, либо платёж пришёл после отмены заказа. Проверьте платёж в личном кабинете Pesapal, затем обработайте заказ или верните платёж.

Для разработчиков: расширение вызывает события OpenCart pesapal_p_supported_currencies (список валют) и pesapal_p_submit_order_payload (запрос платежа до отправки в Pesapal).

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Pesapal Pay Gateway. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Статусы заказов, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения, кешированные токены доступа Pesapal и зарегистрированные ID уведомлений также всегда удаляются (в OpenCart 4 также его события и стартовое действие, которое пропускает уведомления и возврат покупателя в режиме обслуживания). Если включено Delete data, удаляются остальные настройки (название, описание, режим песочницы, ключи, переключатель журнала отладки) и журнал. Если выключено, они сохраняются для повторной установки. Попытки платежей Pesapal всегда сохраняются. Существующие заказы сохраняют примечания об оплате и ID отслеживания Pesapal.

На OpenCart 4, чтобы удалить и файлы расширения, после удаления перейдите в Extensions > Installer и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Pesapal Pay Gateway в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Pesapal — товарный знак его правообладателя. Это расширение не связано с Pesapal и не одобрено Pesapal.