VibeFox Flow for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

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

Валюта: чилийский песо (CLP) или доллар США (USD). Для корзин в других валютах способ оплаты скрыт на этапе оформления заказа. Для CLP установите точность валюты CLP равной 0 в разделе International > Localization > Currencies, так как Flow списывает целые песо.

Учётная запись Flow: нужны API Key и Secret Key вашей учётной записи Flow, в Flow в разделе Mis datos, Datos técnicos. Для тестов создайте отдельную тестовую учётную запись на sandbox.flow.cl и используйте её ключи. Ключи тестовой и рабочей среды различаются. В учётной записи Flow ничего настраивать не нужно.

Публичный сайт: URL подтверждения, возврата покупателя и возврата средств вашего магазина должны быть доступны из интернета, без защиты паролем и без межсетевого экрана, блокирующего Flow. Режим обслуживания магазина их не блокирует.

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

Установка

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

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Flow Gateway в списке модулей и нажмите Configure.

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

4. Введите тестовые API Key и Secret Key, включите Enable / Disable, нажмите Save и оформите тестовый заказ.

5. Чтобы принимать реальные платежи, заполните рабочие ключи и выключите Sandbox mode.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Flow Gateway > Configure. У каждого раздела с полями есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если ключи текущего режима пусты (тогда Flow скрыт на этапе оформления заказа), если валюта магазина по умолчанию не CLP и не USD и если у валюты CLP есть десятичные знаки (установите её точность равной 0, чтобы цены, итоги и возвраты совпадали точно). В тестовом режиме она показывает Sandbox mode — payments go to sandbox.flow.cl, no real money is charged.

Flow.cl

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

Title: название способа оплаты, которое видит покупатель на этапе оформления заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Flow. Обязательно.

Description: текст под способом оплаты на этапе оформления заказа. По умолчанию: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.

API-ключи Flow

Скопируйте API Key и Secret Key из своей учётной записи Flow (Mis datos, Datos técnicos): рабочие ключи — на www.flow.cl, тестовые — на sandbox.flow.cl (отдельная тестовая учётная запись).

Sandbox mode: использует тестовую среду Flow (sandbox.flow.cl) и тестовые ключи. В тестовом режиме реальные деньги не списываются. По умолчанию: on. Выключите его и заполните рабочие ключи, чтобы принимать реальные платежи. Возвраты всегда выполняются в той среде, в которой был оплачен заказ.

Sandbox API Key: API Key вашей учётной записи sandbox.flow.cl.

Sandbox Secret Key: Secret Key вашей учётной записи sandbox.flow.cl. Он используется для подписи каждого запроса.

Live API Key: API Key вашей учётной записи www.flow.cl.

Live Secret Key: Secret Key вашей учётной записи www.flow.cl. Храните его в секрете.

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

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

Уведомления

Модуль отправляет три URL в Flow с каждым платежом и возвратом, поэтому в учётной записи Flow ничего настраивать не нужно. В поле Flow URLs этого раздела они перечислены. При включённых понятных URL они выглядят так:

Подтверждение содержит только токен платежа. Модуль находит токен среди платежей, которые он создал, запрашивает у Flow статус платежа подписанным запросом в той среде, где платёж был создан, и применяет только ответ Flow. Платёж, который этот магазин не создавал, отклоняется без запроса к Flow. Без подтверждения заказ создаётся, когда покупатель возвращается из Flow.

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

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

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

Delete data on uninstall: если включено, удаление модуля удаляет его настройки и журнал. Данные Flow, сохранённые в заказах, остаются. По умолчанию: off.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Flow) и видит описание. В тестовом режиме показывается SANDBOX MODE — платежи идут в тестовую среду Flow, реальных списаний нет. После подтверждения модуль создаёт платёж Flow на сумму корзины в валюте корзины с назначением Cart #, номером корзины и названием магазина, и отправляет покупателя на платёжную страницу Flow. E-mail покупателя передаётся в Flow. Там покупатель выбирает способ оплаты, включённый в вашей учётной записи Flow. На этом этапе заказа ещё нет.

После оплаты покупатель возвращается в ваш магазин. Заказ помечается как оплаченный только после подтверждения Flow: подтверждением или подписанным запросом статуса при возвращении покупателя. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с Your payment with Flow has been received. Если покупатель создал купон Servipag или Multicaja, заказ создаётся в статусе Awaiting Flow payment, а на странице показано Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. Если оплата заказа по купону потом не прошла или отменена, на странице показано Your Flow payment was not completed. Please contact us about this order. Если сумма не совпала, на странице показано Your Flow payment was received and is being reviewed by the shop.

Если Flow недоступен, когда покупатель возвращается, или в этот момент заказ создаёт другой запрос, страница Payment confirmation просит покупателя не платить повторно и предлагает Check again и Back to checkout.

Если платёж отклонён, покупатель возвращается к оформлению заказа с сообщением Your Flow payment was rejected. Please try again or choose another payment method. Если покупатель ушёл со страницы Flow, не заплатив, сообщение: The Flow payment was not completed. You can try again or choose another payment method. Если результат не удалось проверить, сообщение: We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. Корзина сохраняется, и каждая новая попытка создаёт новый платёж Flow, привязанный к корзине.

