VibeFox PayMongo for PrestaShop — Помощь

Требования

PrestaShop: с 8.0 до 9.x.

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

Валюта: филиппинское песо (PHP). PayMongo показывается на оформлении заказа только для корзин в PHP. Если основная валюта вашего магазина не PHP, на странице настроек появится предупреждение, и покупателям нужно переключиться на PHP, чтобы увидеть PayMongo.

Учётная запись PayMongo: нужны секретные ключи API вашей учётной записи PayMongo и вебхук для каждого режима (см. Настройка). Используются только секретные ключи (sk_test_..., sk_live_...) и ключи подписи вебхуков (whsk_...). Публичные ключи не нужны, так как страница оплаты размещена на стороне PayMongo. Способы оплаты, которые вы предлагаете, должны быть активированы в вашей учётной записи PayMongo.

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

Установка

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

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox PayMongo Payment Gateway в списке модулей и нажмите Configure.

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

4. Вставьте секретные ключи PayMongo, создайте вебхуки в PayMongo и вставьте их ключи подписи (см. Настройка).

5. Выберите способы оплаты, включите Enable/Disable и нажмите Save. Проверьте оплату при включённом Test mode, затем выключите его.

При установке модуль создаёт два статуса заказа: Awaiting PayMongo payment и PayMongo payment on hold. В Payment > Preferences проверьте, что модуль разрешён для филиппинского песо, стран ваших покупателей и их групп.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если основная валюта магазина не PHP, если в текущем режиме нет секретного ключа (тогда PayMongo не показывается на оформлении заказа) или нет секрета вебхука (тогда платежи подтверждаются только при возврате покупателя в магазин), а также показывает Test mode is on: no real payments are made., пока включён тестовый режим.

PayMongo

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

Title: название способа оплаты, которое видит покупатель при оформлении заказа. Оно же сохраняется в заказе. По умолчанию: PayMongo (Card, GCash, GrabPay, Maya). Обязательно.

Description: текст под способом оплаты на оформлении заказа. По умолчанию: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.

Payment methods: способы, которые предлагаются на странице оплаты PayMongo. Выбирайте только способы, активированные в вашей учётной записи PayMongo, иначе PayMongo отклонит оплату. Если ничего не выбрано, используются значения по умолчанию. По умолчанию: Cards, GCash, GrabPay and Maya.

Ключи API

Скопируйте секретные ключи из PayMongo Dashboard > Developers > API keys. Публичные ключи не нужны. Каждый ключ должен начинаться с ожидаемого префикса. Значение с неверным префиксом не сохраняется: страница показывает, что поле must start with префикс, и что The previous value was kept.

Test mode: Enable test mode (no real payments). Новые платежи используют тестовые ключи. Платежи, совершённые раньше, сохраняют режим, в котором были созданы, поэтому проверки статуса и возвраты используют соответствующий ключ. По умолчанию: включено. Выключите, чтобы принимать реальные платежи.

Test secret key: секретный ключ тестового режима. Начинается с sk_test_.

Test webhook secret: ключ подписи вебхука тестового режима. Начинается с whsk_.

Live secret key: секретный ключ боевого режима. Начинается с sk_live_.

Live webhook secret: ключ подписи вебхука боевого режима. Начинается с whsk_.

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

Clear saved secrets: отметьте ключ или секрет и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Webhook

Вебхук сообщает вашему магазину, что платёж совершён, в том числе когда покупатель закрыл браузер после оплаты. Создайте вебхук в панели PayMongo (или через API PayMongo) для каждого режима, тестового и боевого, с URL, который показан в поле Webhook URL в этом разделе. При включённых ЧПУ URL выглядит так: https://your-shop/module/wcp_paymongo_payment_gateway/webhook, возможно, с кодом языка, например /en/. Скопируйте URL точно так, как он показан в настройках.

Выберите эти события (они также перечислены в этом разделе):

