VibeFox Vindi for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более ранних версиях PHP.

Валюта магазина: бразильский реал (BRL). Vindi принимает оплату только в BRL, поэтому способ оплаты скрыт для корзин в любой другой валюте.

Учётная запись Vindi: нужен API-ключ вашей учётной записи Vindi. Песочница Vindi (sandbox) — это отдельная тестовая учётная запись Vindi со своим ключом. Boleto, PIX и BolePix также должны быть включены в вашей учётной записи Vindi, если вы хотите их предлагать.

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

Установка

1. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Vindi Gateway в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key блока лицензии в верхней части страницы Configure и нажмите Activate (см. раздел Лицензионный ключ).

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

5. Скопируйте URL вебхука из настроек в Vindi (см. Настройки).

6. Включите Enable / Disable и нажмите Save. Проверьте платёж в режиме sandbox, затем отключите Sandbox mode, чтобы принимать реальные платежи.

При установке модуль создаёт два статуса заказа: Awaiting Vindi payment и Vindi payment on hold. PrestaShop предлагает новый платёжный модуль для всех валют, стран и групп клиентов. Вы можете ограничить их в Payment > Preferences; там модуль должен быть разрешён для BRL.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Vindi Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если валюта магазина не BRL или если API-ключ текущего режима пуст. В обоих случаях способ оплаты не показывается при оформлении заказа. При сохранении ключи очищаются от лишних пробелов. Если ни один способ оплаты не выбран, выбирается банковская карта и страница показывает Choose at least one payment method — credit card was selected. Пустой Title не сохраняется: страница показывает Enter a title for the payment method.

Vindi

Enable / Disable: Enable Vindi payments включает или выключает способ оплаты. По умолчанию: выключено.

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 имеют разные адреса и ключи. Каждый платёж запоминает, где был создан его счёт, поэтому проверки, отмены и возвраты всегда выполняются в этой среде.

Sandbox mode: создаёт новые платежи в sandbox Vindi, используя sandbox-app.vindi.com.br и sandbox API-ключ. Покупатели видят при оформлении заказа пометку TEST MODE: Vindi sandbox: no real charges. По умолчанию: включено. Выключите, чтобы принимать реальные платежи.

Live API key: закрытый ключ рабочей учётной записи Vindi. Он отправляется только в API Vindi.

Sandbox API key: закрытый ключ учётной записи sandbox Vindi.

Сохранённые ключи больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved keys: отметьте ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

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

Offered methods: способы оплаты, которые может выбрать покупатель. По умолчанию: банковская карта. Способы также должны быть включены в вашей учётной записи Vindi.

Для boleto, PIX и BolePix нужен CPF или CNPJ покупателя, который запрашивается при оформлении заказа.

Уведомления об оплате (вебхук)

Вебхук сообщает вашему магазину, что счёт оплачен, отменён, отклонён или возвращён. Поле Webhook URL в этом разделе показывает URL. При ЧПУ-адресах он выглядит так: https://your-shop/module/wcp_vindi_gateway/webhook?token=... и содержит секретный токен, созданный модулем. Скопируйте его точно так, как он показан в настройках. В Vindi перейдите в Settings > Webhooks — в рабочей учётной записи и в учётной записи sandbox, добавьте этот URL и выберите следующие события:

Vindi не подписывает свои уведомления, поэтому запросы с отсутствующим или неверным токеном отклоняются, а каждое уведомление лишь заставляет модуль повторно прочитать счёт через API Vindi, прежде чем изменится заказ. Без вебхука платёж картой учитывается только тогда, когда покупатель повторно оформляет заказ с той же корзиной (тогда оплаченный счёт находится и заказ создаётся), а платёж boleto или PIX — когда покупатель снова открывает страницу подтверждения заказа.

Дополнительно

Debug log: записывает вызовы API и уведомления в logs/wc_vdi_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки и предупреждения записываются всегда, даже когда опция выключена. Ключи, токен вебхука и данные покупателей никогда не записываются в журнал. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete data on uninstall: если включено, при удалении модуля удаляются настройки, токен вебхука и журналы. Заказы и ссылки на счета Vindi заказов сохраняются. По умолчанию: выключено.

Оформление заказа

