VibeFox DPO for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее с расширением SimpleXML.

Учётная запись DPO Pay: вам понадобятся Company Token и Service Type ID вашей торговой учётной записи DPO. DPO выдаёт их при открытии учётной записи; получите их у вашего менеджера DPO или на dpogroup.com. DPO также может предоставить тестовую учётную запись со своим токеном и типом услуги. Отдельного тестового сервера нет: DPO использует один и тот же адрес API для тестовых и рабочих учётных записей, а учётная запись определяется по токену.

Валюта: валюта заказа должна поддерживаться вашей учётной записью DPO. DPO принимает не более 2 знаков после запятой, поэтому суммы заказов с 3 знаками (например, KWD 12.345) оплатить нельзя.

Cron на сервере: задание cron, которое каждые 15 минут вызывает URL повторной проверки расширения (см. Настройка).

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

Установка

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

OpenCart 3

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

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

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

4. Введите Company Token и Service Type тестовой и/или рабочей среды (см. Настройка).

5. Отправьте в службу поддержки DPO URL push-уведомлений из раздела Payment notifications и попросите настроить его для вашей учётной записи. Добавьте URL cron в задания cron вашего сервера.

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

OpenCart 4

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

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

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

4. Введите лицензионный ключ, учётные данные DPO, настройте URL push-уведомлений и cron и проверьте платёж, как в шагах 3–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличаются только URL push-уведомлений и URL cron (см. Уведомления об оплате).

Новая установка начинает работу с выключенным способом оплаты и включённым тестовым режимом. При установке расширение создаёт свою таблицу транзакций и секретный токен URL cron.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox DPO Pay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Если способ оплаты включён, но Company Token или Service Type выбранного режима пуст, страница предупреждает, что способ оплаты скрыт при оформлении заказа, и при сохранении показывается то же предупреждение. Пока включён тестовый режим, страница показывает Тестовый режим включён: платежи создаются с учётными данными тестовой учётной записи. Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении поле Title не должно быть пустым (не более 128 символов), Sort Order должен быть целым числом, а Total — числом не меньше 0; иначе ничего не сохраняется.

DPO Pay

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Безопасно оплатите банковской картой или мобильными деньгами на странице оплаты DPO Pay.

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

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

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

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

DPO выдаёт Company Token и Service Type ID для вашей торговой учётной записи, а отдельные — для тестовой. Получите их у вашего менеджера DPO или на dpogroup.com (раздел содержит ссылку на сайт).

Test mode: когда включено, новые платежи создаются с тестовыми Company Token и Service Type. По умолчанию: включено. Выключите, чтобы принимать реальные платежи с рабочими учётными данными. Пока опция включена, покупатели видят на шаге Confirm Order сообщение Тестовый режим: платежи создаются с тестовой учётной записью. Проверки статуса и отмены существующих платежей всегда используют ту учётную запись, с которой был создан платёж.

Test Company Token: Company Token вашей тестовой учётной записи DPO.

Test Service Type: числовой Service Type ID вашей тестовой учётной записи DPO.

Live Company Token: Company Token вашей рабочей торговой учётной записи DPO.

Live Service Type: числовой Service Type ID вашей рабочей торговой учётной записи DPO.

Сохранённые Company Token больше не показываются. Поле остаётся пустым и показывает Сохранено: оставьте пустым, чтобы не менять. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый токен, отметьте под полем Clear the saved Company Token on save и нажмите Save. Service Type должен быть числом. Любое другое значение не сохраняется: страница показывает предупреждение и оставляет предыдущее значение, а остальные настройки сохраняются.

Уведомления об оплате

Push notification URL: push-уведомление сразу сообщает вашему магазину, что платёж совершён, даже если покупатель закрыл браузер после оплаты. URL не задаётся в личном кабинете: попросите службу поддержки DPO настроить его для вашей учётной записи. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_dpo_pay/notify, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.notify. Он формируется из адреса витрины вашей установки OpenCart. Скопируйте его точно в том виде, в каком он показан на странице. Он должен быть доступен из интернета, без брандмауэра или базовой аутентификации перед ним.

