VibeFox Iugu for WooCommerce — Помощь

Требования

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

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

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

Валюта магазина: бразильский реал (BRL). Iugu принимает платежи только в BRL. Способ оплаты скрыт, если в магазине или в заказе на странице Pay for order используется другая валюта, а также для сумм меньше R$ 1,00 (минимум Iugu).

Аккаунт Iugu: нужны два токена API из панели Iugu: один типа "Test" и один типа "Live" (см. раздел «Настройка»). Iugu использует один адрес API для обоих: токен определяет, являются ли счета тестовыми или настоящими. Вебхук в Iugu настраивать не нужно.

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

Установка

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

2. Нажмите Activate.

3. Установите валюту магазина: бразильский реал (BRL) в разделе WooCommerce > Settings > General.

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

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

6. Введите тестовый и рабочий токены API (см. раздел «Настройка»), оставьте Test mode включённым, включите Enable / Disable и сохраните.

7. Оформите тестовый заказ и оплатите его тестовой картой Iugu. Когда всё готово, снимите отметку с Test mode.

Настройка

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

Общие

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

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

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

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

Создайте токены API в Iugu Alia (alia.iugu.com): Settings > API integration > New. Создайте один токен типа "Test" и один типа "Live".

Test mode: Use the test API token (no real charges). По умолчанию: on. Пока тестовый режим включён, при оформлении заказа над описанием выводится SANDBOX — Test mode enabled. No real charges. Проверки статуса и возвраты заказа всегда используют токен того режима, в котором был создан его счёт, поэтому переключение режима не ломает старые заказы.

Test API token: токен API Iugu типа "Test". Используется, пока включён тестовый режим.

Live API token: токен API Iugu типа "Live" (рабочий). Используется, когда тестовый режим выключен. Храните его в секрете.

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

Каждый счёт предписывает Iugu сообщать об изменениях статуса на URL уведомлений вашего магазина, который показан в этом разделе настроек. Он выглядит так: https://your-site/wc-api/webhook_wc_iugu/. В Iugu ничего настраивать не нужно. Дополнительный триггер (gatilho) на уровне аккаунта, указывающий на тот же URL, безвреден. Уведомления не содержат данных об оплате, которым доверяет магазин: счёт всегда заново запрашивается через API Iugu (статус, сумма, валюта) перед изменением заказа.

Плагин реагирует на события Iugu, которые могут изменить статус счёта: invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action и invoices. Для каждого из них он читает счёт и применяет его статус:

paid: заказ отмечается оплаченным после проверки суммы и валюты.

authorized or in_analysis: платёж картой ожидает списания или находится на проверке. Заказ переходит в статус «На удержании».

partially_paid: счёт оплачен частично. Заказ переходит в статус «На удержании».

expired: срок счёта истёк без оплаты. Заказ переходит в статус «Не удался», и покупатель может оплатить снова.

canceled: счёт отменён. Заказ отменяется.

refunded: счёт возвращён в Iugu. Заказ переходит в статус «Возвращён».

chargeback: держатель карты оспорил платёж. Оплаченный заказ переходит в статус «На удержании».

Другие события и счета, не относящиеся к заказам этого магазина, получают ответ OK и игнорируются. Без уведомлений заказ проверяется только тогда, когда покупатель возвращается в магазин со страницы Iugu.

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

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

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

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

Покупатель выбирает способ оплаты (по умолчанию Iugu) и оформляет заказ. Нужен действительный адрес e-mail для счёта. Плагин создаёт счёт Iugu на сумму заказа в BRL со сроком оплаты 3 дня и отправляет покупателя на страницу счёта Iugu. Там покупатель платит кредитной картой, boleto или PIX — теми способами, которые включены в вашем аккаунте Iugu. Имя и e-mail покупателя передаются в Iugu, а также CPF/CNPJ, номер дома и район из полей оформления заказа «Brazilian Market on WooCommerce», если они есть. Телефон и адрес передаются только в формате, который принимает Iugu (бразильские номера телефонов, бразильские адреса с CEP из 8 цифр).

После оплаты покупатель возвращается на страницу «Заказ получен» вашего магазина. Заказ отмечается оплаченным только после подтверждения Iugu: счёт заново запрашивается через API Iugu, когда покупатель возвращается и когда Iugu присылает уведомление. Если покупатель сформировал код boleto или PIX и вернулся до оплаты, заказ переходит в статус «На удержании», пока Iugu не подтвердит платёж. Таймер неоплаченных заказов WooCommerce не отменяет заказы, счёт Iugu по которым ещё открыт.