Покупатель выбирает способ оплаты (по умолчанию Vindi). Если предлагается более одного способа, в блоке оплаты показываются Pay with и выбор между банковской картой, boleto, PIX или BolePix. Если предлагаются boleto, PIX или BolePix, в блоке также есть поле CPF or CNPJ. Оно обязательно, если банковская карта не предлагается; в остальных случаях показывается Required for boleto and PIX. Поле заполняется из Identification number или VAT-номера адреса для счёта, если в них есть действительный 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 на сумму корзины в один платёж. В Vindi счёт называется Order # с номером корзины.

Банковская карта: покупатель переходит на страницу счёта Vindi и платит там. На этом этапе заказа ещё нет. Vindi не поддерживает URL возврата для счетов, поэтому покупатель автоматически не возвращается в магазин. Заказ создаётся, когда Vindi подтверждает платёж через вебхук. Если покупатель повторно оформляет заказ с той же корзиной, ему снова предлагается ожидающий счёт, а если он уже оплачен, заказ создаётся сразу.

Boleto, PIX и BolePix: счёт выставляется сразу, заказ создаётся со статусом Awaiting Vindi payment, и покупатель попадает на страницу подтверждения заказа. Там, а также в данных заказа в личном кабинете, раздел Payment показывает QR-код PIX, код PIX для копирования с кнопкой Copy code и срок его действия, а также кнопку Open boleto. Письмо с подтверждением заказа содержит код PIX и ссылку на boleto. Если Vindi не возвращает данные boleto или PIX, счёт отменяется и покупатель видит ошибку.

Заказ отмечается оплаченным только после подтверждения Vindi: модуль читает счёт через API Vindi и проверяет валюту, принадлежность счёта корзине (код корзины и клиент Vindi), а также равенство оплаченной суммы итогу заказа. Страница подтверждения заказа проверяет ожидающий заказ через API повторно, не чаще чем раз в 15 секунд. Когда платёж получен, она показывает Your payment with Vindi has been received. Пока счёт проверяется в Vindi, она показывает We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. Для отменённого заказа она показывает This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.

Новая попытка оплаты той же корзины использует ожидающий счёт Vindi, если способ, сумма и среда совпадают. В противном случае предыдущий счёт отменяется в Vindi до создания нового, поэтому покупатель не может оплатить одну и ту же корзину дважды. Если предыдущий счёт тем временем был оплачен, заказ создаётся и новый счёт не выставляется.

Если Vindi не может начать платёж, покупатель остаётся на оформлении заказа с коротким сообщением, например: проверить CPF / CNPJ, адрес для счёта (для boleto обязательны улица, почтовый индекс, город и штат), e-mail или телефон, либо сообщение о том, что Vindi временно недоступен. Техническая причина записывается в журнал.

Вебхук работает, когда магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

Модуль принимает только единоразовые платежи в один платёж. В нём нет подписок и регулярных списаний, сохранённых карт, рассрочки и формы карты на вашем сайте: карта всегда вводится на странице Vindi.

Заказы и возвраты

Статусы заказа

No order yet: платёж картой начат, но Vindi его ещё не подтвердил. Существует только корзина.

Awaiting Vindi payment: ожидается платёж boleto, PIX или BolePix (примечание Awaiting ... payment at Vindi.). Заказ переходит в Payment accepted, когда Vindi сообщает, что счёт оплачен.

Payment accepted: платёж подтверждён. Он записывается с ID счёта Vindi в качестве ID транзакции, а примечание показывает счёт Vindi, сумму и среду.

Vindi payment on hold: счёт Vindi находится на проверке, оплаченный счёт не соответствует заказу (валюта, сумма, код корзины или клиент Vindi), либо счёт оплачен после отмены заказа. Примечание объясняет причину, и на заказе фиксируется оплаченная сумма. Проверьте заказ и остатки на складе, затем завершите заказ или верните платёж.

Payment error: Vindi отклонил попытку платежа по ожидающему заказу. Примечание показывает причину от эквайера, если она есть. Покупатель всё ещё может оплатить тот же счёт, и последующий платёж переводит заказ в Payment accepted.

