VibeFox Quickpay for OpenCart — Помощь

Требования

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

Новая установка начинает работу с выключенным способом оплаты.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Quickpay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Пока не сохранены и ключ API, и приватный ключ, страница показывает Quickpay needs setup: enter the API key and the private key. Until both are saved the payment method is hidden at checkout. Пока включён Test payments, страница напоминает выключить его, когда ваш аккаунт Quickpay перейдёт в рабочий режим. Без права изменять расширение страница показывает настройки, но не может их сохранить.

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

Quickpay

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely by card or MobilePay on the Quickpay payment page.

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

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

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

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

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

Callback URL: показывает callback-адрес вашего магазина. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_quickpay_gateway/callback, в OpenCart 4 — так: https://your-store/index.php?route=extension/wcp_quickpay_gateway/payment/wcp_quickpay_gateway.callback. Он формируется из адреса витрины вашей установки OpenCart. Quickpay вызывает его после каждой операции с платежом (авторизация, списание, возврат, отмена). Он передаётся автоматически с каждым платежом, списанием и возвратом, поэтому в Quickpay ничего настраивать не нужно.

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

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

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

Test API key: эта кнопка проверяет ключ, введённый в поле API key (или сохранённый, если поле пусто), аутентифицированным запросом к Quickpay, без сохранения. Ответ: Connection successful — the API key is valid., Quickpay rejected the API key., API key is not configured. или Connection failed: с указанием причины.

Test payments: принимает платежи тестовыми картами Quickpay. Отдельной песочницы у Quickpay нет: пока ваш аккаунт Quickpay работает в тестовом режиме, платежи проводятся тестовыми картами и помечаются как тестовые. Включайте эту опцию только на время тестирования. Когда она выключена, тестовый платёж никогда не отмечает заказ оплаченным. Когда включена, покупатели видят на шаге Confirm Order надпись Test mode: Quickpay test cards are accepted. По умолчанию: off.

Оплата

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

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

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

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

"Payment accepted" status: списанный платёж подтверждён, сумма и валюта совпадают. По умолчанию: Processing.

"Delivered (completed)" status: используется вместо предыдущего, когда Order status after payment равен Delivered (completed). По умолчанию: Complete.

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

Cancelled status: устанавливается, когда платёж заказа на удержании отменяется в Quickpay. Если вы переводите заказ этого расширения в этот статус, его неоплаченная ссылка на оплату удаляется в Quickpay (см. Заказы и возвраты). По умолчанию: Canceled.

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

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

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

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

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

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

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

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

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

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

После оплаты покупатель возвращается в ваш магазин. Сам возврат ничего не отмечает оплаченным. Заказ отмечается оплаченным только после подтверждения Quickpay: подписанный callback-запрос устанавливает статус заказа, когда списанная сумма и валюта совпадают с заказом. Затем заказ получает свой статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. При Authorize only заказ вместо этого получает статус "Quickpay payment on hold" status, а платёж вы списываете позже. Если callback-запрос ещё не пришёл, когда покупатель возвращается, страница Payment confirmation показывает Your payment is being confirmed by Quickpay. You will receive an e-mail as soon as the order is confirmed. с кнопками Check again и Back to checkout. Когда callback Quickpay позже переводит заказ из статуса "Quickpay payment on hold" status в оплаченный статус или в Cancelled status, покупатель получает письмо.

Если покупатель отменяет оплату в окне Quickpay, ссылка на оплату удаляется в Quickpay, и покупатель возвращается на оформление заказа с сообщением The payment was cancelled. You can try again or choose another payment method. Если карта отклонена, сообщение: The payment was not completed. You can try again or choose another payment method. Корзина сохраняется. Новая попытка оплаты того же заказа получает новую ссылку на тот же платёж Quickpay. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; ссылки на оплату предыдущих заказов той же корзины при этом удаляются, поэтому старая ссылка никогда не может быть оплачена параллельно. Пока платёж корзины авторизован и ждёт списания, второй платёж не начинается; покупатель видит страницу Payment confirmation.

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

Если платёж не удалось начать, покупатель остаётся на шаге Confirm Order с сообщением The Quickpay payment could not be started. Please try again or choose another payment method. над кнопкой. Техническая причина записывается в журнал. Если ключи не заполнены, сообщение: Quickpay is not available at the moment. Please choose another payment method.

Callback-запрос и возврат покупателя работают и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы расширений оплаты, а на OpenCart 4 расширение добавляет для них собственное стартовое действие.

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

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

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

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

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

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

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

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

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

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

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

Вкладка VibeFox Quickpay Gateway

В Sales > Orders откройте заказ, оплаченный через Quickpay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Quickpay Gateway показывает Payment ID с пометкой Test payment для тестовых платежей, Status платежа, Amount / refunded, список всех платежей Quickpay заказа (если их несколько), кнопку списания, форму возврата, историю возвратов и Quickpay notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению. Списание и возвраты требуют права изменять расширение (настраивается в System > Users > User Groups).

Списание

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

Возвраты

На вкладке введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via Quickpay. Подтвердите вопрос Refund this amount through Quickpay? This cannot be undone. Для списанных платежей поддерживаются полные и частичные возвраты. Возвраты выполняются в сумме и валюте, которые Quickpay списал, а не на сумму заказа. Quickpay обрабатывает возвраты асинхронно: в истории возвратов появляется requested, а callback переводит его в confirmed или failed и добавляет результат в примечания. Неудачный возврат не считается возвращённым. Если Quickpay сразу отклоняет возврат, вкладка показывает ошибку, и возврат не регистрируется. Полный возврат переводит заказ в Refunded status без уведомления покупателя и без возврата товаров на склад; частичный возврат статус не меняет. Авторизованный, но никогда не списанный платёж вернуть нельзя; отмените его в менеджере Quickpay.

Возвраты товаров в Sales > Returns не возвращают деньги через Quickpay.

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

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

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

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

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

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

Quickpay не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и сохранены и API key, и Private key. Без обоих ключей способ оплаты скрывается, а на странице настроек появляется предупреждение. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что заказ достигает Total, указанного в настройках.

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

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

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

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

В журнале: корзина заблокирована другим запросом: в этот момент применялся другой callback той же корзины. Callback получает ошибку, поэтому Quickpay отправит его повторно.

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

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

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

Покупатель видит The Quickpay payment could not be started.: посмотрите поле Log на странице расширения. Там показана ошибка Quickpay, например валюта, которую ваш аккаунт Quickpay не принимает.

Возврат не выполняется: у заказа должен быть списанный платёж Quickpay. Сообщение The Quickpay payment of this order has not been captured — there is nothing to refund. означает, что платёж только авторизован; спишите его или отмените в менеджере Quickpay. Invalid refund amount: at most … означает, что сумма больше остатка списанного платежа.

Для разработчиков: перед созданием ссылки на оплату расширение вызывает событие OpenCart qpg_quickpay_link_data с параметрами ссылки и заказом.

Удаление

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

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

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