VibeFox Windcave for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Аккаунт Windcave: нужна учётная запись мерчанта Windcave с учётными данными REST API: имя пользователя API и API-ключ. Windcave выдаёт их отдельно для тестовой среды UAT (uat.windcave.com) и для производственной среды (sec.windcave.com). Запросите их у службы поддержки Windcave или у вашего менеджера. Ключи PxPay с этим модулем не работают. Способы оплаты, которые вы хотите предлагать (карты, кошельки и другие), должны быть включены в вашем аккаунте Windcave.

Уведомление: ваш магазин должен быть доступен из интернета, чтобы Windcave мог отправить уведомление о платеже. Ничего настраивать в Windcave для этого не нужно.

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

Установка

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

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

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

4. Введите имя пользователя и ключ REST API: данные UAT для тестового режима и данные производственной среды для реальных платежей (см. Настройки).

5. Выберите тип транзакции и способы оплаты, включите Enable/Disable и нажмите Save. Проведите тестовый платёж при включённом Test mode, затем выключите Test mode, чтобы принимать реальные платежи.

При установке модуль создаёт статус заказа Windcave payment on hold. PrestaShop предлагает новый платёжный модуль для всех валют, стран и групп клиентов. Ограничить их можно в Payment > Preferences.

Настройки

Все параметры находятся на странице модуля: Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Пока включён тестовый режим, страница показывает сообщение: Test mode включён: платежи уходят в тестовую среду Windcave UAT, реальные деньги не списываются. Если модуль включён, но для текущего режима не указаны имя пользователя или ключ API, страница предупреждает, что способ оплаты скрыт при оформлении заказа, например: Windcave включён, но имя пользователя или ключ API UAT пусты — способ оплаты скрыт при оформлении заказа. Поле Title не может быть пустым: в этом случае страница показывает Введите название способа оплаты. и ничего не сохраняется.

Windcave

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

Title: название способа оплаты, которое видит покупатель при оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Credit/Debit Card (Windcave). Обязательное поле.

Description: текст, который выводится под способом оплаты при оформлении заказа. По умолчанию: You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

Введите учётные данные REST API, выданные Windcave (имя пользователя и API-ключ, а не ключи PxPay). Производственные и тестовые данные UAT можно сохранить одновременно. Тестовый режим использует только данные UAT, боевой режим — только производственные данные. Раздел содержит ссылку на документацию REST API Windcave.

Test mode: использует тестовую среду Windcave UAT (uat.windcave.com). Реальные деньги не списываются. Новые платежи используют данные UAT. Возвраты и списания всегда отправляются в ту среду, в которой был оплачен заказ. По умолчанию: выключено.

Production API username: имя пользователя REST API для sec.windcave.com.

Production API key: ключ REST API для sec.windcave.com.

UAT API username: имя пользователя REST API для uat.windcave.com (тестовый режим).

UAT API key: ключ REST API для uat.windcave.com (тестовый режим).

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

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

Notification URL: показывает адрес, на который Windcave отправляет уведомление о платеже (Fail-Proof Result Notification). При включённых понятных URL он выглядит так: https://ваш-магазин/module/wcp_windcave_payment_gateway/notification. В Windcave ничего настраивать не нужно: модуль передаёт свои адреса возврата и этот адрес уведомления с каждой платёжной сессией. Адрес должен быть доступен из интернета, иначе заказы подтверждаются только тогда, когда покупатель возвращается с сайта Windcave. Ни возврат покупателя, ни уведомление не подписаны Windcave, поэтому модуль никогда не доверяет им сам по себе: он всегда получает результат сессии через REST API Windcave, используя учётные данные той среды, в которой была создана сессия.

Payment

Transaction type: способ списания платежа. По умолчанию: Purchase.

Payment methods: способы, которые показываются на платёжной странице Windcave: Cards, Account2Account (банковский перевод в Новой Зеландии), Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. Чтобы выбрать несколько, используйте Ctrl или Cmd и клик. Способы должны быть включены в вашем аккаунте Windcave. Оставьте поле пустым, чтобы показывать все способы, включённые в аккаунте. По умолчанию: Cards.

Advanced

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

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