Canceled: счёт ожидающего заказа отменён в Vindi. Когда вы отменяете заказ в магазине, его ожидающий счёт Vindi тоже отменяется, и оплатить его становится невозможно. Если это не удаётся, примечание просит отменить счёт в панели Vindi.

Refunded: платёж полностью возвращён через модуль.

Если для уже оплаченного заказа оплачен второй счёт, заказ не меняется. Примечание просит вернуть один платёж в Vindi.

Блок оплаты Vindi

На странице заказа показан блок Vindi payment с счётом и списанием Vindi, средой (с меткой Sandbox для платежей sandbox), способом оплаты, статусом, оплаченной и возвращённой суммой, историей возвратов, всеми Bills of this cart и Vindi notes заказа.

Возвраты

В блоке Vindi payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Vindi. Подтвердите вопрос Refund this amount through Vindi? This cannot be undone. Поддерживаются полные и частичные возвраты платежей картой и PIX. Нужно право редактировать заказы; доступ к страницам модулей не требуется. Возвраты ограничены суммой, которую Vindi фактически списал, поэтому после расхождения можно вернуть не более того, что заплатил покупатель, а не итог заказа. Возврат отправляется в среду платежа (рабочая или sandbox), поэтому API-ключ этой среды должен быть задан. Полный возврат также отменяет счёт в Vindi и переводит заказ в Refunded; частичный возврат статус не меняет. Успешный возврат добавляется в историю возвратов и примечания вместе со списанием Vindi и статусом. Если Vindi или эквайер отклоняет возврат, блок показывает ошибку и возврат не записывается. Возвраты доступны, когда Vindi сообщил, что счёт оплачен.

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

Модуль не создаёт кредитных нот. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Vindi. Возвраты, сделанные в панели Vindi, приходят через вебхук charge_refunded и добавляются в примечания. Статус заказа автоматически не меняется; при необходимости зафиксируйте их в PrestaShop ручным возвратом.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Vindi Gateway — это первый блок на странице Modules > Module Manager > VibeFox Vindi Gateway > Configure, над настройками. Введите ключ в License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-vindi и ссылка 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.

Без активного ключа Vindi не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже созданные счета по-прежнему подтверждаются вебхуком Vindi, а возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в бэк-офисе: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

Vindi не появляется при оформлении заказа: проверьте, что лицензия активна, Enable / Disable включено, валюта корзины BRL, выбран хотя бы один способ в Offered methods, и в текущем режиме задан API-ключ: Sandbox API key в режиме sandbox, Live API key в рабочем режиме. Страница настроек показывает предупреждение, если ключ отсутствует или валюта не BRL. В Payment > Preferences проверьте, что модуль разрешён для BRL, страны покупателя и его группы клиентов.

Платёж прошёл, но заказ не создан или остаётся в статусе Awaiting Vindi payment: вебхук не работает. В Vindi проверьте, что вебхук существует в используемой учётной записи (рабочей или sandbox), что его URL в точности совпадает с показанным в настройках, включая токен, и что выбраны все четыре события.

Вебхук отвечает Forbidden: токен в URL отсутствует или неверен. Скопируйте URL из настроек заново.

Вебхук отвечает Verification failed, retry later: счёт не удалось прочитать через API Vindi (например, API-ключ этой среды был удалён), корзину в тот же момент обновлял другой запрос, либо заказ не удалось создать (например, модуль отключён). Vindi отправит уведомление повторно. Причину покажет журнал.

URL вебхука в браузере показывает Method not allowed: это нормально. URL принимает только запросы от Vindi.

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

Покупатель видит ошибку при оформлении заказа: посмотрите поле Log на странице модуля. Ошибки записываются, даже когда Debug log выключен. Для boleto в адресе для счёта должны быть улица, почтовый индекс, город и штат.

Заказ в статусе Vindi payment on hold: прочитайте примечания в блоке Vindi payment (см. Статусы заказа), затем завершите заказ или верните платёж.

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

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

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Vindi Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data on uninstall включено, настройки, токен вебхука и журналы удаляются. Если выключено, все настройки сохраняются для последующей переустановки. Счета и возвраты Vindi по заказам, а также статусы заказов Awaiting Vindi payment и Vindi payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после переустановки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

Vindi — торговая марка её правообладателя. Этот модуль не аффилирован с Vindi и не одобрен Vindi.