VibeFox Flow for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

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

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

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

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

Установка

Скачиваемый файл — один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_flow_gateway-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_flow_gateway.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ один и тот же для обеих версий.

OpenCart 3

1. В административной части перейдите в раздел Extensions > Installer, нажмите Upload и выберите файл wcp_flow_gateway-oc3-(version).ocmod.zip. Расширение не содержит модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload из этого пакета в корневую папку магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Flow Gateway и нажмите Install (зелёная кнопка +). Вашему администратору нужно право изменять список платёжных расширений.

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

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

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

OpenCart 4

1. В административной части перейдите в раздел Extensions > Installer, нажмите Upload и выберите файл wcp_flow_gateway.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Flow Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и ключи Flow так же, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличаются только Flow URLs (см. Flow URLs): они отправляются с каждым платежом, поэтому в учётной записи Flow ничего менять не нужно.

После новой установки способ оплаты выключен, а режим песочницы включён.

Настройка

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

При сохранении Title должен содержать от 1 до 128 символов, Sort Order должен быть пустым или целым числом, Total должен быть пустым или числом не меньше 0, а выбранная географическая зона и статусы заказов должны существовать. Иначе ничего не сохраняется, и страница показывает, что нужно исправить.

Flow.cl

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

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

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

Sort Order: положение Flow среди способов оплаты при оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Flow только для адресов оплаты в выбранной географической зоне. По умолчанию: All zones. Географические зоны настраиваются в разделе System > Localisation > Geo Zones.

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

Учётные данные API Flow

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

Sandbox mode: использует песочницу Flow (sandbox.flow.cl) и ключи песочницы. В режиме песочницы реальные деньги не списываются. По умолчанию: включено. Выключите его и заполните рабочие ключи, чтобы принимать реальные платежи. Возвраты всегда выполняются в той среде, где был оплачен заказ. Пока режим включён, покупатели на шаге Confirm Order видят SANDBOX MODE — Payments go to the Flow sandbox. No real charges.

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 the saved key on save под полем и нажмите Save.

Уведомления

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

В OpenCart 4 метод указывается после точки: https://your-store/index.php?route=extension/wcp_flow_gateway/payment/wcp_flow_gateway.confirmation, ….back и ….refundCallback.

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

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (пропущенный заказ, «missing order»). Он получает статус только после того, как Flow сообщит об оплате, через подтверждение или возврат покупателя. Статус всегда запрашивается у Flow подписанным запросом. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Order Status After Payment: статус, который устанавливается после проверенного платежа Flow. По умолчанию: В обработке.

Awaiting Flow Payment Status: покупатель создал купон на оплату наличными (Servipag, Multicaja и аналогичные). Деньги поступают позже, и Flow их подтверждает. По умолчанию: Ожидание.

Flow Payment On Hold Status: оплачено, но сумма или валюта не совпадают с заказом, либо деньги пришли по отменённому заказу. Примечание объясняет причину; проверьте платёж вручную. По умолчанию: Ожидание, так как в OpenCart нет статуса «On hold». Вы можете создать свой статус в разделе System > Localisation > Order Statuses и выбрать его здесь.

Payment Rejected Status: заказ, ожидающий оплаты купоном, платёж по которому в Flow был отклонён. По умолчанию: Неудачно.

Payment Annulled Status: заказ, ожидающий оплаты купоном, платёж по которому в Flow был аннулирован (отменён). По умолчанию: Отменено.

Refunded Status: устанавливается после полного возврата платежа со страницы заказа. По умолчанию: Возвращен.

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

Debug log: записывает вызовы API и уведомления в файл flw_p_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть через веб-браузер; при достижении 5 МБ он переименовывается в flw_p_debug.old.log.php. Ключи, подписи и данные покупателей никогда не записываются в журнал. Ошибки записываются всегда, даже когда опция выключена. По умолчанию: выключено.

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

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

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. API Keys и Secret Keys не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые ключи сохраняются.

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Flow). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to Flow to complete the payment. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение создаёт платёж Flow на сумму заказа в валюте заказа с темой Order #, номером заказа и названием магазина, и отправляет покупателя на страницу оплаты Flow. Адрес электронной почты покупателя передаётся в Flow. Там покупатель выбирает способ оплаты, включённый в вашей учётной записи Flow. Заказу добавляется примечание Flow payment started с суммой, номером заказа Flow и средой.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Flow: через подтверждение или через подписанный запрос статуса при возврате покупателя. Затем заказ получает статус обычным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если покупатель создал купон Servipag или Multicaja, заказ получает статус Awaiting Flow Payment Status, а на странице также выводится Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. Если сумма не совпала, страница показывает Your Flow payment was received and is being reviewed by the store.

Если Flow недоступен, когда покупатель возвращается, или в этот момент заказ подтверждается другим запросом, появляется страница Payment confirmation с текстом We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly — please do not pay again., кнопкой 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. Корзина сохраняется. На OpenCart 4 эти сообщения выводятся над страницей оформления заказа.

