VibeFox PayMongo for WooCommerce — Помощь

Требования

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

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

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

Валюта: филиппинское песо (PHP). Способ оплаты скрывается, если валюта магазина или валюта заказа на странице Pay for order не PHP.

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

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

Установка

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

2. Нажмите Activate.

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

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

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

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

Настройка

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

Webhook

Вебхук сообщает вашему магазину, что платёж совершён, в том числе если покупатель закрыл браузер после оплаты. Создайте вебхук в панели PayMongo (или через API PayMongo) для каждого режима, тестового и боевого, с URL, который показан в этом разделе настроек. Он выглядит так: https://your-site/?wc-api=paymongo_p_webhook.

Выберите эти события:

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

Заказы

Статус заказа после оплаты: статус заказа, который устанавливается после успешной оплаты. Статус устанавливается сразу, без второго изменения статуса.

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

Debug log: Log API calls and webhook events записывает их в WooCommerce > Status > Logs, источник wcp_paymongo_payment_gateway. Ошибки записываются всегда. Ключи и данные покупателей никогда не записываются. По умолчанию: выкл.

Delete data on uninstall: Delete the settings and logs when the plugin is deleted. ID PayMongo, сохранённые в заказах, остаются, так как они нужны для возвратов и учёта. По умолчанию: выкл.

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

Покупатель выбирает способ оплаты (по умолчанию PayMongo (Card, GCash, GrabPay, Maya)) и оформляет заказ. В тестовом режиме на странице оформления заказа отображается Test mode: no real payment will be made. Плагин создаёт сессию оплаты PayMongo на сумму заказа в PHP, с одной строкой Order # и номером заказа, и отправляет покупателя на платёжную страницу PayMongo. Имя, e-mail, телефон и платёжный адрес покупателя передаются в PayMongo. Там покупатель выбирает один из выбранных способов и оплачивает.

Способ оплаты показывается только для заказов от 100,00 ₱. Заказ меньшей суммы нельзя оплатить через PayMongo.

После оплаты покупатель возвращается на страницу «Заказ получен» вашего магазина. Заказ помечается оплаченным только после подтверждения PayMongo: плагин запрашивает платёж через API PayMongo, когда покупатель возвращается, и когда приходит вебхук. Если PayMongo ещё обрабатывает платёж или недоступен, покупатель всё равно попадает на страницу «Заказ получен», а вебхук завершит заказ позже.

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

Способ оплаты работает на классическом оформлении заказа, в блоке оформления заказа и на странице Pay for order. Он совместим с WooCommerce High-Performance Order Storage (HPOS).

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

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

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

Pending payment: покупатель был отправлен в PayMongo и ещё не оплатил, или PayMongo ещё не подтвердил платёж. В примечании фиксируется каждая сессия оплаты PayMongo, созданная для заказа. Пока PayMongo обрабатывает платёж, в примечании об этом сказано.

Processing или Completed: платёж подтверждён. Статус соответствует настройке Order status after payment. В примечании к заказу указаны платёж PayMongo, сумма, способ и режим. ID транзакции — это ID платежа PayMongo (pay_...). На экране заказа под платёжным адресом показаны сессия оплаты PayMongo, намерение оплаты и режим.

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

Failed: подписанный вебхук payment.failed сообщил, что последняя попытка оплаты ожидающего заказа не удалась. В примечании указаны код и сообщение об ошибке PayMongo. Покупатель может оплатить снова.

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via PayMongo (Card, GCash, GrabPay, Maya) (на кнопке отображается название вашего способа оплаты). Поддерживаются полные и частичные возвраты. Возврат отправляется с секретным ключом режима, в котором был совершён платёж (тестовый или боевой), поэтому этот ключ должен быть задан. Если PayMongo не принимает возврат, WooCommerce показывает ошибку и возврат не регистрируется. Успешный возврат добавляется в примечания к заказу вместе с ID и статусом возврата PayMongo.

Возвраты, сделанные в панели PayMongo, не переносятся в WooCommerce. Оформляйте возврат из заказа WooCommerce или создайте ручной возврат в WooCommerce.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заказ в статусе On hold после оплаты: прочитайте примечание к заказу. Оплаченные сумма или валюта не совпали с заказом, платёж был тестовым или поступил после отмены заказа. Обработайте заказ или сделайте возврат платежа.

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

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

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, временные данные и журналы удаляются, только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои примечания об оплате, ID транзакций и ID PayMongo.

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