VibeFox Autopay for OpenCart — Помощь

Требования

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

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

Сервис Autopay: нужны Service ID и Shared key (ключ хеширования) вашего сервиса Autopay. Они показаны в портале мерчанта Autopay: portal.autopay.eu для рабочего режима и testportal.autopay.eu для тестов. У тестовых сервисов свои Service ID и Shared key; попросите Autopay открыть такой сервис. Хеш-функция сервиса должна быть SHA-256.

Валюта: валюта заказа должна быть PLN, EUR, GBP, USD или CZK и приниматься вашим сервисом Autopay.

Доступный магазин: Autopay должен иметь возможность отправлять уведомления в ваш магазин, поэтому магазин должен быть доступен из интернета без базовой аутентификации и без файрвола, блокирующего POST-запросы. Режим обслуживания не блокирует уведомления, потому что OpenCart пропускает запросы платёжных расширений.

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

Установка

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

OpenCart 3

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

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

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

4. Введите Service ID и Shared key (тестовый и рабочий) и выберите валюты вашего сервиса.

5. В портале Autopay задайте для вашего сервиса ITN URL, URL возврата и хеш-функцию SHA-256 (см. Настройка).

6. Включите Enable/Disable и нажмите Save. Оформите тестовый заказ в тестовом режиме, затем отключите Test mode для реальных платежей.

OpenCart 4

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

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

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

4. Введите лицензионный ключ и настройки так же, как в шагах с 3 по 6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличаются только адреса ITN и возврата (см. Адреса ITN и возврата).

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если Service ID или Shared key выбранной среды пусты (тогда способ оплаты скрыт при оформлении заказа), и если валюта магазина по умолчанию не отмечена в Currencies (тогда способ оплаты скрыт в этой валюте). Пока тестовый режим включён, страница показывает Test mode is on: payments go to the Autopay test environment (testpay.autopay.eu), no real money is taken. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

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

Autopay

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

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

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

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

Сервис Autopay

Service ID и Shared key показаны в портале мерчанта Autopay (portal.autopay.eu или testportal.autopay.eu, ссылки приведены в этом разделе).

Test mode: использует тестовую среду Autopay (testpay.autopay.eu) и тестовые учётные данные, указанные ниже. По умолчанию: включено. Отключите его, чтобы принимать реальные платежи на pay.autopay.eu с рабочими учётными данными. Пока режим включён, покупатели видят Test mode: no real payment is taken. на шаге Confirm Order.

Service ID (production): числовой идентификатор сервиса на portal.autopay.eu.

Shared key (production): ключ хеширования рабочего сервиса. Храните его в секрете.

Service ID (test): числовой идентификатор сервиса на testportal.autopay.eu.

Shared key (test): ключ хеширования тестового сервиса.

Сохранённые Shared key больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый ключ, отметьте Clear the saved key on save под полем и нажмите Save.

Currencies: валюты, которые принимает ваш сервис Autopay: PLN, EUR, GBP, USD, CZK. Autopay обычно открывает отдельный сервис для каждой валюты. Способ оплаты предлагается только тогда, когда валюта оформления заказа отмечена здесь. По умолчанию: PLN.

Адреса ITN и возврата

Введите эти адреса в портале Autopay для вашего сервиса — и для рабочего режима, и для тестового. Точные адреса показаны в поле Addresses этого раздела и формируются из адреса витрины вашей установки OpenCart:

Это адреса OpenCart 3. В OpenCart 4 они такие:

Скопируйте адреса точно так, как их показывают настройки. Без URL ITN заказы никогда не подтверждаются: OpenCart оставляет заказ без статуса, пока Autopay не подтвердит платёж. Каждое ITN проверяется по хешу SHA-256, рассчитанному с Shared key сервиса, указанного в уведомлении. Уведомления без действительного хеша или с неизвестным Service ID отклоняются. Уведомление применяется к заказу, только если его платёж был начат с тем же сервисом Autopay, поэтому тестовое уведомление никогда не подтверждает рабочий платёж. Уведомления по платежам, начатым до переключения Test mode, по-прежнему проверяются правильным ключом, пока обе учётные записи сохранены.

Расширение обрабатывает в ITN следующие статусы платежей:

Orders

OpenCart создаёт заказ на шаге Confirm Order без статуса (пропущенный заказ). Заказ получает статус только после подтверждения платежа Autopay (ITN SUCCESS). Неудачный или брошенный платёж оставляет его без статуса. В OpenCart 4 неоплаченный заказ оформления может получить статус Voided, который OpenCart 4 ставит, когда покупатель возвращается на шаг Confirm Order; расширение считает такой заказ заказом без статуса, и последующее ITN SUCCESS всё равно отмечает его оплаченным. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

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

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

Advanced

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

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

Import / Export

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Autopay). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the secure Autopay payment page to complete the payment. OpenCart создаёт заказ на этом шаге, пока без статуса. Когда покупатель нажимает Confirm Order, браузер отправляет в Autopay подписанную форму платежа: сумма заказа в валюте заказа, номер заказа OpenCart как OrderID, описание Order с номером и адрес электронной почты покупателя. На странице Autopay покупатель выбирает способ оплаты и платит.

