VibeFox PagSeguro for WooCommerce — Помощь

Требования

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

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

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

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

HTTPS: ваш сайт должен быть доступен из интернета по HTTPS, чтобы PagBank мог отправлять уведомления об оплате.

Учётная запись PagBank: рабочий токен для реальных платежей и токен sandbox для проверок. Рабочий токен: войдите в учётную запись PagBank, откройте Venda online > Integrações и нажмите Gerar token; PagBank отправит токен по e-mail. Sandbox: создайте учётную запись sandbox на портале разработчиков PagBank и скопируйте её токен. Токены sandbox и рабочие токены работают только в своей среде.

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите токен sandbox и, для приёма реальных платежей, рабочий токен.

6. Включите Enable / Disable и сохраните настройки. Проводите тестовые платежи с включённым Sandbox Mode, а затем выключите его, чтобы принимать реальные платежи.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > PagSeguro / PagBank. Под заголовком страница показывает текущий режим: SANDBOX MODE (платежи создаются в sandbox PagBank, реальные списания не происходят) или LIVE (платежи создаются с рабочим токеном). Страница предупреждает, если токен текущего режима не задан (тогда способ оплаты скрыт при оформлении заказа), и если валюта магазина не BRL. В списке способов оплаты PagBank помечается как требующий настройки, пока не введён токен текущего режима, а пока включён режим sandbox, отображается метка тестового режима.

Общие

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

Учётная запись PagBank

Раздел объясняет, где получить токены, и содержит ссылки на вашу учётную запись PagBank и на страницу PagBank о токенах.

Sandbox Mode: Enable sandbox/test mode (no real charges). Новые платежи уходят в sandbox PagBank с токеном sandbox, а при оформлении заказа показывается заметка SANDBOX MODE. Проверки статуса и возвраты заказа всегда используют среду и токен, с которыми был создан его платёж. По умолчанию: вкл.

Sandbox token: токен sandbox PagBank. Используется, пока включён режим sandbox.

Production token: рабочий токен PagBank. Используется, когда режим sandbox выключен. Храните его в секрете.

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

Уведомления об оплате

Каждый платёж сообщает PagBank, куда отправлять изменения статуса, поэтому в PagBank ничего настраивать не нужно. В разделе показан URL для уведомлений. Он выглядит так: https://your-site/wc-api/webhook_wc_pagseguro/. Адрес должен быть доступен из интернета по HTTPS.

Уведомления с заголовком x-authenticity-token проверяются токеном среды заказа; уведомление с неверной подписью отклоняется. Содержимому уведомления плагин никогда не доверяет: перед изменением заказа он всегда читает оплату и заказ PagBank через API PagBank (статус, сумму и валюту).

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

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

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

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

Покупатель выбирает способ оплаты (по умолчанию PagSeguro / PagBank) и оформляет заказ. Плагин создаёт в PagBank платёж на точную сумму заказа в BRL одной позицией, Order # с номером заказа и названием вашего магазина, и отправляет покупателя на страницу оплаты PagBank. Имя и e-mail покупателя, CPF или CNPJ из полей плагина Brazilian Market on WooCommerce и бразильский номер телефона подставляются, если они есть в магазине; покупатель может дополнить или исправить их на странице PagBank. Покупатель платит способами, включёнными в вашей учётной записи PagBank, например кредитной картой, PIX или boleto.

Страница оплаты истекает за 5 минут до того, как таймер Hold stock WooCommerce отменит неоплаченный заказ (минимум 10 минут), или через 120 минут, если остатки не резервируются.

После оплаты покупатель возвращается в магазин. Возврат проверяется так же, как уведомление: плагин читает платёж через API PagBank, и один только возврат покупателя никогда не отмечает заказ оплаченным. Оплаченный заказ или платёж, ожидающий подтверждения (boleto, PIX, проверка), ведёт на страницу «Заказ получен»; заказ подтверждается уведомлением, если PagBank его ещё не отправил.