Clean uninstall: при удалении модуля удаляет его настройки и журналы. Платёжные данные, сохранённые с заказами (идентификаторы транзакций Windcave, которые нужны для возвратов), всегда сохраняются. По умолчанию: выключено.

Версия модуля указана внизу страницы.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Credit/Debit Card (Windcave)) с его описанием. В тестовом режиме покупатель также видит Test mode: платежи уходят в тестовую среду Windcave UAT, реальные деньги не списываются. После подтверждения модуль создаёт платёжную сессию Windcave на сумму корзины в валюте корзины и отправляет покупателя на Windcave Hosted Payment Page. Номер корзины передаётся как референс мерчанта вместе с языком магазина и именем, e-mail, телефоном и платёжным адресом покупателя (а также адресом доставки, если корзине нужна доставка). На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ помечается как оплаченный только после подтверждения Windcave: модуль запрашивает у REST API Windcave результат сессии, и когда покупатель возвращается, и когда приходит уведомление от Windcave. Блокировка на уровне корзины гарантирует, что платёж применяется только один раз. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your Windcave payment has been received. Для заказа на удержании (авторизация или платёж, который не совпадает с корзиной) страница показывает Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again.

Если покупатель вернулся после одобренного платежа, но результат ещё не известен, страница Payment confirmation показывает We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. и кнопку Check again. Уведомление создаёт заказ, как только Windcave подтверждает платёж.

Если покупатель вернулся без завершённого платежа, страница оформления заказа показывает одно из этих сообщений. Корзина сохраняется.

Покупатель может повторить попытку с той же корзиной. Новая попытка сначала проверяет предыдущую сессию: если она уже оплачена, заказ создаётся и второй платёж не начинается; если покупатель ни разу не открывал платёжную страницу и корзина не изменилась, его возвращают на ту же страницу. Если предыдущий платёж как раз сейчас подтверждается, покупатель видит Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.

Если Windcave не может начать платёж, покупатель остаётся на странице оформления заказа с коротким сообщением: что Windcave не смог начать платёж с данными этого заказа или что платёжный сервис временно недоступен. Причина записывается в журнал. Если для текущего режима нет учётных данных, покупатель видит This payment method is not available at the moment. Please choose another payment method or contact us.

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

В модуле нет подписок и периодических платежей, сохранённых карт, встроенной формы карты на вашем сайте (покупатель всегда платит на странице Windcave), поддержки API PxPay 2.0, и он не добавляет наценок. Если Windcave добавит наценку, заказ сопоставляется с основной транзакцией.

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

Order statuses

No order yet: покупатель был отправлен на Windcave и не оплатил, Windcave ещё не подтвердил платёж, либо платёж был отклонён, отменён или истёк. Существует только корзина.

Payment accepted: платёж Purchase подтверждён и совпадает с корзиной. Платёж записывается с идентификатором транзакции Windcave, а примечание показывает сумму, идентификатор транзакции, код авторизации, тип карты с замаскированным номером и среду (UAT или производственная).

Windcave payment on hold (authorised): платёж Auth одобрен, но ещё не списан. До списания платёж в заказе не записывается. Примечание объясняет, как его списать или снять резерв.

Windcave payment on hold (does not match): Windcave сообщил сумму, валюту, референс мерчанта или тип транзакции, отличающиеся от корзины (например, корзину изменили в другой вкладке после начала оплаты). Примечание перечисляет расхождения. Для Purchase в валюте корзины платёж записывается с суммой, которую Windcave фактически списал. Проверьте платёж в Windcave Payline перед отправкой и при необходимости сделайте возврат.

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

Если одобренный платёж приходит для отменённого заказа или второй одобренный платёж — для уже существующего заказа, заказ не меняется. Примечание с идентификатором транзакции просит вас вернуть деньги в Windcave Payline (или восстановить отменённый заказ вручную).

Windcave payment block

На странице заказа показывается блок Windcave payment с идентификатором транзакции, идентификатором сессии, типом транзакции и статусом с указанием среды, оплаченной суммой, кодом авторизации и картой, транзакцией списания или отмены, суммой платежа и возвращённой суммой, меткой Test mode (UAT) для тестовых платежей, историей возвратов, всеми сессиями Windcave для корзины и Windcave notes заказа.

