VibeFox Vindi for WooCommerce — Допомога

Вимоги

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

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

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

Валюта магазину: бразильський реал (BRL). Vindi приймає платежі лише в BRL, тому спосіб оплати приховується для будь-якої іншої валюти.

Обліковий запис Vindi: потрібен API-ключ вашого облікового запису Vindi. Vindi sandbox — це окремий тестовий обліковий запис із власним ключем. Boleto, PIX і BolePix також мають бути увімкнені у вашому обліковому записі Vindi, якщо ви хочете їх пропонувати.

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

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

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

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

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

4. Вставте Sandbox API key і, коли будете готові, Live API key. Оберіть Offered methods.

5. Скопіюйте URL вебхука з налаштувань до Vindi (див. розділ «Конфігурація»).

6. Увімкніть Enable / Disable і збережіть. Перевірте платіж у режимі sandbox, а потім приберіть позначку Sandbox mode, щоб приймати реальні платежі.

Конфігурація

Усі налаштування розміщені на одній сторінці: WooCommerce > Settings > Payments > Vindi. Над полями сторінка попереджає, якщо валюта магазину не BRL або якщо API-ключ поточного режиму порожній. В обох випадках спосіб оплати не відображається на оформленні замовлення. У списку способів оплати Vindi позначено як такий, що потребує налаштування, доки в поточному режимі немає API-ключа. Під час збереження ключі очищаються від пробілів, а якщо не вибрано жодного способу оплати, обирається кредитна картка і сторінка показує Choose at least one payment method — credit card was selected.

Загальні

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

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

Description: текст під способом оплати на оформленні замовлення. За замовчуванням: Pay by credit card on the secure Vindi page, or by boleto / PIX.

API-ключі

Створіть ключі в панелі Vindi у розділі Settings > API keys: на app.vindi.com.br для робочого режиму та на sandbox-app.vindi.com.br для sandbox. Кожне замовлення запам'ятовує, де створено його рахунок, тож перевірки, скасування та повернення завжди виконуються в цьому середовищі.

Sandbox mode: Create new payments in the Vindi sandbox використовує sandbox-app.vindi.com.br з API-ключем sandbox. Покупці бачать на оформленні замовлення примітку TEST MODE: Vindi sandbox: no real charges. За замовчуванням: on. Приберіть позначку, щоб приймати реальні платежі.

Live API key: закритий ключ робочого облікового запису Vindi. Він надсилається лише до API Vindi.

Sandbox API key: закритий ключ тестового облікового запису Vindi sandbox.

Способи оплати

Offered methods: способи оплати, які покупець може обрати. За замовчуванням: credit card. Способи також мають бути увімкнені у вашому обліковому записі Vindi.

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

Вебхук повідомляє вашому магазину, що рахунок оплачено, скасовано або повернуто. Цей розділ налаштувань показує URL вебхука. Він має вигляд https://your-site/wc-api/webhook_wc_vindi/?token=... і містить секретний токен, створений плагіном. Скопіюйте його точно так, як показано в налаштуваннях. У Vindi перейдіть до Settings > Webhooks — і в робочому, і в тестовому обліковому записі sandbox — додайте цей URL і виберіть такі події:

Запити з відсутнім або невірним токеном відхиляються. Кожне сповіщення лише змушує плагін знову зчитати рахунок через API Vindi, перш ніж змінюватиметься замовлення. Без вебхука платежі карткою, boleto та PIX підтверджуються лише тоді, коли покупець відкриває сторінку «Замовлення отримано».

Додатково

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

Delete data on uninstall: Remove the settings, webhook token and logs when the plugin is deleted. За замовчуванням: off.

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

Покупець обирає спосіб оплати (за замовчуванням Vindi). Коли пропонується більше одного способу, блок оплати показує Pay with і вибір між кредитною карткою, boleto, PIX або BolePix. Коли пропонується boleto, PIX або BolePix, блок також містить поле CPF or CNPJ. Воно обов'язкове, якщо пропонуються лише ці способи; інакше показується Required for boleto and PIX. Номер перевіряється за контрольними цифрами. У класичному оформленні поле не показується, якщо активний Brazilian Market on WooCommerce, оскільки цей плагін уже запитує CPF / CNPJ. Тоді використовуються його CPF / CNPJ, номер будинку та район. Якщо чогось бракує, покупець бачить Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. або Please enter your CPF or CNPJ — it is required for boleto and PIX.

Коли замовлення розміщується, плагін створює для нього клієнта Vindi на основі платіжних даних і рахунок Vindi на суму замовлення в один платіж.

Credit card: покупця надсилають на сторінку рахунку Vindi, де він і платить. Vindi не має URL повернення для рахунків, тож покупець автоматично не повертається до магазину. Замовлення підтверджується вебхуком або коли покупець відкриває сторінку «Замовлення отримано». Поки оплату не завершено, ця сторінка та замовлення в розділі My account показують Your payment has not been completed yet. і кнопку Pay at Vindi.

Boleto, PIX і BolePix: рахунок виставляється одразу, замовлення отримує статус «На утриманні», а покупець потрапляє на сторінку «Замовлення отримано». Там і в My account > Orders розділ Payment показує QR-код PIX, код PIX для копіювання з кнопкою Copy code і термін його дії, а також кнопку Open boleto. Лист покупцю про замовлення на утриманні та лист з рахунком містять код PIX і посилання на boleto.

