VibeFox Square for WooCommerce — Помощь

Требования

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

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

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

Валюта магазина: валюта вашей локации Square: USD, CAD, AUD, JPY, GBP или EUR. Для других валют способ оплаты скрывается на странице оформления заказа. Square работает с продавцами в США, Канаде, Австралии, Японии, Великобритании, Ирландии, Франции и Испании.

Учётная запись Square: нужно приложение в Square Developer Dashboard. Из него вы копируете Application ID и Access Token (страница Credentials) и Location ID (страница Locations). Значения для Sandbox и Production разные. Вебхук не нужен: плагин получает результат платежа прямо из ответа Square.

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

Установка

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

2. Нажмите Activate.

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

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

5. Оставьте включённым Sandbox Mode и введите Application ID, Access Token и Location ID для sandbox (см. раздел «Настройка»). Сохраните: плагин проверит учётные данные в Square.

6. Включите Enable/Disable и проверьте оплату тестовыми картами из руководства Square по sandbox-тестированию. Затем снимите отметку Sandbox Mode, введите учётные данные для производственной среды и сохраните снова.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Square. Над полями страница показывает Square Gateway сейчас работает в режиме SANDBOX. Реальные списания не выполняются., пока включён режим sandbox. Она предупреждает, если Square включён, но Application ID, Access Token или Location ID выбранного режима не заполнены (тогда способ оплаты скрыт на странице оформления заказа), и если Square не может работать с валютой магазина. В списке способов оплаты Square показывает значок Test mode, пока включён режим sandbox.

При сохранении плагин проверяет учётные данные выбранного режима в Square. Вы увидите ошибку, если Square отклонит Access Token, если Location ID не найден для этого токена, если учётные данные не удалось проверить или если валюта локации отличается от валюты магазина. Square может списывать средства только в валюте локации: плагин запоминает валюту проверенной локации и скрывает способ оплаты на странице оформления заказа для любой другой валюты, а на странице настроек сохраняется предупреждение. Также плагин предупреждает, если Application ID из sandbox используется в боевом режиме или наоборот.

General

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

Title: название способа оплаты, которое видит покупатель при оформлении заказа. По умолчанию: Credit / debit card.

Description: описание способа оплаты, которое видит покупатель при оформлении заказа. По умолчанию: Pay securely with your credit or debit card via Square.

Square account

Откройте Square Developer Dashboard, выберите своё приложение и скопируйте Application ID и Access token со страницы Credentials (для Sandbox и Production значения разные), а Location ID — со страницы Locations. Валюта локации должна совпадать с валютой вашего магазина. Страница показывает только поля учётных данных выбранного режима: поля sandbox, пока включён Sandbox Mode, и поля боевого режима, когда он выключен.

Sandbox Mode: Enable sandbox (test) mode. Платежи отправляются в sandbox Square, и реальные деньги не списываются. Используйте тестовые карты Square. По умолчанию: on.

Sandbox Application ID: ваш Application ID Square для sandbox (начинается с sandbox-sq0idb-).

Sandbox Access Token: ваш Access Token Square для sandbox.

Sandbox Location ID: ваш Location ID Square для sandbox.

Live Application ID: ваш Application ID Square для боевого режима (начинается с sq0idp-).

Live Access Token: ваш Access Token Square для боевого режима.

Live Location ID: ваш Location ID Square для боевого режима.

Advanced

Debug log: Log API requests and responses. Ошибки записываются всегда. Включите этот параметр, чтобы записывать также каждый запрос, без данных карт и ключей. Журналы находятся в WooCommerce > Status > Logs, источник wcp_square_gateway. По умолчанию: off.

Delete data on uninstall: Remove all plugin data when the plugin is deleted. Удаляет настройки шлюза и файлы журналов при удалении плагина. Платёжные данные заказов сохраняются. По умолчанию: off.

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

Покупатель выбирает способ оплаты (по умолчанию Credit / debit card) и вводит данные карты в форме Square, которая отображается под описанием. В режиме sandbox на странице оформления заказа показывается уведомление о sandbox. Когда покупатель нажимает Place order, карта токенизируется в браузере с проверкой покупателя (3-D Secure / SCA): сумма, валюта и платёжный контакт передаются в Square, а банк покупателя может запросить подтверждение. Ваш сервер получает только одноразовый токен.

Затем плагин списывает сумму токеном через Square Payments API на сумму заказа в валюте заказа, с номером заказа в качестве ссылки, примечанием Order # с номером заказа и названием вашего сайта, а также с электронной почтой для выставления счёта. Платёж списывается сразу. Заказ отмечается оплаченным только после подтверждения Square: ответ Square должен показывать платёж со статусом COMPLETED на точную сумму заказа, с его валютой, номером заказа и локацией. После этого покупатель переходит на страницу подтверждения заказа. Если платёж не COMPLETED или какое-либо значение отличается, заказ переводится в статус «На удержании» с примечанием, а покупатель всё равно переходит на страницу подтверждения заказа.

Одновременно выполняется только одна попытка оплаты на заказ. Если покупатель нажимает дважды или платит в двух вкладках, вторая попытка показывает Этот заказ уже оплачивается. Подождите немного и проверьте электронную почту, прежде чем повторять попытку. Запросы идемпотентны: один и тот же заказ, токен и сумма никогда не создают второй платёж.

