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, і він ще не оплатив. У примітці вказано ідентифікатор платежу PagBank і середовище. Якщо сторінка оплати спливає без оплати, примітка про це повідомляє, а статус не змінюється.

Processing: платіж підтверджено. Це стандартний статус WooCommerce після оплати; замовлення, що містять лише віртуальні товари для завантаження, переходять у статус «Виконано». У примітці до замовлення вказано суму, спосіб оплати та ідентифікатор списання PagBank, який також є ідентифікатором транзакції замовлення.

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. Успішне повернення додається до приміток замовлення з ідентифікатором списання.

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

PagSeguro та PagBank є торговельними марками їхніх відповідних власників. Цей плагін не афілійований із PagSeguro чи PagBank і не схвалений ними.