Скопируйте ключ подписи (whsk_...) каждого вебхука в Test webhook secret или Live webhook secret. Вебхуки без действительной подписи отклоняются. Подпись проверяется секретом своего режима, и режим события должен совпадать с ним, поэтому тестовый вебхук никогда не подтвердит реальный платёж. Каждое событие перед созданием или изменением заказа повторно проверяется через API PayMongo секретным ключом режима платежа. PayMongo отправляет события всего аккаунта каждому вебхуку; события платежей, которые не были начаты в этом магазине, игнорируются. Без вебхука заказ создаётся, только когда покупатель возвращается в магазин после оплаты.

Заказы

Order status after payment: статус заказа, который устанавливается после успешной оплаты.

Платежи, которые ещё обрабатываются, ожидают в статусе Awaiting PayMongo payment. Несоответствия суммы или валюты и тестовые платежи в боевом магазине всегда попадают в PayMongo payment on hold.

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

Debug log: записывает вызовы API PayMongo и события вебхуков в logs/paymongo_p_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки и предупреждения записываются всегда, даже когда переключатель выключен. Ключи и данные покупателей никогда не записываются. По умолчанию: выключено.

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

Delete data on uninstall: если включено, при удалении модуля удаляются настройки и журнал. Идентификаторы PayMongo, сохранённые для заказов, возвраты и статусы заказов модуля, всегда сохраняются, так как они нужны для возвратов и учёта. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию PayMongo (Card, GCash, GrabPay, Maya)) и видит его описание. В тестовом режиме оформление заказа также показывает Test mode: no real payment will be made. PayMongo предлагается только для корзин в PHP с суммой не менее 100,00 ₱.

После подтверждения модуль создаёт PayMongo Checkout Session на сумму корзины в PHP, с одной строкой Cart # и номером корзины, и отправляет покупателя на страницу оплаты PayMongo. Имя, e-mail, телефон и адрес для выставления счёта покупателя передаются в PayMongo. Там покупатель выбирает один из выбранных способов и платит. На этом этапе заказа ещё нет.

После оплаты покупатель возвращается в ваш магазин. Заказ помечается как оплаченный только после подтверждения PayMongo: модуль запрашивает у API PayMongo информацию о платеже, когда покупатель возвращается и когда приходит вебхук. Тогда заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с Your PayMongo payment has been received. Если PayMongo ещё обрабатывает платёж, когда покупатель возвращается, заказ создаётся в статусе Awaiting PayMongo payment, а на странице показывается PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. Если платёж позже не удастся, страница показывает Your PayMongo payment was not completed. Please contact us about this order. Если PayMongo недоступен, когда покупатель возвращается, появляется страница Payment confirmation, которая просит покупателя не платить повторно, и кнопка Check again; вебхук создаёт заказ, как только придёт.

Если покупатель отменяет оплату на странице PayMongo или не завершает её, он возвращается к оформлению заказа с сообщением You cancelled the PayMongo payment. You can try again or choose another payment method. или Your PayMongo payment was not completed. You can try again or choose another payment method. Корзина сохраняется. Новая попытка сначала проверяет предыдущую: если её тем временем оплатили, заказ создаётся без новой оплаты; иначе предыдущая ссылка на оплату PayMongo становится недействительной, поэтому корзину нельзя оплатить дважды. Пока предыдущий платёж ещё обрабатывается, покупатель видит Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.

Если PayMongo не может начать оплату, покупатель остаётся на оформлении заказа с коротким сообщением, например The payment could not be started. Please try again or choose another payment method. или PayMongo could not be reached. Please try again in a moment. Техническая причина записывается в журнал.

Вебхук работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

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

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

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

No order yet: покупатель был отправлен на PayMongo и ещё не заплатил, или PayMongo ещё не подтвердил платёж. Существует только корзина.

Payment accepted or Delivered: платёж подтверждён. Статус следует за Order status after payment. Платёж записывается с идентификатором PayMongo (pay_...) как ID транзакции, а примечание показывает платёж, сумму, способ, режим и то, как он был подтверждён (вебхуком или возвратом).

Awaiting PayMongo payment: покупатель вернулся, пока PayMongo ещё обрабатывал платёж. Заказ переходит в оплаченный статус, когда PayMongo подтверждает платёж.

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

