VibeFox Pagar.me for WooCommerce — Помощь

Требования

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

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

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

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

Учётная запись Pagar.me: нужны секретные ключи вашей учётной записи Pagar.me: тестовый (sk_test_...) и, для боевого режима, боевой (sk_...). Они находятся в личном кабинете Pagar.me в разделе Development > Keys. Используются только секретные ключи; публичный ключ (pk_...) не нужен. Можно предлагать только те способы оплаты, которые включены в вашей учётной записи Pagar.me.

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите тестовый секретный ключ, а при переходе в боевой режим — боевой секретный ключ.

6. Создайте вебхук в личном кабинете Pagar.me с URL, который показан в настройках (см. раздел «Настройка»).

7. Включите Enable / Disable и сохраните. Совершайте тестовые платежи при включённом Test mode, затем выключите его, чтобы принимать реальные платежи.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Pagar.me. Под заголовком страница показывает текущий режим: TEST MODE (платежи создаются с тестовым секретным ключом, реальных списаний нет) или LIVE. Она предупреждает, если отсутствует секретный ключ текущего режима (тогда способ оплаты скрыт при оформлении заказа), если тестовый ключ не начинается с sk_test_, если боевой ключ не начинается с sk_ или является тестовым, и если валюта магазина не BRL. В списке способов оплаты Pagar.me помечен как требующий настройки, пока не введён ключ текущего режима, а пока включён тестовый режим, отображается соответствующая метка.

Общие

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

Title: название способа оплаты, которое видят покупатели при оформлении заказа. По умолчанию: Pagar.me.

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

API-ключи

Скопируйте секретные ключи из личного кабинета Pagar.me: Development > Keys. Pagar.me использует один адрес API для тестовых и боевых платежей; ключ определяет, является платёж тестовым или реальным.

Test mode: Use the test secret key (no real charges). Пока тестовый режим включён, на оформлении заказа показывается примечание TEST MODE. Проверки статуса и возвраты заказа всегда используют ключ того режима, в котором был создан его платёж. По умолчанию: включено.

Test secret key: тестовый секретный ключ Pagar.me (sk_test_...). Используется, пока тестовый режим включён.

Live secret key: боевой секретный ключ Pagar.me (sk_...). Используется, когда тестовый режим выключен. Храните его в секрете.

Единый секретный ключ версии 1.0 переносится автоматически: тестовый ключ попадает в Test secret key, и тестовый режим включается; в противном случае он остаётся боевым ключом, и тестовый режим выключается.

Страница оплаты

Payment methods: способы, которые предлагаются на странице оплаты Pagar.me. Выбирайте только те, что включены в вашей учётной записи Pagar.me. По умолчанию: Credit card, PIX и Boleto.

Boleto due in (days): количество дней до срока оплаты boleto, от 1 до 30. Заказ остаётся в статусе On hold, пока Pagar.me не подтвердит оплату. По умолчанию: 3.

Уведомления об оплате (вебхук)

В личном кабинете Pagar.me откройте Settings > Webhooks и создайте вебхук с URL из этого раздела. Он выглядит так: https://your-site/wc-api/webhook_wc_pagarme/. Скопируйте его точно в том виде, в каком он показан в настройках.

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