Если Square не отвечает (проблема сети, таймаут, ошибка сервера), запрос повторяется один раз с тем же ключом идемпотентности. Если ответа по-прежнему нет, покупатель видит Мы не смогли получить подтверждение от платёжного провайдера. Подождите минуту и попробуйте снова: если с вашей карты уже списаны деньги, платёж будет распознан, и с вас не возьмут деньги дважды. В примечании к заказу предлагается проверить Square Dashboard. При следующей попытке плагин сначала ищет в Square более ранний платёж по этому заказу и завершает заказ с ним, а не списывает деньги с карты повторно.

Когда банк отклоняет карту, покупатель видит короткое сообщение по коду ошибки Square, например Ваша карта отклонена. Используйте другую карту или способ оплаты., Код безопасности карты (CVV) указан неверно. Проверьте его и попробуйте снова. или Ваш банк требует дополнительной проверки (3-D Secure). Введите данные карты снова и пройдите проверку. Техническая причина записывается в примечания к заказу и в журнал. Покупатель может попробовать снова с другой картой, в том числе позже со страницы Pay for order.

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

Плагин принимает только платежи картами, которые списываются сразу. Не поддерживаются сохранённые карты и профили покупателей, WooCommerce Subscriptions и предзаказы, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH и подарочные карты Square, платежи только с авторизацией, вебхуки Square, а также синхронизация товаров и остатков с Square. Споры управляются в Square Dashboard.

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

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

Pending payment: заказ создан и ещё не оплачен, например после отклонённой карты или потерянного ответа Square.

Processing: Square подтвердил платёж COMPLETED на сумму заказа. Это стандартный статус WooCommerce после оплаты (заказы, содержащие только виртуальные товары для скачивания, переходят в статус «Выполнен»). В примечании к заказу указаны ID платежа Square, бренд карты с последними 4 цифрами и режим (sandbox или боевой). ID транзакции — это ID платежа Square; на экране заказа он ведёт к платежу в Square Dashboard.

On hold: Square ответил платежом, который не является COMPLETED, или с другими суммой, валютой, номером заказа или локацией. Примечание Square payment needs review показывает ID платежа, статус и суммы. Перед отправкой заказа проверьте списание, сумму и валюту в Square Dashboard.

Плагин сохраняет в заказе ID платежа Square, бренд карты и последние 4 цифры, среду и локацию. Номера карт никогда не сохраняются.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Credit / debit card (на кнопке отображается ваш Title). Поддерживаются полные и частичные возвраты. Возврат отправляется в ту среду (sandbox или боевую) и на ту локацию, где прошёл платёж, поэтому должен быть задан Access Token этого режима. Запросы на возврат идемпотентны и повторяются один раз, если Square не отвечает. Возврат, который Square принимает (статус PENDING или COMPLETED), добавляется в примечания к заказу с ID возврата Square. Если Square его отклоняет, WooCommerce показывает ошибку, и возврат не регистрируется.

Square завершает возвраты на своей стороне. Возврат, который Square отклонит позже, в WooCommerce не передаётся, а возвраты, оформленные в Square Dashboard, в WooCommerce не отображаются.

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

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

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

Без активного ключа Square не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит Этот способ оплаты недоступен. Выберите другой. Авторизованные менеджеры магазина по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), поэтому вы можете настроить и проверить плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются: оплаченные заказы остаются оплаченными, а возвраты работают.

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

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

Square не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, а Application ID, Access Token и Location ID текущего режима заполнены. Проверьте, что валюта магазина (или валюта заказа на странице Pay for order) — USD, CAD, AUD, JPY, GBP или EUR и совпадает с валютой вашей локации Square. На странице настроек для каждой из этих проблем выводится предупреждение.

Форма карты не загружается: покупатель видит Не удалось загрузить форму карты. Обновите страницу или выберите другой способ оплаты. Проверьте, что Application ID и Location ID относятся к выбранному режиму (ID sandbox начинаются с sandbox-). Если покупатель нажимает слишком рано, отображается Форма карты ещё загружается. Подождите немного и попробуйте снова.

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

Square отклонил Access Token выбранного режима: токен относится к другому режиму или неверен. Скопируйте его заново со страницы Credentials вашего приложения и проверьте Sandbox Mode.

Location ID не найден для этого Access Token: скопируйте Location ID со страницы Locations того же приложения и того же режима.

Покупатель увидел «Мы не смогли получить подтверждение от платёжного провайдера»: Square не ответил. Прочитайте примечание к заказу и проверьте платежи этой локации в Square Dashboard (ссылка = ID заказа). Если покупатель попробует снова, плагин сначала найдёт более ранний платёж и завершит заказ с ним, а не будет списывать деньги повторно.

Заказ в статусе On hold: прочитайте примечание Square payment needs review. Платёж не был COMPLETED, либо его сумма, валюта или локация отличались от заказа. Проверьте платёж в Square Dashboard, затем выполните заказ или сделайте возврат платежа.

Возврат не проходит с сообщением о режиме: платёж был сделан в режиме sandbox или боевом режиме, а Access Token этого режима не задан. Введите его и повторите попытку.

Другие ошибки: включите Debug log и посмотрите в WooCommerce > Status > Logs, источник wcp_square_gateway.

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

Удаление

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

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