Покупатель может попробовать снова. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 обновляет заказ, созданный при оформлении, поэтому новая попытка оплачивает тот же заказ новым платежом Flow. Flow не может отменить уже начатый платёж. Поэтому перед новым платежом у Flow проверяются открытые платежи Flow по этому заказу и по другим заказам из той же корзины за последние два дня. Если один из них оплачен или имеет купон, покупатель переходит на страницу успешного оформления вместо повторной оплаты. Если другой заказ из той же корзины уже оплачен через Flow, новый платёж тоже не начинается. Если та же корзина оплачивается дважды, например в двух вкладках браузера, статус получает заказ только по первому платежу: другой заказ остаётся без статуса, а оплаченный заказ получает примечание с просьбой вернуть второй платёж в вашей учётной записи Flow.

OpenCart 4 хранит заказ в оформлении заказа до показа страницы успешного оформления. Если этот заказ закрыт без оплаты (например, вы его отменили), покупатель возвращается к оформлению заказа с сообщением The Flow payment was not completed. You can try again or choose another payment method., а следующее нажатие Confirm Order оплачивает новый заказ этой корзины. Если этот заказ уже оплачен или имеет купон, но корзина с тех пор изменилась, в том числе количество товара, покупатель возвращается к оформлению заказа, а следующее нажатие Confirm Order оплачивает новую корзину новым заказом. Оплаченный заказ никогда не показывается как оплаченный для другой корзины.

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

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

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

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

Без статуса (missing order): покупатель был направлен в Flow и не оплатил, платёж был отклонён или не завершён, либо Flow ещё не подтвердил платёж. В разделе Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Order Status After Payment (default Processing): Flow сообщил, что платёж выполнен, а сумма и валюта совпадают. Примечание показывает сумму и номер заказа Flow.

Awaiting Flow Payment Status (default Pending): покупатель создал купон на оплату наличными. Примечание указывает тип купона. Заказ переходит в статус Order Status After Payment, когда Flow подтверждает платёж.

Flow Payment On Hold Status (default Pending): Flow сообщил о сумме или валюте, отличных от суммы заказа, либо платёж поступил по отменённому заказу. Полученный Flow платёж записывается, а примечание поясняет ситуацию. Проверьте заказ и отправьте его или верните платёж.

Payment Rejected Status (default Failed): Flow отклонил платёж купоном по заказу в ожидании.

Payment Annulled Status (default Canceled): платёж купоном по заказу в ожидании был аннулирован в Flow.

Refunded Status (default Refunded): платёж полностью возвращён через расширение.

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

Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox Flow Gateway

В разделе Sales > Orders откройте заказ, оплаченный через Flow. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Flow Gateway показывает номер Flow order со способом оплаты и метку Sandbox для платежей в песочнице, ссылку commerceOrder (и количество попыток), Status платежа, суммы Paid / refunded, форму возврата, историю возвратов и Flow notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению.

Возвраты

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

Последующие изменения статуса возврата, которые сообщает Flow, добавляются в примечания. Если Flow позже отклоняет или отменяет возврат, примечание сообщает, что деньги покупателю не возвращены, и сумму можно вернуть снова. Возвраты товаров в разделе Sales > Returns не возвращают деньги через Flow. Возвраты, созданные в панели Flow, в OpenCart не импортируются.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Flow Gateway — первый блок в разделе Extensions > Extensions > Payments > VibeFox Flow Gateway > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы повторно проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: opencart-payment-flow и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись на vibefox.net. Изменять ключ могут только администраторы с правом Modify на расширение. Тексты блока следуют языку административной части (включены английский и русский).

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

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

Без активного ключа Flow не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Администратор, вошедший в административную часть в том же браузере, по-прежнему видит способ оплаты в магазине, помеченный как (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать расширение до покупки ключа. На OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без активного ключа способ оплаты скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard административной части появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова при открытии административного Dashboard или страницы Edit: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Задание cron не требуется.

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

Flow не появляется при оформлении заказа: проверьте, что лицензия активна, включён Enable / Disable, заполнены ключи текущего режима (ключи песочницы в режиме песочницы, рабочие ключи в рабочем режиме), и что валюта оформления заказа — CLP или USD. Также проверьте, что адрес оплаты входит в выбранную Geo Zone, и что сумма заказа достигает значения Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: подтверждение от Flow не доходит до вашего магазина, а покупатель не вернулся. Проверьте, что адрес подтверждения из 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 текущего режима.

Покупатель видит This payment method is not available. Please reload the checkout page.: сессия оформления больше не соответствует заказу, либо способ оплаты тем временем был выключен. Покупатель перезагружает страницу оформления.

Покупатель видит A valid billing email is required for Flow payments: Flow нужен адрес электронной почты покупателя.

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

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

На вкладке нет формы возврата: вкладка объясняет причину: платёж ещё не подтверждён, он полностью возвращён, у вашей группы пользователей нет права изменять расширение, или ключи среды, в которой был сделан платёж, пусты.

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

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

Для разработчиков расширение вызывает события OpenCart wc_flw_supported_currencies (валюты, для которых предлагается способ оплаты) и wc_flw_payment_subject (тема платежа, отправляемая в Flow).

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Flow Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable / Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения также удаляется (на OpenCart 4 удаляются его события и стартовое действие, которое пропускает Flow URLs в режиме обслуживания). Если Delete data on uninstall включено, удаляются остальные настройки (название, описание, режим песочницы, ключи, переключатель журнала отладки) и журнал. Если оно выключено, они сохраняются для последующей повторной установки. Записи о платежах и возвратах Flow всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

На OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer, нажмите рядом с VibeFox Flow Gateway в списке установленных расширений кнопку Uninstall (оранжевая кнопка −), затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

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