Если счёт отменён или срок его действия истёк, а заказ ещё можно оплатить, покупатель попадает на страницу Pay for order с сообщением The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. Когда покупатель оплачивает снова, плагин возвращает его к тому же открытому счёту, если сумма не изменилась. Иначе старый счёт отменяется в Iugu и создаётся новый, чтобы один заказ нельзя было оплатить дважды через два открытых счёта. Если старый счёт всё же будет оплачен, платёж по-прежнему сопоставляется с заказом.

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

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

Плагин принимает только разовые платежи. В нём нет формы карты на сайте, сохранённых карт, подписок и регулярных списаний, carnê (бумажных платёжных книжек), разделённых платежей и настроек рассрочки: для рассрочки используйте настройки на странице Iugu. Способы оплаты, которые предлагает страница Iugu, нельзя выбрать в настройках плагина: предлагаются все способы, включённые в вашем аккаунте Iugu.

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

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

Pending payment: счёт создан, покупатель ещё не оплатил.

Processing or Completed: Iugu подтвердил оплату. WooCommerce присваивает обычный статус оплаченного заказа. В примечании к заказу указаны ID счёта Iugu и способ оплаты (кредитная карта, boleto или PIX). ID транзакции — это ID счёта Iugu; на странице заказа он ведёт на счёт в Iugu.

On hold: покупатель сформировал boleto или PIX и вернулся в магазин (платёж ожидается); платёж картой авторизован, но ещё не списан (спишите его в Iugu, и заказ будет выполнен, когда Iugu сообщит, что счёт оплачен); платёж на проверке; счёт оплачен частично; открыт chargeback; или оплаченная сумма либо валюта не совпали с заказом. Платёж, поступивший после отмены заказа, тоже переводит его в «На удержании», а не открывает заказ молча. Примечания к заказу указывают, какой именно случай.

Failed: срок счёта истёк без оплаты. Покупатель может оплатить заказ снова.

Cancelled: счёт отменён в Iugu.

Refunded: счёт, которым был оплачен заказ, возвращён в Iugu.

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Iugu. Возврат отправляется с токеном того режима, в котором был создан счёт.

Credit card: полные или частичные возвраты.

PIX: только полные возвраты.

Boleto: через Iugu не возвращается. Верните деньги покупателю банковским переводом, затем оформите возврат вручную, без кнопки Refund via Iugu.

Возвращать можно только оплаченные счета и не больше суммы, которая ещё доступна к возврату в Iugu. Возврат считается выполненным, только когда Iugu его подтвердит. Если Iugu отклонит возврат или не подтвердит его, WooCommerce покажет ошибку, и возврат не будет записан. Успешный возврат добавляется в примечания к заказу с ID счёта и причиной.

Полный возврат, сделанный в панели Iugu, переводит заказ в статус «Возвращён». Частичные возвраты, сделанные в панели, не импортируются.

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

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

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

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

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

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

Iugu не появляется при оформлении заказа: проверьте, что лицензия активна, Enable / Disable включён и задан токен активного режима: Test API token в тестовом режиме, Live API token в рабочем режиме. Валюта магазина должна быть BRL, а сумма заказа — не меньше R$ 1,00. На странице настроек показывается предупреждение, если токен или валюта неверны.

Платёж прошёл, но заказ остаётся в статусе Pending payment: уведомление от Iugu не дошло до вашего магазина или не удалось его проверить. Включите Debug log и посмотрите WooCommerce > Status > Logs, источник wcp_iugu_gateway. Убедитесь, что ваш сайт доступен из интернета по URL уведомлений, указанному в настройках, и что токен того режима, в котором создан счёт, всё ещё введён. Заказ также проверяется, когда покупатель возвращается в магазин после оплаты.

Notification answers verification failed: счёт не удалось прочитать через API Iugu в этот момент, например из-за сетевой ошибки или неверного токена. Iugu повторит уведомление.

Notification answers invalid invoice id: в уведомлении не было корректного ID счёта. Ничего не меняется.

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

The customer sees "Iugu payments are not available right now": токен API отсутствует или неверен. Проверьте токен активного режима.

Возврат не проходит: прочитайте сообщение. Платежи boleto через Iugu не возвращаются, платежи PIX возвращаются только полностью, и возвращать можно только оплаченные счета. Если Iugu не подтвердил возврат, проверьте счёт в Iugu, прежде чем пробовать снова.

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

Разработчики могут изменить запрос счёта, например ограничить способы оплаты через payable_with, с помощью фильтра wc_igu_invoice_data.

Удаление

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

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