VibeFox Quickpay for PrestaShop — Помощь

Требования

PrestaShop: 8.0 – 9.x.

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

Учётная запись Quickpay: вам нужны два значения из менеджера Quickpay: ключ API пользователя API (для создания платежей, списания и возвратов) и приватный ключ учётной записи (для проверки подписи обратных вызовов Quickpay). Больше ничего настраивать в Quickpay не нужно. Ваш магазин должен быть доступен из интернета, без защиты паролем, чтобы обратные вызовы Quickpay могли приходить.

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

Установка

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

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

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

4. Вставьте ключ API и приватный ключ из менеджера Quickpay и нажмите Test API key (см. Настройки).

5. Выберите режим списания и статус заказа после оплаты, включите Enable/Disable и нажмите Save. Пока ваша учётная запись Quickpay в тестовом режиме, включите Test payments и совершите платёж тестовой картой Quickpay.

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

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Quickpay Gateway > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Пока не сохранены ключ API и приватный ключ, страница показывает Quickpay требует настройки: введите ключ API и приватный ключ. Пока оба не сохранены, способ оплаты скрыт при оформлении заказа. Пока включены Test payments, страница напоминает выключить их, когда ваша учётная запись Quickpay перейдёт в рабочий режим.

Quickpay

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

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

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

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

В менеджере Quickpay (manage.quickpay.net) откройте Settings > Integration. Скопируйте ключ API пользователя API (Settings > Users) и приватный ключ учётной записи.

Callback URL: показывает URL обратного вызова вашего магазина. При понятных URL он выглядит так: https://your-shop/module/wcp_quickpay_gateway/callback. Quickpay вызывает его после каждой операции с платежом (авторизация, списание, возврат, отмена). Он передаётся с каждым платежом автоматически, поэтому в Quickpay ничего настраивать не нужно.

API key: ключ API пользователя API Quickpay. Используется для создания платежей, списания и возвратов.

Private key: приватный ключ учётной записи. Используется для проверки подписи (HMAC-SHA256) обратных вызовов Quickpay. Без него ни один платёж не подтверждается, а обратные вызовы отклоняются.

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

Очистка сохранённых секретов: отметьте API key или Private key и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Test payments: принимает платежи, сделанные тестовыми картами Quickpay. Отдельной песочницы у Quickpay нет: пока учётная запись Quickpay в тестовом режиме, платежи проводятся тестовыми картами и помечаются как тестовые. Включайте этот параметр только во время тестирования. Когда он выключен, тестовый платёж никогда не отмечает заказ оплаченным. Когда он включён, при оформлении заказа под способом оплаты показывается Тестовый режим: принимаются тестовые карты Quickpay. По умолчанию: выключено.

Test API key: эта кнопка проверяет ключ, введённый в поле API key (или сохранённый, если поле пустое), запросом к Quickpay с авторизацией, без сохранения ключа. Ответы: Подключение успешно — ключ API действителен., Quickpay отклонил ключ API., Ключ API не настроен. или Не удалось подключиться: и причина.

Оплата

Capture: момент, когда деньги списываются с карты.

Order status after payment: статус заказа после того, как Quickpay подтвердил списанный платёж.

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

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

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

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

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Quickpay, со значком карты) и подтверждает выбор. Модуль создаёт платёж Quickpay для корзины в валюте корзины и ссылку на оплату на сумму корзины, после чего отправляет покупателя в окно оплаты Quickpay. На этом этапе заказа ещё нет. Покупатель платит в этом окне одним из способов, включённых в вашем окне оплаты Quickpay. E-mail покупателя передаётся в Quickpay. Окно оплаты открывается на языке покупателя, если Quickpay его поддерживает (датский, немецкий, английский, испанский, финский, французский, итальянский, нидерландский, норвежский, польский, шведский), в противном случае — на английском.

После оплаты покупатель возвращается в ваш магазин. Сам возврат ничего не отмечает как оплаченное. Заказ отмечается оплаченным только после подтверждения Quickpay: подписанный обратный вызов создаёт заказ, когда списанная сумма и валюта совпадают с корзиной. Затем покупатель видит стандартную страницу подтверждения заказа. При Authorize only заказ создаётся в статусе Quickpay payment on hold, а платёж вы списываете позже. Если обратный вызов ещё не пришёл, когда покупатель вернулся, страница Payment confirmation показывает сообщение Ваш платёж подтверждается Quickpay. Вы получите письмо, как только заказ будет подтверждён. с кнопками Check again и Back to checkout.

Если покупатель отменяет платёж в окне оплаты, ссылка на оплату удаляется в Quickpay, а покупатель возвращается к оформлению заказа с сообщением Платёж отменён. Вы можете попробовать снова или выбрать другой способ оплаты. Если карта отклонена, сообщение: Платёж не был завершён. Вы можете попробовать снова или выбрать другой способ оплаты. Корзина сохраняется. Новая попытка повторно использует платёж Quickpay корзины с новой ссылкой, поэтому старая ссылка никогда не может быть оплачена параллельно. Пока платёж по корзине авторизован и ждёт списания, второй платёж не начинается; покупатель видит страницу Payment confirmation.

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

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

Модуль принимает только разовые платежи. В нём нет подписок и периодических платежей, сохранённых карт, частичного списания; он не передаёт в Quickpay позиции корзины или счёта и не имеет отдельных способов MobilePay, Apple Pay или Klarna: покупатель выбирает из способов, включённых в ваше окно оплаты Quickpay.

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

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

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

