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 и sandbox API-ключ. Покупатели видят при оформлении заказа пометку 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. Если в этот момент тот же заказ обрабатывается другим запросом, покупателю предлагается подождать немного и попробовать снова.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице 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.