Payment error: подписанный вебхук payment.failed сообщил, что последняя попытка оплаты заказа в статусе Awaiting PayMongo payment не удалась. Примечание показывает код и сообщение об ошибке PayMongo. Если тот же платёж позже пройдёт успешно, заказ переходит в оплаченный статус.

Refunded: платёж полностью возвращён через модуль.

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

Блок PayMongo payment

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

Возвраты

В блоке PayMongo payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via PayMongo. Подтвердите вопрос Refund this amount through PayMongo? This cannot be undone. Поддерживаются полные и частичные возвраты, не более двух знаков после запятой. Нужно право редактировать заказы; доступ к страницам модулей не требуется. Возвраты ограничены суммой, которую PayMongo фактически списал, поэтому после расхождения суммы можно вернуть не больше того, что заплатил покупатель, а не сумму заказа. Возврат отправляется секретным ключом режима, в котором был совершён платёж (тестовый или боевой), поэтому этот ключ должен быть задан. Причина, которую вы введёте, передаётся в PayMongo как примечание к возврату. Если PayMongo не принимает возврат, блок показывает ошибку и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания с идентификатором и статусом возврата PayMongo. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет.

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через PayMongo. Возвраты, сделанные в панели PayMongo, не переносятся в PrestaShop. Оформляйте возврат из блока заказа или обновите заказ вручную.

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

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

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

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

Решение проблем

PayMongo не отображается на оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включён, что в текущем режиме задан секретный ключ (Test secret key в тестовом режиме, Live secret key в боевом), что корзина в PHP и сумма не меньше 100,00 ₱. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: вебхук не работает, и покупатель не вернулся в магазин. В панели PayMongo проверьте, что в используемом режиме есть вебхук, что его URL точно совпадает с показанным в Webhook URL и что выбраны все три события. Проверьте, что его ключ подписи указан в нужном поле (Test webhook secret или Live webhook secret).

Вебхук отвечает Invalid signature: ключ подписи этого режима отсутствует или принадлежит другому вебхуку. Вставьте ключ подписи вебхука в поле его режима.

Вебхук отвечает Mode mismatch: тестовое событие было подписано как боевое или наоборот. Проверьте, что каждый вебхук принадлежит правильному режиму.

Вебхук отвечает Temporary error: платёж не удалось проверить через API PayMongo, например потому, что отсутствует секретный ключ режима платежа. PayMongo автоматически повторяет вебхук.

Вебхук отвечает Busy, retry: заказ в тот же момент подтверждал другой запрос, или заказ не удалось создать (например, модуль отключён). PayMongo автоматически повторяет вебхук. Причина указана в Log.

Вебхук отвечает Ignored: событие относится к платежу, который не был начат в этом магазине, или к другому режиму. Ничего не меняется.

URL вебхука в браузере показывает Method not allowed: это нормально. URL принимает только запросы от PayMongo.

Значение не сохранилось: ключ вставлен не в то поле. Секретные ключи начинаются с sk_test_ или sk_live_, секреты вебхуков — с whsk_.

Покупатель видит ошибку при выборе PayMongo: посмотрите поле Log на странице модуля. Неверный секретный ключ даёт сообщение, что способ оплаты временно недоступен. Способ оплаты, не активированный в вашей учётной записи PayMongo, заставляет PayMongo отклонить оформление; удалите его из Payment methods.

Тестовые платежи в боевом магазине: тестовый платёж, пришедший, пока магазин работает в боевом режиме, переводит заказ в PayMongo payment on hold с примечанием, что деньги не получены. Реальные платежи распознаются всегда, в том числе после возврата в тестовый режим, и возвращаются боевым ключом.

Заказ в PayMongo payment on hold после оплаты: прочитайте примечания в блоке PayMongo payment (см. Статусы заказа), затем обработайте заказ или верните платёж.

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

Разработчики могут изменить данные Checkout Session с помощью хука actionPaymongoPCheckoutSessionData.

Удаление

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

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