Замовлення позначається оплаченим лише після підтвердження Vindi: плагін зчитує рахунок через API Vindi та перевіряє, що він належить замовленню (код замовлення та клієнт Vindi), а оплачена сума дорівнює сумі замовлення.

Покупець може повторно оплатити неоплачене замовлення зі сторінки Pay for order. Якщо спосіб оплати, сума та середовище ті самі, чинний очікуваний рахунок Vindi використовується повторно. Інакше він скасовується у Vindi перед створенням нового, тож покупець не може двічі оплатити те саме замовлення. Якщо попередній рахунок тим часом оплачено, замовлення позначається оплаченим і новий рахунок не створюється.

Якщо Vindi не може розпочати платіж, покупець бачить коротке повідомлення, наприклад із проханням перевірити CPF / CNPJ, платіжну адресу, e-mail або телефон, чи повідомлення, що Vindi тимчасово недоступний. Якщо в цей момент те саме замовлення обробляється іншим запитом, покупцеві пропонують почекати мить і спробувати ще раз.

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

Плагін приймає лише разові платежі одним платежем. Він не підтримує підписки та регулярні списання, збережені картки, розстрочку і форму картки на вашому сайті: картка завжди вводиться на сторінці Vindi.

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

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

Pending payment: розпочато платіж карткою, і Vindi його ще не підтвердив.

On hold: платіж boleto, PIX або BolePix очікує (примітка Awaiting ... payment at Vindi.), або рахунок Vindi перевіряється.

Processing or Completed: платіж підтверджено. Статус встановлюється стандартним для WooCommerce способом: «Обробляється» або «Виконано» для замовлень, які містять лише віртуальні товари для завантаження. Примітка до замовлення показує рахунок Vindi, суму та середовище. ID транзакції — це ID рахунку Vindi.

On hold after payment: оплачений рахунок не відповідає замовленню (сума, код замовлення або клієнт Vindi), або рахунок було оплачено після скасування замовлення. Примітка до замовлення пояснює причину. Перевірте замовлення та запаси, а потім завершіть замовлення або поверніть платіж.

Failed: Vindi відхилив спробу оплати. Примітка показує причину від банку-еквайра, якщо вона є. Покупець усе ще може оплатити той самий рахунок, і пізніший платіж завершує замовлення.

Cancelled: рахунок скасовано у Vindi, або замовлення скасовано вами, покупцем чи через тайм-аут резервування запасів WooCommerce. Коли замовлення скасовується в магазині, його очікуваний рахунок Vindi також скасовується, тож оплатити його вже не можна. Якщо це неможливо, примітка попросить вас скасувати рахунок у панелі Vindi. Перш ніж тайм-аут резервування запасів скасує замовлення, рахунок перевіряється: якщо його тим часом оплачено, замовлення позначається оплаченим.

Якщо другий рахунок оплачено за вже оплачене замовлення, замовлення не змінюється знову. Примітка попросить вас повернути один платіж у Vindi.

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Vindi. Підтримуються повні та часткові повернення платежів карткою та PIX. Повне повернення також скасовує рахунок у Vindi. Повернення надсилається в середовищі платежу (робочому або sandbox), тому API-ключ цього середовища має бути заданий. Успішне повернення додається до приміток замовлення разом зі списанням Vindi та статусом. Якщо Vindi або банк-еквайр відхиляють повернення, WooCommerce показує помилку і повернення не реєструється.

Vindi не може повертати платежі boleto. Плагін показує Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.

Повернення, зроблені в панелі Vindi, надходять через вебхук charge_refunded і додаються до приміток замовлення. Вони не реєструються автоматично як повернення WooCommerce. За потреби створіть ручне повернення в WooCommerce, не використовуючи Refund via Vindi.

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

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

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

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

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

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

Vindi не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено, валюта магазину — BRL, принаймні один спосіб вибрано в Offered methods, а в поточному режимі є API-ключ: Sandbox API key у режимі sandbox, Live API key у робочому режимі. Сторінка налаштувань показує попередження, якщо ключ відсутній або валюта не BRL.

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

Вебхук відповідає Forbidden: токен в URL відсутній або невірний. Скопіюйте URL з налаштувань ще раз.

Вебхук відповідає Verification failed, retry later або Order busy, retry later: рахунок не вдалося прочитати через API Vindi (наприклад, API-ключ цього середовища було видалено), або замовлення в цей момент оновлювалося іншим запитом. Vindi надішле сповіщення знову.

Покупець бачить This payment method is temporarily unavailable: Vindi відхилив API-ключ. Перевірте ключ поточного режиму.

Покупець бачить помилку під час розміщення замовлення: відкрийте примітки до замовлення або журнал у WooCommerce > Status > Logs, джерело wcp_vindi_gateway. Помилки записуються, навіть коли Debug log вимкнено. Для boleto в платіжній адресі мають бути вулиця, поштовий індекс, місто та область.

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

Старі замовлення sandbox після переходу на робочий режим: кожне замовлення зберігає середовище свого рахунку. Перевірки, скасування та повернення замовлень sandbox і далі використовують ключ sandbox, доки він є в налаштуваннях.

Повернення не виконується: прочитайте повідомлення. Платежі boleto не можна повернути через Vindi, а API-ключ середовища платежу має бути заданий.

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

Видалення

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

Vindi є торговою маркою її власника. Цей плагін не пов'язаний із Vindi і не схвалений Vindi.