Если оплата не завершилась, покупатель возвращается на страницу Pay for order с сообщением The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. или The payment was declined by PagBank. Please try again with another card or payment method. Если оплата была отменена и вместе с ней заказ, покупатель попадает в корзину с сообщением The PagBank payment was cancelled, so the order was cancelled.

Когда покупатель платит повторно, открытый платёж PagBank используется снова, если сумма и среда те же и он не истекает в течение 10 минут. В противном случае предыдущий платёж деактивируется и больше не может быть оплачен. Оплата, сделанная на предыдущей странице до этого, по-прежнему засчитывается в заказ.

Если PagBank не может начать оплату, покупатель видит короткое сообщение, например PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. или Could not connect to PagBank. Please try again in a moment. Причина, которую сообщает PagBank, добавляется в заметки к заказу.

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

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

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

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

Pending payment: покупатель был отправлен в PagBank и ещё не оплатил. В заметке указаны ID платежа PagBank и среда. Если страница оплаты истекает без оплаты, заметка об этом появляется, а статус не меняется.

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

On hold: сформирован boleto или PIX и ожидается оплата; платёж на проверке; платёж картой авторизован, но не списан (спишите его в PagBank); оплаченная сумма или валюта не совпадают с заказом; либо платёж поступил после того, как WooCommerce отменил неоплаченный заказ (проверьте остатки, затем завершите заказ или верните платёж в PagBank). Заметка к заказу объясняет причину.

Failed: платёж отклонён. Покупатель может оплатить заказ повторно со страницы Pay for order.

Cancelled: платёж отменён, например просроченный boleto или PIX.

Refunded: платёж полностью возвращён в панели PagBank.

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

Возвраты

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

Возвраты, оформленные в панели PagBank, не импортируются как строки возврата WooCommerce. Полный возврат переводит заказ в статус «Возвращён»; частичный возврат добавляет заметку с возвращённой суммой, и вы можете вручную добавить возврат к заказу.

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

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

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

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

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

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

PagBank не появляется при оформлении заказа: проверьте, что лицензия активна, включён Enable / Disable, задан токен текущего режима (Sandbox token в режиме sandbox, Production token в рабочем режиме) и валюта магазина — BRL. В каждом из этих случаев на странице настроек показывается предупреждение.

Оплата прошла, но заказ остаётся в статусе «Ожидает оплаты»: PagBank ещё не сообщил об оплате, а покупатель не вернулся в магазин. Заказ обновится, как только придёт уведомление. Проверьте, что ваш сайт доступен из интернета по HTTPS, и посмотрите WooCommerce > Status > Logs, источник wcp_pagseguro_gateway.

Уведомление отвечает Invalid signature: x-authenticity-token не совпадает с токеном среды, в которой был оплачен заказ. Проверьте, что в настройках указан правильный токен.

Уведомление отвечает Verification failed, retry later: API PagBank недоступен, токен среды заказа отсутствует или заказ в тот же момент обновлялся другим запросом. PagBank повторит уведомление.

Уведомление отвечает Order not found: заказа нет в этом магазине или он оплачен другим способом оплаты. Ничего не меняется.

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

Покупатель видит PagBank payments are temporarily unavailable: токен текущего режима отсутствует или был отклонён PagBank.

Покупатель видит PagSeguro/PagBank only accepts payments in Brazilian Real (BRL): заказ оформлен в другой валюте.

Заказ в статусе On hold с заметкой Amount/currency does not match: PagBank сообщил о платеже, сумма или валюта которого отличается от суммы заказа, например потому что заказ был изменён после создания страницы оплаты. Сравните суммы в PagBank и завершите заказ или вручную сделайте возврат.

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

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

Удаление

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

PagSeguro и PagBank являются товарными знаками их соответствующих владельцев. Этот плагин не связан с PagSeguro или PagBank и не одобрен ими.