VibeFox Square for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

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

Валюта: валюта корзины должна совпадать с валютой вашей локации 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. В back office перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

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

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

4. Оставьте включённым Sandbox Mode и введите Application ID, Access Token и Location ID для sandbox (см. Настройка). Нажмите Save: модуль проверит учётные данные в Square.

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

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Square Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Square Gateway сейчас работает в режиме SANDBOX. Реальные списания не производятся., пока включён режим sandbox. Она предупреждает, если Square включён, но у выбранного режима не заполнены Application ID, Access Token или Location ID (тогда способ оплаты скрыт на оформлении заказа), если Square не может работать с валютой магазина по умолчанию и если валюта вашей локации Square отличается от неё.

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

Square

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

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

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

Учётная запись Square

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

Sandbox 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 для боевого режима.

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

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

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

Debug log: ошибки и предупреждения записываются всегда. Включите опцию, чтобы также записывать каждый запрос и ответ, без данных карт и ключей, в файл logs/wc_sqg_debug.log.php в папке модуля. Файл нельзя открыть из веба. По умолчанию: off.

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

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

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

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

Затем модуль списывает токен через Square Payments API на сумму корзины в валюте корзины, с номером корзины в качестве референса, примечанием Cart # с номером корзины и названием вашего магазина и адресом электронной почты покупателя. Платёж захватывается сразу. Заказ отмечается оплаченным только после подтверждения Square: ответ Square должен показывать платёж COMPLETED на сумму корзины, в её валюте, с её номером и для той же локации. Затем заказ создаётся со статусом Payment accepted, а покупатель видит стандартную страницу подтверждения заказа с сообщением Оплата картой получена. и ссылкой на чек Square. Если платёж не COMPLETED или какое-либо значение не совпадает, заказ создаётся со статусом Square payment on hold, а на странице показывается Оплата картой получена и проверяется. Мы обновим ваш заказ, как только проверка завершится.

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

Если Square не отвечает (проблема сети, таймаут, ошибка сервера), запрос повторяется один раз с тем же ключом идемпотентности. Если ответа по-прежнему нет, модуль сразу ищет платёж по этой корзине в Square. Если он найден, заказ создаётся с ним. Если платёж не найден, покупатель остаётся на оформлении заказа с сообщением Не удалось получить подтверждение от платёжного провайдера. Подождите минуту и попробуйте снова — если карта уже была списана, платёж будет распознан и повторного списания не будет. Следующая попытка сначала снова ищет предыдущий платёж. Если Square не удаётся связаться и для поиска, заказ создаётся со статусом Square payment on hold без платежа, с примечанием, что карта могла быть списана, а страница подтверждения показывает Не удалось получить подтверждение оплаты картой от Square. Перед повторной оплатой проверьте электронную почту и выписку по карте или свяжитесь с нами.

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

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

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

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

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

Payment accepted: Square подтвердил платёж COMPLETED на сумму корзины. Платёж записывается с ID платежа Square в качестве ID транзакции, а примечание показывает ID платежа, бренд карты с последними 4 цифрами и режим (sandbox или live).

Square payment on hold: Square ответил платежом, который не в статусе COMPLETED (например APPROVED), либо с другой суммой, валютой, референсом или локацией. Примечание Требуется проверка платежа Square показывает ID платежа, статус и суммы. Платёж COMPLETED записывается в заказ с суммой, которую списал Square. Этот статус также используется, когда корзина изменилась во время оплаты, и когда ответ Square был потерян и его не удалось проверить (тогда платёж не записывается). Проверьте платёж в Square Dashboard до отправки заказа.

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

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

Блок Square

На странице заказа показан блок Square с ID платежа Square (со ссылкой на платёж в Square Dashboard), статусом Square, брендом карты и последними 4 цифрами, суммами Paid / order / refunded, средой и локацией, ссылкой на чек Square, значком Sandbox для платежей в sandbox, историей возвратов и Square notes заказа. Номера карт никогда не сохраняются.

Возвраты

В блоке Square введите сумму (невозвращённая сумма подставляется автоматически), при необходимости причину и нажмите Refund via Square. Подтвердите вопрос Вернуть эту сумму через Square? Это действие нельзя отменить. Поддерживаются полные и частичные возвраты. Нужно право на редактирование заказов. Возвраты делаются в сумме и валюте, которые списал Square, поэтому при расхождении суммы можно вернуть до той суммы, которую покупатель реально заплатил, а не до суммы заказа. Возврат отправляется в среду (sandbox или боевую) и на локацию, где прошёл платёж, поэтому должен быть задан Access Token этого режима. Запросы возврата идемпотентны и повторяются один раз, если Square не отвечает. Возврат, который принял Square (статус PENDING или COMPLETED), добавляется в историю возвратов и примечания с ID возврата Square. Если Square отклоняет его, блок показывает ошибку, и возврат не записывается. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет.

Модуль не создаёт кредитные ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Square. Square завершает возвраты на своей стороне: возврат, который Square позже отклонит, не сообщается обратно, а возвраты, сделанные в Square Dashboard, в PrestaShop не отображаются.

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

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

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

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

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

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

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

Способ оплаты пропал после сохранения: валюта локации Square отличается от валюты корзины. Введите Location ID локации Square в валюте вашего магазина и сохраните снова: способ оплаты снова появится после успешной проверки.

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

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

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

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

Заказ в статусе Square payment on hold: прочитайте примечания в блоке Square (см. Статусы заказов). Проверьте платёж в Square Dashboard, затем отправьте заказ или верните платёж.

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

Другие ошибки: включите Debug log и посмотрите поле Log на странице модуля.

Удаление

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

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