Push-уведомления DPO не содержат подписи, поэтому их содержимому никогда не доверяют. Расширение использует их только для того, чтобы найти платёж по его токену транзакции, а затем проверяет результат непосредственно в DPO. Токен, который не создавал ваш магазин, отклоняется без какого-либо запроса к DPO.

Плановая проверка статуса (cron): вызывайте этот URL каждые 15 минут из задания cron на сервере, например с помощью curl. Неподтверждённые платежи повторно проверяются в DPO через 15 минут после перенаправления и затем снова после истечения срока оплаты. URL содержит секретный токен, поэтому держите его в тайне. На OpenCart 4 он выглядит так: https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.cron&token= и токен. Без push-URL и cron заказ получает статус, только когда покупатель возвращается в магазин после оплаты.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Заказ получает статус только после того, как DPO подтвердил платёж. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Successful payment status: статус заказа после проверенного успешного платежа. По умолчанию: В обработке. Выберите Выполнен, если каждый оплаченный заказ должен завершаться автоматически, или собственный статус проверки для ручного подтверждения каждого заказа.

DPO payment on hold status: статус для платежа, который требует вашей проверки: несовпадение суммы или валюты, платёж только с авторизацией, переплата или недоплата по транзакции либо платёж, поступивший после отмены заказа покупателем. Примечание в истории заказа объясняет причину. По умолчанию: Ожидает оплаты, так как в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Cancelled order status: если неоплаченный заказ DPO Pay переведён в этот статус, его открытый платёж DPO также отменяется в DPO. По умолчанию: Отменен.

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию DPO Pay). На шаге Confirm Order покупатель видит ваше описание и примечание Вы будете перенаправлены на защищённую страницу оплаты DPO Pay. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт транзакцию DPO на сумму заказа в валюте заказа с номером заказа и названием вашего магазина в качестве описания и отправляет покупателя на страницу оплаты DPO. Имя, e-mail, телефон и платёжный адрес покупателя передаются, чтобы заранее заполнить страницу. Там покупатель платит любым способом, включённым в вашей учётной записи DPO. Ссылка на оплату действительна 5 часов. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Если магазин не запрашивает платёжный адрес (поведение OpenCart 4 по умолчанию), передаётся адрес доставки.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения DPO: расширение запрашивает у DPO результат транзакции, когда покупатель возвращается, когда приходит push-уведомление и при плановых проверках. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. На OpenCart 4 браузер не передаёт сессию магазина, когда DPO возвращает покупателя, поэтому расширение сначала показывает короткую страницу, которая заново открывает тот же адрес возврата в вашем магазине: корзина и вход покупателя сохраняются.

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

Если покупатель нажимает на странице DPO кнопку возврата в магазин, сначала проверяется транзакция. Если она оплачена, покупатель видит страницу успеха. Иначе транзакция отменяется в DPO, а покупатель возвращается к оформлению заказа с корзиной.

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

OpenCart 4 хранит заказ в оформлении до показа страницы успеха. Если этот заказ тем временем был закрыт (например, отменён или возвращён), Confirm Order или возврат из DPO отправляет покупателя на оформление заказа: с сообщением The payment was declined or cancelled. Please try again or choose another payment method., если у заказа не было платежа, или с сообщением 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 оплачивает новый заказ корзины.

Если DPO не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, выбранным по коду ошибки DPO, например DPO Pay не поддерживает валюту этого заказа. Пожалуйста, выберите другой способ оплаты. или Сумма превышает лимит, разрешённый DPO Pay. Пожалуйста, выберите другой способ оплаты или свяжитесь с нами. Прочие ошибки показывают DPO Pay временно недоступен. Пожалуйста, попробуйте снова или выберите другой способ оплаты. Техническая причина записывается в журнал.

Push-уведомление и URL cron также работают, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а на OpenCart 4 расширение добавляет стартовое действие (startup action), которое пропускает их и возврат покупателя. Уже начатые платежи подтверждаются, даже если вы выключите способ оплаты.

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

Заказы

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

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