Если Flow не может начать платёж, покупатель остаётся на оформлении заказа с коротким сообщением, например Could not connect to Flow. Please try again in a moment. Подробности записаны в журнале.

Если купон в корзине перестаёт действовать между оплатой и её подтверждением, PrestaShop удаляет его из заказа. Заказ тогда переходит в статус Flow payment on hold с заметкой, потому что покупатель заплатил цену со скидкой.

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

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

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

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

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

Awaiting Flow payment: покупатель создал купон на оплату Servipag или Multicaja. Заказ переходит в статус Payment accepted, когда Flow подтвердит платёж.

Flow payment on hold: Flow сообщил сумму или валюту, отличающиеся от итога заказа (например, корзина была изменена после начала оплаты), купон был удалён или платёж поступил для отменённого заказа. Списанный Flow платёж записывается, а заметка объясняет ситуацию. Проверьте заказ и отправьте его или сделайте возврат платежа.

Payment error: Flow отклонил платёж по купону для заказа в ожидании.

Canceled: платёж по купону для заказа в ожидании был аннулирован в Flow.

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

Если для уже оплаченного заказа поступает ещё один платёж, заказ не меняется. Заметка просит вернуть дубликат в вашей учётной записи Flow. Заказ с полным возвратом никогда не открывается заново.

Блок платежа Flow

На странице заказа показан блок Flow payment с номером заказа Flow и способом оплаты, ссылкой commerceOrder, статусом платежа, оплаченной и возвращённой суммой, значком Sandbox для тестовых платежей, историей возвратов и Flow notes заказа.

Возвраты

В блоке Flow payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Flow. Подтвердите вопрос Refund this amount via Flow? Flow e-mails the customer to complete the refund. Поддерживаются полный и частичный возвраты. Нужно право редактировать заказы. Возвраты ограничены суммой, которую Flow фактически списал, поэтому после расхождения сумм можно вернуть не больше суммы, оплаченной покупателем, а не итог заказа. Возвраты в CLP должны быть целыми суммами. Возврат отправляется в ту среду, где был оплачен платёж (тестовую или рабочую), поэтому ключи этой среды должны быть заполнены, а у покупателя должен быть действительный e-mail. Если Flow отклоняет возврат, блок показывает ошибку, и возврат не записывается. Успешный запрос добавляется в историю возвратов и заметки с номером и статусом возврата Flow. Полный возврат переводит заказ в статус Refunded. Частичный возврат не меняет статус. Возвраты доступны после подтверждения платежа Flow.

Последующие изменения статуса возврата, сообщённые Flow, добавляются в заметки. Если Flow позже отклоняет или отменяет возврат, в заметке указывается, что деньги покупателю не возвращены, и сумму можно вернуть повторно. Модуль не создаёт кредитные ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Flow. Возвраты, созданные в панели Flow, не импортируются в PrestaShop.

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

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

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

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

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

Flow не появляется на этапе оформления заказа: проверьте, что лицензия активна, Enable / Disable включено, заполнены ключи текущего режима (тестовые в тестовом режиме, рабочие в рабочем режиме) и валюта корзины — CLP или USD. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: подтверждение Flow не доходит до вашего магазина, а покупатель не вернулся. Проверьте, что URL подтверждения из Flow URLs открывается из интернета и не блокируется защитой паролем или межсетевым экраном. Включите Debug log и посмотрите поле Log на странице модуля.

Подтверждение отвечает Payment does not belong to the order: токен не относится к платежу, созданному этим магазином, или Flow сообщил для него другую ссылку. Ничего не меняется.

Подтверждение отвечает Gateway not configured: ключи среды платежа пусты. Введите их снова. Flow повторит подтверждение.

Подтверждение отвечает Flow API unavailable or Busy, retry: запрос статуса к Flow не выполнен или заказ в тот же момент создавал другой запрос. Flow повторит подтверждение.

Покупатель видит Flow payments are not available at the moment: ключи отсутствуют или Flow их отклонил. Проверьте API Key и Secret Key текущего режима.

Покупатель видит A valid billing email is required for Flow payments: Flow нужен e-mail покупателя.

Покупатель видит The order total is too small to be paid with Flow: итог корзины округляется до нуля в валюте корзины.

Покупатель заплатил, но заказ в статусе Awaiting Flow payment или Flow payment on hold: прочитайте заметки в блоке Flow payment. Покупатель создал купон на оплату наличными, который ещё не оплачен, или сумма либо валюта, сообщённые Flow, не совпадают с заказом. Итоги в CLP с десятичными знаками округляются до целых песо, поэтому установите точность CLP равной 0.

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

Возврат не выполняется с Flow accepts CLP refunds in whole units only: введите целую сумму.

Для разработчиков README перечисляет хуки actionWcpFlowSupportedCurrencies (валюты, для которых предлагается способ оплаты) и actionWcpFlowPaymentSubject (назначение платежа, отправляемое в Flow).

Удаление

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

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