VibeFox Pagar.me for WooCommerce — Допомога

Вимоги

WordPress: 6.0 або новіша версія.

WooCommerce: 8.0 або новіша версія, встановлений і активний. Плагін не активується без нього.

PHP: 8.0 або новіша версія.

Валюта: бразильський реал (BRL). Спосіб оплати приховується, якщо валюта магазину (або на сторінці Pay for order — валюта замовлення) не BRL.

Обліковий запис Pagar.me: вам потрібні секретні ключі вашого облікового запису Pagar.me: тестовий (sk_test_...) і для роботи в бойовому режимі — робочий (sk_...). Вони знаходяться в панелі Pagar.me у розділі Development > Keys. Використовуються лише секретні ключі; публічний ключ (pk_...) не потрібен. Пропонувати можна лише ті способи оплати, які увімкнені у вашому обліковому записі Pagar.me.

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

Встановлення

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, оберіть ZIP-архів плагіна і натисніть Install Now. Також можна завантажити папку wcp_pagarme_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Pagar.me > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії у верхній частині сторінки і натисніть Activate.

5. Введіть тестовий секретний ключ, а під час переходу в робочий режим — робочий секретний ключ.

6. Створіть вебхук у панелі Pagar.me з URL, який показано в налаштуваннях (див. розділ «Налаштування»).

7. Увімкніть Enable / Disable і збережіть. Здійснюйте тестові платежі з увімкненим Test mode, а потім вимкніть його, щоб приймати реальні платежі.

Налаштування

Усі налаштування розміщені на одній сторінці: WooCommerce > Settings > Payments > Pagar.me. Під заголовком сторінка показує поточний режим: TEST MODE (платежі створюються з тестовим секретним ключем, реальних списань немає) або LIVE. Вона попереджає, якщо немає секретного ключа поточного режиму (тоді спосіб оплати приховано на оформленні замовлення), якщо тестовий ключ не починається з sk_test_, якщо робочий ключ не починається з sk_ або є тестовим, і якщо валюта магазину не BRL. У списку способів оплати Pagar.me позначено як такий, що потребує налаштування, доки не введено ключ поточного режиму, а поки тестовий режим увімкнено, відображається відповідна позначка.

Загальні

Enable / Disable: Enable Pagar.me payments вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачать покупці під час оформлення замовлення. За замовчуванням: Pagar.me.

Description: текст під способом оплати на сторінці оформлення замовлення. За замовчуванням: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

API-ключі

Скопіюйте секретні ключі з панелі Pagar.me: Development > Keys. Pagar.me використовує одну адресу API для тестових і робочих платежів; ключ визначає, чи є платіж тестовим або реальним.

Test mode: Use the test secret key (no real charges). Поки тестовий режим увімкнено, на оформленні замовлення показується примітка TEST MODE. Перевірки статусу та повернення замовлення завжди використовують ключ того режиму, в якому створено його платіж. За замовчуванням: увімкнено.

Test secret key: тестовий секретний ключ Pagar.me (sk_test_...). Використовується, поки тестовий режим увімкнено.

Live secret key: робочий секретний ключ Pagar.me (sk_...). Використовується, коли тестовий режим вимкнено. Тримайте його в таємниці.

Єдиний секретний ключ версії 1.0 переноситься автоматично: тестовий ключ потрапляє в Test secret key, і тестовий режим вмикається; інакше він лишається робочим ключем, а тестовий режим вимикається.

Сторінка оплати

Payment methods: способи, які пропонуються на сторінці оплати Pagar.me. Обирайте лише ті, що увімкнені у вашому обліковому записі Pagar.me. За замовчуванням: Credit card, PIX і Boleto.

Boleto due in (days): кількість днів до терміну оплати boleto, від 1 до 30. Замовлення залишається On hold, доки Pagar.me не підтвердить платіж. За замовчуванням: 3.

Сповіщення про оплату (вебхук)

У панелі Pagar.me відкрийте Settings > Webhooks і створіть вебхук з URL із цього розділу. Він має такий вигляд: https://your-site/wc-api/webhook_wc_pagarme/. Скопіюйте його точно так, як показують налаштування.

Оберіть ці події:

Вебхук не потребує пароля чи підпису. Його вміст ніколи не вважається достовірним: магазин бере з нього лише ID замовлення Pagar.me і зчитує це замовлення через API Pagar.me з ключем того режиму, в якому його створено. Сповіщення про замовлення інших магазинів у тому самому обліковому записі Pagar.me ігноруються. Без вебхука PIX і boleto, оплачені пізніше, підтверджуються лише тоді, коли покупець повертається до магазину.

Додатково

Debug log: Log API requests and notifications записує деталі до WooCommerce > Status > Logs, джерело wcp_pagarme_gateway. Помилки записуються завжди. Журнали не містять ключів і даних покупців. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. За замовчуванням: вимкнено.

Оформлення замовлення

Покупець обирає спосіб оплати (за замовчуванням Pagar.me) і оформлює замовлення. Потрібна дійсна електронна адреса для рахунку. Плагін створює замовлення Pagar.me на суму в BRL з позиціями замовлення, доставкою та комісіями (або однією позицією Order # з номером замовлення, якщо позиції не можуть точно скластися) і надсилає покупця на сторінку оплати Pagar.me. Ім'я, електронна адреса покупця, а для Бразилії також телефон і адреса для рахунку передаються в Pagar.me. CPF або CNPJ береться з полів плагіна Brazilian Market on WooCommerce, якщо вони є; інакше покупець вводить його на сторінці Pagar.me.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Pagar.me: магазин зчитує замовлення Pagar.me через API, а сплачена сума і валюта мають збігатися із замовленням. Оплата карткою, PIX або boleto позначає замовлення оплаченим. Виставлений, але ще не оплачений PIX або boleto переводить замовлення на утримання, доки Pagar.me не підтвердить платіж через вебхук.

Якщо покупець повернувся без оплати, або платіж було відхилено чи скасовано, він потрапляє на сторінку Pay for order з повідомленням The Pagar.me payment was not completed. You can pay the order below. або The Pagar.me payment was declined or canceled. You can try again below.

Коли покупець платить знову, відкрита сторінка оплати Pagar.me використовується повторно, якщо сума і режим ті самі; інакше вона закривається в Pagar.me, перш ніж створюється нова. Якщо попередню спробу тим часом оплачено, або її PIX чи boleto ще очікує, замовлення оновлюється без нового платежу. Якщо попередню сторінку не вдається закрити, вона залишається пов'язаною із замовленням, тож платіж, здійснений на ній, усе одно буде зафіксовано.

Якщо Pagar.me не може розпочати платіж, покупець бачить коротке повідомлення, наприклад Could not connect to Pagar.me. Please try again in a moment., або повідомлення Pagar.me про некоректні платіжні дані. Технічна причина додається до приміток замовлення.

Спосіб оплати працює на класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

Плагін не має форми для введення картки в оформленні замовлення, збережених карток, підписок чи регулярних платежів, правил розстрочки, розподілених платежів (маркетплейс), платежів картою лише з авторизацією та інтеграції з Pagar.me Hub.

Замовлення та повернення коштів

Статуси замовлення

Pending payment: покупця було перенаправлено до Pagar.me, і він ще не оплатив або не створив PIX чи boleto. Примітка показує ID замовлення Pagar.me і режим.

Processing: платіж підтверджено. Це стандартний статус WooCommerce після оплати; замовлення лише з віртуальними товарами для завантаження переходять у статус Completed. Примітка до замовлення показує ID замовлення Pagar.me і спосіб оплати. ID транзакції — це ID замовлення Pagar.me (or_...).

On hold: виставлено PIX або boleto (або платіж карткою перебуває на перевірці) і він очікує оплати; або boleto оплачено лише частково; або оплачена сума чи валюта відрізняються від замовлення; або платіж надійшов після скасування замовлення; або замовлення оплачено в Pagar.me після того, як покупець змінив спосіб оплати; або для оплаченого замовлення відкрито оскарження (chargeback). Примітка до замовлення пояснює причину. Перегляньте замовлення і переведіть його в статус Processing, або поверніть платіж у Pagar.me.

Failed: платіж не вдався, або замовлення Pagar.me було скасовано чи прострочено (наприклад, неоплачений boleto). Перевести неоплачене замовлення в статус Failed може лише остання спроба. Покупець може оплатити знову.

Refunded: платіж повернено або скасовано в Pagar.me.

Кожен статус Pagar.me застосовується один раз, тож повторні вебхуки або повернення не додають приміток, листів і списань запасів. Оплачене замовлення ніколи не повертається до статусу очікування чи невдачі, а скасоване або повернене замовлення ніколи не відкривається знову. Якщо оплачено друге замовлення Pagar.me для того самого замовлення WooCommerce, примітка просить повернути дублікат у панелі Pagar.me.

Повернення коштів

Відкрийте замовлення, натисніть Refund, введіть суму і натисніть Refund via Pagar.me (на кнопці відображається назва вашого способу оплати). Підтримуються повні та часткові повернення платежів карткою та PIX — у межах суми, яку ще можна повернути в Pagar.me. Повернення надсилається з ключем того режиму, в якому було здійснено платіж. Повернення фіксується лише після підтвердження Pagar.me; інакше WooCommerce показує помилку, наприклад Pagar.me refused the refund: ... або Pagar.me did not confirm the refund, і повернення не зберігається. Успішне повернення додається до приміток замовлення з ID списання.

Платежі boleto можна повернути лише на банківський рахунок покупця. Поверніть їх у панелі Pagar.me, а потім вручну зафіксуйте повернення у WooCommerce, не використовуючи Refund via Pagar.me.

Повне повернення або скасування, зроблене в панелі Pagar.me, надходить через вебхук і переводить замовлення у статус Refunded. Оскарження додає примітку і переводить замовлення Processing або Completed на утримання.

Ліцензійний ключ

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

Один ключ працює на одному домені. Видалення ключа з сайту не звільняє слот домену. Звільніть слот в обліковому записі на vibefox.net.

Без активного ключа Pagar.me не показується покупцям на оформленні замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Авторизовані менеджери магазину і далі бачать спосіб оплати з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати й протестувати плагін до купівлі ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються: платежі, що вже розпочато, і далі підтверджуються, а повернення працюють.

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

Усунення несправностей

Pagar.me не з'являється на оформленні замовлення: перевірте, що ліцензія активна, увімкнено Enable / Disable, задано секретний ключ поточного режиму (Test secret key у тестовому режимі, Live secret key у робочому) і валюта магазину — BRL. Сторінка налаштувань показує попередження в кожному з цих випадків.

Платіж пройшов, але замовлення залишається в статусі Pending payment або On hold: вебхук не працює. У панелі Pagar.me перевірте, що вебхук існує для облікового запису й режиму, які ви використовуєте, що його URL точно збігається з показаним у налаштуваннях і що вибрано перелічені вище події. Замовлення також перевіряється, коли покупець повертається до магазину.

Вебхук відповідає verification failed, retry later: магазин не зміг зчитати замовлення Pagar.me через API, наприклад тому що ключа цього режиму немає або API не відповів. Pagar.me повторює вебхук.

Вебхук відповідає busy, retry later: замовлення в ту саму мить оновлювалося іншим запитом. Pagar.me повторює вебхук.

Вебхук відповідає unknown order: замовлення Pagar.me створене не цим магазином, наприклад це замовлення іншого магазину в тому самому обліковому записі. Нічого не змінюється.

Покупець бачить This order is already being processed: вебхук або повернення покупця в ту саму мить оновлювали замовлення. Покупець може спробувати знову через мить.

Покупець бачить Pagar.me payments are not available right now: секретний ключ неправильний або відсутній. Перевірте ключ поточного режиму.

Покупець бачить Pagar.me could not start the payment: Pagar.me відхилив платіжні дані. Повідомлення вказує на проблему; повна причина є в приміток до замовлення.

Покупець бачить Pagar.me only supports payments in Brazilian Real (BRL): замовлення в іншій валюті, наприклад через плагін перемикання валют.

Замовлення On hold після оплати: прочитайте примітку до замовлення. PIX або boleto очікує оплати, сплачена сума чи валюта відрізнялися, або платіж надійшов після скасування замовлення.

Повернення для boleto не виконується: платежі boleto не можна повернути через API. Поверніть їх у панелі Pagar.me і зафіксуйте повернення вручну.

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

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте і видаліть плагін на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу та журнали плагіна видаляються лише тоді, коли була увімкнена опція Delete data on uninstall. Інакше вони зберігаються для подальшого повторного встановлення. Наявні замовлення зберігають свої примітки про оплату, ID транзакцій і дані Pagar.me.

Pagar.me є торговою маркою її власника. Цей плагін не афілійований з Pagar.me і не схвалений Pagar.me.