Successful payment status (по умолчанию В обработке): платёж проверен. Примечание в истории заказа показывает сумму, валюту, код одобрения и начало токена транзакции DPO.

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

Cancelled order status (по умолчанию Отменен): если неоплаченный заказ расширения переведён в этот статус (например, заказ, приостановленный из-за платежа только с авторизацией), его открытая транзакция DPO также отменяется в DPO.

Более поздний результат отказа никогда не меняет заказ, а результаты старых транзакций никогда не проваливают текущую попытку. Если DPO подтверждает второй успешный платёж за уже оплаченный заказ, заказ не меняется и получает примечание о возможной двойной оплате, чтобы вы могли вернуть деньги в портале DPO. Такое же примечание добавляется к оплаченному заказу, когда та же корзина (та же сессия покупателя и то же содержимое корзины) была оплачена ещё раз с другим заказом, например во второй вкладке браузера; этот другой заказ статуса не получает. Заказ, который вы перевели в другой статус (например, возвращён), никогда не открывается заново; поздний платёж лишь добавляет примечание.

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

Возвраты

Возвраты из магазина в этой версии недоступны. Верните платёж в торговом портале DPO, а затем измените статус заказа в OpenCart.

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

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

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

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

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

DPO Pay не отображается при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и заданы Company Token и Service Type выбранного режима: тестовые поля в тестовом режиме, рабочие — в остальных случаях. Страница настроек показывает предупреждение, если их нет. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает значения Total в настройках.

Платёж прошёл, но заказ остался без статуса: вероятно, URL push-уведомлений не настроен для вашей учётной записи DPO, а покупатель не вернулся в магазин. Попросите службу поддержки DPO настроить URL из настроек и проверьте, что cron вызывает URL повторной проверки каждые 15 минут. Включите Logging и посмотрите поле Log на странице расширения.

Push-уведомление отвечает Unknown transaction: токен транзакции не относится к платежу DPO Pay этого магазина, например push пришёл от другого магазина на той же учётной записи DPO.

Push-уведомление отвечает Verification failed: не удалось обратиться к DPO для проверки платежа, заказ в тот же момент обрабатывался другим запросом, или не удалось установить статус заказа. DPO повторяет уведомление, и плановая проверка также подтверждает заказ. Причина есть в журнале.

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

URL cron отвечает Forbidden: токен в URL неверен. Скопируйте URL заново со страницы настроек. Рабочий вызов отвечает OK checked= и количеством проверенных платежей.

Service Type не сохраняется: он должен быть числовым Service Type ID из DPO.

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

Покупатель видит DPO Pay is temporarily unavailable: DPO отказался создать транзакцию, например из-за неверного Company Token или Service Type либо токена другого режима. Код результата DPO есть в журнале.

Покупатель видит, что DPO принимает не более 2 знаков после запятой: сумма заказа имеет 3 знака. DPO не может списать такие суммы.

Покупатель видит This order has already been paid with DPO Pay: DPO отклонил второй платёж за тот же заказ. Проверьте платёж в портале DPO и заказ в OpenCart.

Заказ после оплаты в статусе проверки: прочитайте примечание в History заказа (см. Статусы заказов), затем проверьте транзакцию в портале DPO.

Для разработчиков: расширение запускает события OpenCart wcp_dpo_pay_customer_data (данные покупателя, отправляемые в DPO) и wcp_dpo_pay_payment_time_limit (срок оплаты в часах).

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox DPO Pay Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Также удаляется событие OpenCart этого расширения (на OpenCart 4 — его события и стартовое действие, которое пропускает DPO и cron в режиме обслуживания). Если Delete data включено, удаляются остальные настройки шлюза (название, описание, тестовый режим, Company Token, Service Type, журналирование) и журнал, а при повторной установке создаётся новый URL cron. Если выключено, они сохраняются для последующей переустановки. Данные DPO по заказам всегда сохраняются, поэтому поздние уведомления и повторные проверки старых платежей продолжают работать после переустановки. Существующие заказы сохраняют свои примечания об оплате.

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

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