Заказ отмечается оплаченным только после того, как Autopay подтвердит его подписанным ITN, а сумма и валюта совпадут с заказом. Затем заказ получает статус стандартным способом OpenCart, с обычными письмами о заказе и обновлением остатков на складе. После оплаты покупатель возвращается в ваш магазин. Адрес возврата подписан, но никогда не изменяет заказ. Если у заказа уже есть статус, покупатель видит страницу успешного оформления заказа OpenCart. Если ITN ещё не пришло, страница Payment confirmation показывает Thank you. Your payment is being confirmed by Autopay — your order is confirmed as soon as Autopay reports the payment, and you will receive an e-mail. с кнопками Check again и Back to checkout.

Если Autopay сообщил о неудачном платеже, покупатель возвращается к оформлению заказа с сообщением The payment was not completed. You can try again or choose another payment method. Корзина сохраняется. Каждая новая попытка создаёт новый заказ OpenCart (в OpenCart 4 покупатель оплачивает тот же заказ снова, новой попыткой под тем же OrderID). Если другой заказ из той же корзины (те же товары в том же визите) уже оплачен, покупатель попадает на страницу успеха вместо повторной оплаты. Новая покупка после завершённой — это новая корзина, и она оплачивается обычным образом. Если платёж невозможно начать, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например Autopay payments are not configured. Please choose another payment method or contact the store. или о том, что Autopay не может принимать платежи в этой валюте.

В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Сообщение о незавершённом платеже показывается над страницей оформления заказа. OpenCart 4 хранит один заказ для оформления и обновляет его. Если этот заказ тем временем закрыл магазин (например, вы его отменили), покупатель возвращается к оформлению заказа с сообщением The payment was not completed. You can try again or choose another payment method., либо, если заказ был оплачен через Autopay, с сообщением Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. Если заказ оформления уже оплачен для другой корзины, сообщение: Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. Следующее нажатие Confirm Order оплачивает новый заказ. Изменение корзины, в том числе нового количества, считается новой корзиной, которой нужна собственная оплата. ITN также работает, когда магазин находится в режиме обслуживания: в OpenCart 4 расширение добавляет для этого стартовое действие.

Расширение не поддерживает возвраты из OpenCart, подписки и регулярные платежи, сохранённые карты, код BLIK или форму карты на странице оформления заказа, выбор банка или платёжного канала на странице оформления заказа, и использует один Service ID на среду.

Заказы

Order statuses

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

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

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

Оплаченный заказ никогда не меняется последующим уведомлением о неудаче. Если Autopay сообщает о ещё одном успешном платеже по уже оплаченному заказу или оплачен второй заказ из той же корзины, примечание предупреждает, что покупатель мог заплатить дважды. Уведомление о платеже, начатом с другим сервисом Autopay, не применяется, и примечание это объясняет. Примечания — это записи в History заказа, которых покупатель не видит.

VibeFox Autopay Payment tab

В разделе Sales > Orders откройте заказ, оплаченный через Autopay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Autopay Payment показывает OrderID at Autopay, Service ID и среду с меткой Test mode для тестовых платежей, Amount, статус Payment attempt, Autopay transaction ID и Autopay notes заказа. Вкладка доступна только для чтения и показывается пользователям, у которых есть доступ к расширению.

Refunds

Возвраты через Autopay не поддерживаются. Верните платёж в портале Autopay, а затем вручную обновите заказ в OpenCart.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Autopay Payment является первым блоком в разделе Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату окончания действия лицензии и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-autopay и ссылка 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.

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

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

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

Autopay не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, в выбранной среде заполнены Service ID и Shared key, а валюта оформления заказа отмечена в Currencies. Страница настроек показывает предупреждение, если чего-то из этого не хватает. Проверьте также, что платёжный адрес входит в выбранную Geo Zone и что заказ достигает Total, указанного в настройках.

Платёж прошёл, но заказ остаётся без статуса: Autopay не доставил ITN, или магазин его отклонил. Проверьте, что ITN URL, показанный в настройках, задан для сервиса в портале Autopay (рабочий или тестовый), что хеш-функция — SHA-256 и что Shared key в расширении совпадает с сервисом. Проверьте, что магазин доступен из интернета. Включите Logging и посмотрите поле Log на странице расширения.

В журнале написано ITN rejected: invalid hash: Shared key не совпадает с сервисом, либо хеш-функция сервиса не SHA-256.

В журнале написано, что service ID не настроен: уведомление пришло от сервиса, Service ID которого не введён в расширение, либо его Shared key пуст.

В журнале написано could not lock the order, Autopay will retry: заказ в этот момент обрабатывало другое уведомление. Магазин отвечает так, чтобы Autopay отправил уведомление повторно.

URL ITN в браузере показывает METHOD_NOT_ALLOWED: это нормально. URL принимает только POST-запросы от Autopay.

Заказ находится в статусе удержания с примечанием о несоответствии: Autopay сообщил о сумме или валюте, отличных от суммы заказа. Проверьте транзакцию в портале Autopay и вручную завершите или верните заказ.

Примечание говорит, что уведомление НЕ применено: платёж по этому заказу был начат не с этим сервисом Autopay, например тестовое уведомление по рабочему заказу. Проверьте транзакцию в портале Autopay.

После оплаты покупатель попадает на главную страницу: адрес возврата не удалось проверить, например потому что Service ID не введён в расширение. Заказ не затронут; он следует за ITN.

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

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

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Autopay Payment. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders. Расширение всегда удаляет прочие настройки шлюза, включая Service ID и Shared key, а также журнал. Опции сохранить настройки нет. В OpenCart 4 также удаляются события расширения и его стартовое действие, которое пропускает ITN в режиме обслуживания. Записи о платежах Autopay всегда сохраняются. Существующие заказы сохраняют свои платёжные примечания.

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

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