VibeFox DPO for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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 повторной проверки модуля (см. Configuration).

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

Установка

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

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

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

4. Введите Company Token и Service Type тестовой и/или рабочей учётной записи (см. Configuration).

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

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

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

Configuration

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox DPO Pay Gateway > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Если модуль включён, но Company Token или Service Type выбранного режима пуст, страница предупреждает, что платёжный метод скрыт на оформлении заказа, и при сохранении появляется то же предупреждение. Пока включён тестовый режим, страница показывает Test mode is on: payments are created with the test account credentials.

DPO Pay

Enable/Disable: Enable DPO Pay включает или выключает платёжный метод. По умолчанию: выключено.

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

Description: текст под платёжным методом при оформлении заказа. По умолчанию: Pay securely by card or mobile money on the DPO Pay payment page.

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

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

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

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 больше никогда не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Service Type должен быть числом. Любое другое значение не сохраняется: страница показывает предупреждение и оставляет предыдущее значение.

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

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

Push notification URL: push-уведомление сразу сообщает вашему магазину, что платёж произведён, даже если покупатель закрыл браузер после оплаты. URL не задаётся в панели управления: попросите поддержку DPO установить этот URL для вашей учётной записи. С понятными ссылками он выглядит так: https://your-shop/module/wcp_dpo_pay/notify, возможно с кодом языка. Скопируйте его точно так, как он показан на странице. Он должен быть доступен из интернета, без режима обслуживания, брандмауэра или базовой аутентификации перед ним.

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

Scheduled status re-check (cron): вызывайте этот URL каждые 15 минут из задания cron сервера, например с помощью curl. Неподтверждённые платежи повторно проверяются в DPO через 15 минут после перенаправления и ещё раз после истечения срока оплаты. URL содержит секретный токен, поэтому держите его в тайне. Без URL push-уведомлений и cron заказ создаётся, только когда покупатель возвращается в магазин после оплаты.

Заказы

Successful payment status: статус заказа после проверенной успешной оплаты.

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

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

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

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

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

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

На этапе оплаты покупатель выбирает платёжный метод (по умолчанию DPO Pay) и видит примечание You will be redirected to the secure DPO Pay payment page. После подтверждения модуль создаёт транзакцию DPO на сумму корзины в валюте корзины, с номером корзины и названием вашего магазина в качестве описания, и отправляет покупателя на страницу оплаты DPO. Имя, e-mail, телефон и адрес для счёта покупателя передаются для предзаполнения страницы. Там покупатель платит любым способом, включённым в вашей учётной записи DPO. Ссылка на оплату действительна 5 часов. На этом этапе заказа ещё не существует.

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

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

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

Когда покупатель платит повторно за ту же корзину, сначала проверяется предыдущая транзакция DPO. Если она оплачена, заказ создаётся без второго списания. Если она ещё обрабатывается, покупатель видит Your previous payment for this order is still being processed by DPO. Please wait a few minutes before trying again. Иначе старая транзакция отменяется в DPO и создаётся новая.

Если DPO не может начать платёж, покупатель остаётся на оформлении заказа с коротким сообщением, выбранным по коду ошибки DPO, например DPO Pay does not support the currency of this order. Please choose another payment method. или The amount exceeds the limit allowed by DPO Pay. Please choose another payment method or contact us. При других ошибках показывается DPO Pay is temporarily unavailable. Please try again or choose another payment method. Техническая причина записывается в журнал.

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

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

Заказы

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

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

Payment accepted, Delivered or DPO payment on hold: платёж проверен. Статус соответствует Successful payment status. Платёж записывается с токеном транзакции DPO в качестве ID транзакции. Закрытое примечание на странице заказа показывает сумму, валюту, код одобрения и начало токена.

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

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

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

Возвраты

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

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

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

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

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

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

DPO Pay does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включено и заданы Company Token и Service Type выбранного режима: тестовые поля в тестовом режиме, рабочие — в остальных случаях. Страница настроек показывает предупреждение, если они не заполнены. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

The payment went through, but no order was created: скорее всего, URL push-уведомления не настроен для вашей учётной записи DPO, а покупатель не вернулся в магазин. Попросите поддержку DPO настроить URL, показанный в настройках, и проверьте, что cron вызывает URL повторной проверки каждые 15 минут. Включите Logging и посмотрите поле Log на странице модуля.

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

Push notification answers Verification failed: DPO не удалось связаться для проверки платежа, корзину в это же время обрабатывал другой запрос, или заказ не удалось создать (например, модуль отключён). DPO повторяет уведомление, а запланированная повторная проверка тоже подтверждает заказ. Причина записана в журнал.

The push URL shows Method not allowed in the browser: это нормально. URL принимает только запросы от DPO.

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

The Service Type is not saved: он должен быть числовым Service Type ID из DPO.

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

The customer sees that DPO accepts at most 2 decimal places: сумма корзины имеет 3 знака после запятой. DPO не может списать такие суммы.

The customer sees This order has already been paid with DPO Pay: DPO отказал во втором платеже за ту же корзину. Проверьте платёж в портале DPO и заказ в PrestaShop.

Order is DPO payment on hold after payment: прочитайте закрытое примечание на странице заказа (см. Статусы заказа), затем проверьте транзакцию в портале DPO.

Разработчики могут изменить данные покупателя, отправляемые в DPO, с помощью хука actionWcpDpoPayCustomerData, а срок оплаты — с помощью actionWcpDpoPayPaymentTimeLimit.

Удаление

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

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