Payment accepted or Delivered: Quickpay подтвердил списанный платёж с правильной суммой и валютой. Статус соответствует Order status after payment. Платёж записывается с ID платежа Quickpay в качестве ID транзакции, а примечание показывает платёж (для тестовых платежей помечено TEST).

Quickpay payment on hold: платёж только авторизован и ждёт Capture Quickpay payment; или Quickpay сообщил сумму или валюту, отличные от суммы заказа (например, корзина была изменена после начала платежа или в менеджере Quickpay списали другую сумму); или автоматическое списание не удалось, и сумма всё ещё только зарезервирована. Примечание поясняет причину. Если деньги списаны на другую сумму, платёж записывается в заказ на сумму, которую списал Quickpay.

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

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

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

Когда вы отменяете неоплаченный заказ, его ссылка на оплату удаляется в Quickpay. Отмена авторизованного заказа не освобождает зарезервированную сумму автоматически: примечание напоминает отменить платёж в менеджере Quickpay; иначе резерв закончится по истечении авторизации.

Блок Quickpay

На странице заказа показан блок Quickpay payment с ID платежа, статусом платежа, суммой и возвращённой суммой, значком Test payment для тестовых платежей, списком всех платежей Quickpay корзины (если их больше одного), историей возвратов и Quickpay notes заказа. Для списания и возвратов нужно право редактировать заказы; доступ к страницам модулей не требуется.

Списание

При Authorize only нажмите Capture Quickpay payment в блоке Quickpay и подтвердите Списать всю сумму заказа через Quickpay? Списывается вся сумма заказа; частичное списание недоступно. Если Quickpay подтверждает сразу, заказ переводится в статус Order status after payment. Иначе примечание сообщает, что списание запрошено, и заказ отмечается оплаченным, когда обратный вызов Quickpay это подтвердит. Отклонённое списание показывается в блоке и отмечается в заказе.

Возвраты

В блоке Quickpay введите сумму (предзаполняется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Quickpay. Подтвердите вопрос Вернуть эту сумму через Quickpay? Это действие нельзя отменить. Полные и частичные возвраты поддерживаются для списанных платежей. Возвраты выполняются в сумме и валюте, которые списал Quickpay, поэтому при расхождении суммы или валюты вы можете вернуть не больше того, что покупатель реально заплатил, а не сумму заказа. Quickpay обрабатывает возвраты асинхронно: в истории возвратов появляется requested, а обратный вызов переводит его в confirmed или failed и добавляет результат в примечания. Если Quickpay сразу отклоняет возврат, блок показывает ошибку, и возврат не записывается. Полный возврат переводит заказ в статус Refunded; частичный возврат статус не меняет. Авторизованный платёж, который никогда не списывался, вернуть нельзя; отмените его в менеджере Quickpay.

Модуль не создаёт credit slips. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Quickpay.

Возвраты, сделанные напрямую в менеджере Quickpay, только добавляются в примечания. Статус заказа и credit slips автоматически не меняются. При необходимости обновите их вручную.

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

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

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

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

Решение проблем

Quickpay не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и сохранены и API key, и Private key. Без обоих ключей способ оплаты скрыт. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: обратный вызов Quickpay не дошёл до вашего магазина или был отклонён. Проверьте, что магазин доступен из интернета (без защиты паролем) и что Private key — приватный ключ той же учётной записи Quickpay. Отклонённые обратные вызовы всегда записываются в журнал на странице модуля. Включите Debug log, чтобы видеть каждый обратный вызов.

Журнал показывает Callback rejected: invalid checksum.: приватный ключ в настройках не принадлежит учётной записи, которая отправила обратный вызов. Скопируйте его заново из Settings > Integration в менеджере Quickpay.

Журнал показывает Callback rejected: the private key is not configured.: введите приватный ключ. Обратные вызовы без него никогда не принимаются.

Журнал показывает Callback: no cart found for payment …: обратный вызов относится к платежу Quickpay, который этот магазин не создавал, например к платежу, сделанному вне PrestaShop.

Журнал показывает Could not lock the cart или Cannot create the order: в этот момент применялся другой обратный вызов той же корзины, или заказ не удалось создать (например, модуль отключён). Обратный вызов получает ответ с ошибкой, поэтому Quickpay отправит его снова.

Тестовый платёж не отметил заказ оплаченным: Test payments выключено. В журнале (и в примечании, если заказ существует) написано, что тестовый платёж не принят. Включайте настройку во время тестов и выключайте, когда учётная запись перейдёт в рабочий режим.

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

Test API key показывает «Quickpay отклонил ключ API.»: ключ неверный или принадлежит пользователю без доступа к API. Скопируйте ключ API пользователя API из менеджера Quickpay.

Покупатель видит «Не удалось начать платёж Quickpay.»: посмотрите поле Log на странице модуля. Там показана ошибка Quickpay, например валюта, которую ваша учётная запись Quickpay не принимает.

Возврат не выполняется: у заказа должен быть списанный платёж Quickpay. Сообщение Платёж Quickpay по этому заказу не списан — возвращать нечего. означает, что платёж только авторизован; спишите его или отмените в менеджере Quickpay. Недопустимая сумма возврата: не более … означает, что сумма больше остатка списанного платежа.

Разработчики могут менять параметры ссылки на оплату Quickpay через хук actionQpgQuickpayLinkData.

Удаление

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

Quickpay — товарный знак соответствующего правообладателя. Этот модуль не связан с Quickpay и не одобрен компанией Quickpay.