Capture (Auth mode)

Для заказа в статусе Windcave payment on hold, у которого авторизация ещё не списана и не снята, блок показывает Capture Windcave payment с суммой. Нажмите её и подтвердите Capture the authorised amount through Windcave now? Авторизованная сумма списывается (сумма заказа, если только платёж не отличается от заказа), заказ переходит в Payment accepted, а платёж записывается с идентификатором транзакции списания. Если Windcave не принимает списание, блок показывает Windcave capture failed: с причиной, причина добавляется в примечания, а заказ остаётся на удержании.

Refunds

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

Для платежа Auth, который не списан, кнопка называется Release authorisation (void), и снять резерв можно только на полную сумму. Частичная сумма вызывает ошибку с просьбой вернуть полную сумму или сначала списать платёж.

Если Windcave отклоняет возврат, блок показывает Windcave declined the refund: с причиной, и возврат не записывается. Если Windcave ещё обрабатывает возврат, блок показывает Windcave has not confirmed the refund yet. See the order notes., и возврат не записывается. Проверьте транзакцию в Windcave Payline: если она одобрена, запишите возврат вручную; если нет — повторите попытку. Повторная попытка того же возврата не отправляется в Windcave дважды.

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

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

Модуль работает с лицензионным ключом VibeFox, полученным на vibefox.net. Блок лицензии License — VibeFox Windcave Payment Gateway — это первый блок в Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure, над настройками. Введите ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-windcave и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (включены английский и русский).

Если ключ не принят, блок объясняет причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте vibefox.net.

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

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

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

Windcave не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и в текущем режиме заполнены оба набора учётных данных: UAT API username и UAT API key в тестовом режиме, Production API username и Production API key в боевом режиме. Страница настроек показывает предупреждение, если их нет. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: модуль ещё не смог получить результат от Windcave. Посмотрите поле Log на странице модуля: ошибки всегда записываются, например когда не удалось проверить сессию. Проверьте, что учётные данные среды платежа сохранены и верны. Проверка повторяется, когда Windcave заново отправляет уведомление (модуль отвечает payment could not be verified yet, retry later с кодом ошибки, чтобы Windcave повторил запрос), когда покупатель нажимает Check again и когда покупатель начинает новый платёж для той же корзины. Ваш сервер должен принимать запросы Windcave на Notification URL, указанный в настройках.

Уведомление отвечает order not found: сессию создал не этот магазин, например сессия другого магазина, который использует тот же аккаунт Windcave. Такое уведомление игнорируется.

В журнале Authentication failed: имя пользователя или ключ REST API неверны либо принадлежат другой среде. Учётные данные UAT работают только в тестовом режиме, производственные — только в боевом. Ключи PxPay не работают.

Покупатель видит, что Windcave не смог начать платёж с данными этого заказа: Windcave отклонил запрос на сессию, например из-за валюты или способа оплаты, не включённого в вашем аккаунте. Точная причина есть в журнале.

Заказ в статусе Windcave payment on hold после оплаты: прочитайте примечания в блоке Windcave payment. Либо платёж — это авторизация Auth, которая ждёт списания, либо оплаченная сумма, валюта или референс мерчанта отличались от корзины. Спишите, отправьте или верните платёж.

Тестовые и реальные платежи: UAT и производственная среда разделены. Каждая сессия проверяется в той среде, в которой была создана, а возвраты и списания идут в среду платежа, даже если вы позже переключите Test mode.

Возврат завершается ошибкой с сообщением о среде: платёж был сделан в UAT или в производственной среде, а учётные данные для этой среды не сохранены. Введите их и повторите попытку.

В блоке заказа нет Capture Windcave payment: кнопка показывается только для заказов в статусе Windcave payment on hold, оплаченных через Auth и ещё не списанных или не снятых, и только сотрудникам, которым разрешено редактировать заказы.

Где искать подробности: ошибки и предупреждения всегда записываются в журнал; включите Debug log, чтобы дополнительно записывать запросы к API и события оплаты.

Удаление

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

Windcave — товарный знак его владельца. Этот модуль не аффилирован с Windcave и не одобрен компанией Windcave.