VibeFox Iugu for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

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

Установка

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

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

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

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

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

При установке модуль создаёт два статуса заказа: Awaiting Iugu payment и Iugu payment on hold. PrestaShop предлагает новый способ оплаты для всех валют, стран и групп покупателей. Ограничить их можно в Payment > Preferences. В любом случае Iugu предлагается только для корзин в BRL.

Настройка

Все параметры находятся на странице модуля: Modules > Module Manager > VibeFox Iugu Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница показывает TEST MODE (счета создаются с тестовым токеном API, без реальных списаний) или LIVE. Она предупреждает, если токен активного режима не заполнен (тогда способ оплаты скрыт при оформлении заказа), и если валюта магазина по умолчанию не BRL (тогда Iugu не предлагается для корзин в других валютах).

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: использует тестовый токен API, поэтому реальные списания не производятся. По умолчанию: on. Пока тестовый режим включён, при оформлении заказа над описанием выводится SANDBOX — Test mode enabled. No real charges. Проверки статуса и возвраты заказа всегда используют токен того режима, в котором был создан его счёт, поэтому смена режима не ломает старые заказы.

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

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

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

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

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

Notification URL: каждый счёт сообщает Iugu, что нужно отправлять изменения статуса на этот URL вашего магазина. При включённых ЧПУ-адресах он выглядит так: https://your-shop/module/wcp_iugu_gateway/webhook. В 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: срок действия счёта истёк без оплаты. Ожидающий заказ получает Payment error.

canceled: счёт отменён. Ожидающий заказ отменяется.

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

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

Прочие события и счета, созданные не вашим магазином, получают ответ HTTP 200 и игнорируются без запроса в Iugu. Без уведомлений счёт проверяется только тогда, когда покупатель возвращается в магазин со страницы Iugu.

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

Debug log: записывает запросы и уведомления Iugu в logs/wc_igu_debug.log.php в папке модуля. Открыть файл из браузера нельзя. Токены и данные покупателей не записываются. Ошибки и предупреждения записываются всегда, даже когда переключатель выключен. По умолчанию: off.

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

Delete Data on Uninstall: если включено, при удалении модуля удаляются настройки шлюза и журнал. Заказы, ссылки на счета Iugu, возвраты и статусы заказов модуля всегда сохраняются, поэтому старые заказы продолжают работать после повторной установки. По умолчанию: off.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Iugu) и подтверждает выбор. Требуется действительный адрес электронной почты покупателя. Модуль создаёт счёт Iugu на сумму корзины в BRL со сроком оплаты 3 дня и отправляет покупателя на страницу счёта Iugu. Там покупатель платит кредитной картой, boleto или PIX — способами, включёнными в вашем аккаунте Iugu. В счёте указаны Order # и номер корзины. Имя и e-mail покупателя передаются в Iugu, а также компания и CPF/CNPJ из поля адреса Identification number или VAT number, если они заполнены. Телефон и адрес передаются только в формате, который принимает Iugu (бразильские номера телефонов, бразильские адреса с 8-значным CEP; номер дома передаётся как s/n). На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ помечается как оплаченный только после подтверждения Iugu: счёт заново запрашивается через API Iugu, когда покупатель возвращается, и когда Iugu присылает уведомление. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your payment with Iugu has been received.

Если покупатель создал код boleto или PIX и вернулся до оплаты, заказ создаётся в статусе Awaiting Iugu payment, а на странице подтверждения выводится Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. Заказ переходит в статус Payment accepted, когда Iugu сообщает о поступлении денег: по уведомлению или когда покупатель снова открывает ссылку возврата. Если при возврате покупателя связаться с Iugu ещё не удалось, отображается страница Payment confirmation с текстом We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again., кнопкой Check again и кнопкой Back to checkout. Если счёт заказа отменён или истёк без оплаты, на странице подтверждения выводится Your Iugu payment was not completed. Please contact us about this order.

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

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

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

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

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

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

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

Payment accepted: Iugu подтвердил оплату. Платёж записывается с ID счёта Iugu в качестве ID транзакции, а примечание содержит ID счёта и способ оплаты (кредитная карта, boleto или PIX).

Awaiting Iugu payment: покупатель вернулся с выставленным boleto или PIX. Заказ переходит в статус Payment accepted, когда Iugu сообщает об оплате.

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

Payment error: срок действия счёта ожидающего заказа истёк без оплаты. Если Iugu позже сообщит, что счёт оплачен, заказ перейдёт в статус Payment accepted.

Canceled: счёт ожидающего заказа был отменён в Iugu.

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

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

Блок оплаты Iugu

На странице заказа выводится блок Iugu payment с ID счёта Iugu (со ссылкой на счёт в Iugu), способом оплаты, статусом, суммой, которую списал Iugu, и возвращённой суммой, значком Test mode для тестовых счетов, историей возвратов и Iugu notes заказа.

Возвраты

В блоке Iugu payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Iugu. Подтвердите вопрос Refund this amount through Iugu? This cannot be undone. Для этого нужно право на редактирование заказов. Возврат отправляется с токеном того режима, в котором был создан счёт, поэтому этот токен должен быть заполнен.

Кредитная карта: полные или частичные возвраты.

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

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

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

Модуль не создаёт credit slips. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Iugu.

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Iugu Gateway находится первым на странице Modules > Module Manager > VibeFox Iugu Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-iugu и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для этого модуля. Тексты блока соответствуют языку админ-панели (включены английский и русский).

Если ключ не принят, блок показывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

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

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

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

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

Платёж прошёл, но заказ не создан: уведомление от Iugu не дошло до магазина или не удалось его проверить. Включите Debug log и посмотрите поле Log на странице модуля. Убедитесь, что магазин доступен из интернета по Notification URL и что токен того режима, в котором был создан счёт, всё ещё введён. Счёт также проверяется, когда покупатель возвращается в магазин после оплаты.

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

Notification answers busy: корзину в тот же момент обрабатывал другой запрос, или заказ не удалось создать (например, модуль отключён). Iugu повторяет уведомление. В журнале указана причина.

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

Заказ в статусе Iugu payment on hold: прочитайте Iugu notes в блоке заказа. Платёж картой ожидает списания, платёж на проверке, оплачен частично или оспорен, оплаченная сумма не совпала с корзиной, либо платёж поступил после отмены заказа.

Покупатель видит «Iugu payments are not available right now»: токен API отсутствует или неверен. Проверьте токен активного режима.

Покупатель видит «This order already has an Iugu payment that the store has to review»: более ранний счёт корзины авторизован, находится на проверке или оплачен частично, но заказ создать не удалось. Проверьте счёт в Iugu и журнал.

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

Разработчики могут изменить запрос счёта, например ограничить способы оплаты через payable_with, в хуке actionWcpIuguInvoiceData.

Удаление

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

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