Вебхук не требует пароля или подписи. Его содержимое никогда не считается достоверным: магазин берёт из него только ID заказа Pagar.me и читает этот заказ через API Pagar.me с ключом режима, в котором он создан. Уведомления о заказах других магазинов в той же учётной записи Pagar.me игнорируются. Без вебхука PIX и boleto, оплаченные позже, подтверждаются только тогда, когда покупатель возвращается в магазин.

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

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

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Pagar.me) и оформляет заказ. Обязателен действительный адрес электронной почты для выставления счёта. Плагин создаёт заказ Pagar.me на сумму в BRL со строками заказа, доставкой и сборами (или одной строкой Order # с номером заказа, если строки не могут точно сложиться) и отправляет покупателя на страницу оплаты Pagar.me. Имя, адрес электронной почты покупателя, а для Бразилии также телефон и адрес для выставления счёта передаются в Pagar.me. CPF или CNPJ берётся из полей плагина Brazilian Market on WooCommerce, если они есть; иначе покупатель вводит его на странице Pagar.me.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Pagar.me: магазин читает заказ Pagar.me через API, и оплаченная сумма и валюта должны совпадать с заказом. Оплата картой, PIX или boleto отмечает заказ оплаченным. Выставленный, но ещё не оплаченный PIX или boleto переводит заказ в статус On hold, пока Pagar.me не подтвердит оплату через вебхук.

Если покупатель вернулся без оплаты, либо платёж был отклонён или отменён, он попадает на страницу Pay for order с сообщением The Pagar.me payment was not completed. You can pay the order below. или The Pagar.me payment was declined or canceled. You can try again below.

Когда покупатель платит повторно, открытая страница оплаты Pagar.me используется снова, если сумма и режим те же; иначе она закрывается в Pagar.me, прежде чем создаётся новая. Если предыдущая попытка тем временем была оплачена или её PIX или boleto ещё ожидает оплаты, заказ обновляется без новой оплаты. Если предыдущую страницу не удаётся закрыть, она остаётся связанной с заказом, поэтому оплата, выполненная на ней, всё равно будет учтена.

Если Pagar.me не может начать оплату, покупатель видит короткое сообщение, например Could not connect to Pagar.me. Please try again in a moment., или сообщение Pagar.me о неверных платёжных данных. Техническая причина добавляется в примечания к заказу.

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

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

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

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

Pending payment: покупатель был отправлен в Pagar.me и ещё не оплатил или не создал PIX или boleto. В примечании указаны ID заказа Pagar.me и режим.

Processing: оплата подтверждена. Это стандартный статус WooCommerce после оплаты; заказы, содержащие только виртуальные скачиваемые товары, переходят в статус «Выполнен». В примечании к заказу указаны ID заказа Pagar.me и способ оплаты. ID транзакции — это ID заказа Pagar.me (or_...).

On hold: выставлен PIX или boleto (или платёж картой находится на проверке) и ожидает оплаты; либо boleto оплачено только частично; либо оплаченная сумма или валюта не совпадает с заказом; либо платёж поступил после отмены заказа; либо заказ оплачен в Pagar.me после того, как покупатель переключился на другой способ оплаты; либо по оплаченному заказу открыт чарджбэк. Причина объясняется в примечании к заказу. Проверьте заказ и переведите его в статус «Processing» или верните платёж в Pagar.me.

Failed: оплата не удалась, либо заказ Pagar.me был отменён или истёк (например, неоплаченное boleto). Перевести неоплаченный заказ в статус Failed может только последняя попытка. Покупатель может оплатить заново.

Refunded: платёж возвращён или отменён в Pagar.me.

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Pagar.me (на кнопке отображается название вашего способа оплаты). Поддерживаются полные и частичные возвраты платежей картой и PIX в пределах суммы, которую ещё можно вернуть в Pagar.me. Возврат отправляется с ключом того режима, в котором была произведена оплата. Возврат фиксируется только после подтверждения Pagar.me; в противном случае WooCommerce показывает ошибку, например Pagar.me refused the refund: ... или Pagar.me did not confirm the refund, и возврат не фиксируется. Успешный возврат добавляется в примечания к заказу с ID списания.

Платежи boleto можно вернуть только на банковский счёт покупателя. Верните их в личном кабинете Pagar.me, а затем вручную зафиксируйте возврат в WooCommerce, не используя Refund via Pagar.me.

Полный возврат или отмена, выполненные в личном кабинете Pagar.me, приходят через вебхук и переводят заказ в статус Refunded. Чарджбэк добавляет примечание и переводит заказ в статусе Processing или Completed в статус «On hold».

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

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

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

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

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

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

Pagar.me не появляется при оформлении заказа: проверьте, что лицензия активна, включён Enable / Disable, задан секретный ключ текущего режима (Test secret key в тестовом режиме, Live secret key в боевом) и валюта магазина — BRL. Страница настроек показывает предупреждение в каждом из этих случаев.

Платёж прошёл, но заказ остаётся в статусе Pending payment или On hold: вебхук не работает. В личном кабинете Pagar.me проверьте, что вебхук существует для используемой учётной записи и режима, что его URL точно совпадает с показанным в настройках и что выбраны перечисленные выше события. Заказ также проверяется, когда покупатель возвращается в магазин.

Вебхук отвечает verification failed, retry later: магазин не смог прочитать заказ Pagar.me через API, например потому что ключ этого режима отсутствует или API не ответил. Pagar.me повторит вебхук.

Вебхук отвечает busy, retry later: заказ в тот же момент обновлялся другим запросом. Pagar.me повторит вебхук.

Вебхук отвечает unknown order: заказ Pagar.me создан не этим магазином, например это заказ другого магазина в той же учётной записи. Ничего не меняется.

Покупатель видит This order is already being processed: вебхук или возврат покупателя в тот же момент обновлял заказ. Покупатель может повторить попытку через некоторое время.

Покупатель видит Pagar.me payments are not available right now: секретный ключ неверный или отсутствует. Проверьте ключ текущего режима.

Покупатель видит Pagar.me could not start the payment: Pagar.me отклонил платёжные данные. Сообщение указывает на проблему; полная причина указана в примечаниях к заказу.

Покупатель видит Pagar.me only supports payments in Brazilian Real (BRL): заказ в другой валюте, например из-за плагина переключения валют.

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

Возврат для boleto не выполняется: платежи boleto нельзя вернуть через API. Выполните возврат в личном кабинете Pagar.me и зафиксируйте его вручную.

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

Удаление

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

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