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

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

Повернення розраховуються від суми, яку 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.