VibeFox Quickpay for WooCommerce — Помощь

Требования

WordPress: 6.2 или новее.

WooCommerce: 7.1 или новее, установлен и активен. Без него плагин не активируется.

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

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

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

Установка

1. В WordPress откройте Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Можно также загрузить папку wcp_quickpay_gateway в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Quickpay > Manage или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

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

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

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Quickpay. Пока не введены ключ API и приватный ключ, Quickpay в списке способов оплаты помечается как требующий настройки и скрывается при оформлении заказа, так как платёж нельзя ни создать, ни подтвердить.

Общие

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

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

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

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

В панели Quickpay (manage.quickpay.net) откройте Settings > Integration. Скопируйте ключ API пользователя API (Settings > Users) и приватный ключ учётной записи. В разделе также показан URL обратного вызова вашего магазина вида https://your-site/wc-api/qpg_quickpay/. Он автоматически передаётся с каждым платежом, поэтому в Quickpay ничего настраивать не нужно.

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

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

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

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

Оплата

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

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

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

Debug log: Enable logging. Журнал находится в WooCommerce > Status > Logs, источник wcp_quickpay_gateway. Ошибки и предупреждения, например отклонённые обратные вызовы и ошибки API Quickpay, записываются всегда. Включите эту опцию, чтобы записывать также каждый запрос и обратный вызов. Ключи API, данные карт и данные покупателей никогда не записываются в журнал. По умолчанию: выключено.

Delete data: Delete the gateway settings and logs when the plugin is deleted. Деактивация плагина ничего не удаляет. Данные заказов (идентификаторы платежей Quickpay, примечания) всегда сохраняются. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Quickpay, отображается с иконками Visa и Mastercard) и оформляет заказ. Плагин создаёт для заказа платёж Quickpay в валюте заказа и ссылку на оплату на сумму заказа, после чего отправляет покупателя в окно оплаты Quickpay. Покупатель платит там одним из способов, включённых в вашем окне оплаты Quickpay. Адрес электронной почты для выставления счёта передаётся в Quickpay. Окно оплаты открывается на языке вашего сайта, если Quickpay его поддерживает (датский, немецкий, английский, испанский, финский, французский, итальянский, нидерландский, норвежский, польский, шведский), в противном случае на английском.

После оплаты покупатель возвращается на страницу «Заказ получен» вашего магазина. Само возвращение ничего не отмечает оплаченным. Заказ отмечается оплаченным только после того, как Quickpay подтвердит его подписанным обратным вызовом и сумма и валюта совпадут с заказом. При Authorize only заказ вместо этого переходит в статус «На удержании», а платёж вы списываете позже.

Если покупатель отменяет оплату в окне Quickpay во время оформления заказа, неоплаченный заказ отменяется стандартным способом WooCommerce, а корзина восстанавливается. На странице Pay for order отмена возвращает покупателя на эту страницу, поэтому заказ остаётся доступным для оплаты. Неудачный или отменённый платёж можно повторить: новая попытка повторно использует платёж Quickpay заказа с новой ссылкой, поэтому старая ссылка никогда не может быть оплачена параллельно. Когда неоплаченный заказ отменяется, его ссылка на оплату удаляется в Quickpay.

Если платёж не удаётся начать, покупатель видит 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.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с WooCommerce High-Performance Order Storage (HPOS).

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

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

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

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

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

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

Failed: попытка оплаты отклонена. Покупатель может оплатить снова.

Cancelled: покупатель отменил оплату в окне Quickpay, заказ был отменён вами или по тайм-ауту резервирования запасов WooCommerce, либо платёж был отменён в панели Quickpay.

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

Списание

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

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Quickpay. Полные и частичные возвраты поддерживаются для списанных платежей. Quickpay обрабатывает возвраты асинхронно: примечание сообщает, что возврат запрошен, а обратный вызов добавляет окончательный результат, confirmed или FAILED с причиной. Если Quickpay сразу отклоняет возврат, WooCommerce показывает ошибку, и возврат не записывается. Авторизованный, но никогда не списанный платёж нельзя вернуть; отмените его в панели Quickpay.

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

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > Quickpay. Вставьте ключ в поле License key и нажмите Activate. В блоке показан статус, например дата, до которой лицензия активна, и ваш домен. Используйте Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает вашу учётную запись vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает его место для домена. Освободите место в вашей учётной записи vibefox.net.

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

Когда лицензия истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

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

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

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

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

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

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

В журнале Callback: order #… is locked by another request.: в этот момент применялся другой обратный вызов того же заказа. Обратный вызов получает ответ с ошибкой, поэтому он не считается обработанным. Если заказ не меняется, проверьте платёж в панели Quickpay.

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

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

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

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

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите место в вашей учётной записи vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его, деактивируйте и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза и журналы плагина (файлы журналов, включая ротированные, и записи журнала в базе данных) удаляются только если была включена опция Delete data. В противном случае они сохраняются для повторной установки. Существующие заказы сохраняют свои платёжные примечания и идентификаторы транзакций.

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