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. Для кожної з них він зчитує рахунок і застосовує його статус:

Інші події та рахунки, що не належать до замовлень цього магазину, отримують відповідь 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. Повернення надсилається з токеном того режиму, в якому створено рахунок.

Повертати можна лише оплачені рахунки і не більше суми, яка ще доступна до повернення в 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.