VibeFox Square for OpenCart — Помощь

Требования

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

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

4. Введите лицензионный ключ и учётные данные Square так же, как в шагах с 3 по 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Square Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Square Gateway сейчас работает в режиме SANDBOX. Реальные списания не выполняются., пока включён режим песочницы. Здесь же выводятся предупреждения, если Square включён, но Application ID, Access Token или Location ID выбранного режима не заполнены (тогда способ оплаты скрыт на оформлении заказа), если Square не может работать с валютой по умолчанию вашего магазина и если валюта вашей локации Square отличается от неё. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении Title не должен быть пустым (до 128 символов), Sort Order должен быть целым числом (отрицательные значения допускаются), Total должен быть числом не меньше 0, а географическая зона и статусы заказов должны существовать; иначе ничего не сохраняется. Затем расширение проверяет учётные данные выбранного режима в Square. Настройки сохраняются в любом случае, а предупреждения появляются в красном блоке над настройками: Square отклонил Access Token, Location ID не найден для этого токена, учётные данные не удалось проверить или валюта локации отличается от валюты магазина. Square может списывать деньги только в валюте локации: расширение запоминает валюту проверенной локации и скрывает способ оплаты для заказов в любой другой валюте. Оно также предупреждает, если Application ID из песочницы используется в рабочем режиме или наоборот.

Square

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

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

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

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

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

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

Аккаунт Square

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

Sandbox Mode: платежи уходят в песочницу Square, реальные деньги не списываются. Используйте тестовые карты Square. По умолчанию: включено. Возвраты по заказу всегда выполняются в той среде и на той локации, где был оплачен заказ.

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

Sandbox Access Token: ваш Access Token Square для песочницы.

Sandbox Location ID: ваш Location ID Square для песочницы.

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

Live Access Token: ваш Access Token Square для рабочей среды.

Live Location ID: ваш Location ID Square для рабочей среды.

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

Заказы

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

Order Status After Payment: Square провёл платёж точно на сумму и валюту заказа. По умолчанию: Processing.

On Hold (Review) Status: платёж требует вашей проверки (см. Статусы заказов). По умолчанию: Pending, так как в OpenCart нет статуса On hold. Свой статус можно создать в System > Localisation > Order Statuses и выбрать его здесь.

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

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

Debug log: ошибки и предупреждения записываются всегда. Включите, чтобы записывать также каждый запрос и ответ без данных карт и ключей в wc_sqg_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть из браузера; при размере 5 МБ он переименовывается в wc_sqg_debug.old.log.php. По умолчанию: выключено.

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

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

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

Экспорт: Download JSON сохраняет настройки в файл JSON. Access Token не экспортируются.

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit / debit card). На шаге Confirm Order покупатель видит Credit / debit card (Square), ваше описание, РЕЖИМ SANDBOX — реальные списания не выполняются., пока включён режим песочницы, и форму карты Square. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, карта токенизируется в браузере с проверкой покупателя (3-D Secure / SCA): сумма заказа, валюта и адрес оплаты передаются в Square, и банк покупателя может запросить подтверждение. Ваш магазин получает только одноразовый токен. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options. Форма карты Square затем появляется в блоке подтверждения внизу страницы оформления заказа, над Confirm Order.

Затем расширение списывает токен через Square Payments API на сумму заказа в валюте заказа, с номером заказа как ссылкой, примечанием Order # с номером заказа и названием вашего магазина, а также с e-mail покупателя. Платёж списывается сразу. Заказ отмечается оплаченным только после подтверждения Square: ответ Square должен показывать платёж со статусом COMPLETED на точно совпадающие сумму, валюту, номер заказа и локацию. Затем заказ получает Order Status After Payment стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart с сообщением Оплата картой получена. и ссылкой View the receipt на чек Square. Если платёж не COMPLETED или какое-либо значение не совпадает, заказ получает On Hold (Review) Status, а страница показывает Оплата картой получена и проходит проверку. Мы обновим ваш заказ, как только проверка будет завершена.

По каждой корзине одновременно выполняется только одна попытка оплаты. Если покупатель нажимает дважды или платит в двух вкладках, вторая попытка видит Этот заказ уже оплачивается. Подождите немного и проверьте e-mail, прежде чем пробовать снова. Запросы идемпотентны, а OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, поэтому расширение отслеживает корзину: уже оплаченная корзина никогда не списывается повторно, и покупатель сразу попадает на страницу успешного оформления.

Если Square не отвечает (проблема с сетью, тайм-аут, ошибка сервера), запрос повторяется один раз с тем же ключом идемпотентности. Если ответа по-прежнему нет, расширение сразу ищет платёж по этому заказу в Square. Если платёж найден, заказ получает статус из него. Если платёж не найден, покупатель остаётся на шаге Confirm Order с сообщением Не удалось получить подтверждение от платёжного провайдера. Подождите минуту и попробуйте снова — если карта уже списана, платёж будет распознан и второго списания не будет. При следующей попытке той же корзины сначала снова ищется предыдущий платёж. Если Square не отвечает и на поиск, заказ получает On Hold (Review) Status без платежа, с примечанием, что карта могла быть списана, а страница успеха показывает Не удалось получить подтверждение оплаты картой от Square. Проверьте e-mail и выписку по карте, прежде чем платить снова, или свяжитесь с нами.

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

OpenCart 4 хранит один заказ для оформления и обновляет его: если карту отклонили, покупатель оплачивает тот же заказ снова, а если Square не ответил на платёж, следующая попытка этого заказа сначала ищет предыдущий платёж. Если заказ оформления уже имеет статус (он был оплачен или закрыт магазином), а в корзине появились новые товары, покупатель возвращается к оформлению заказа, и новая корзина оплачивается новым заказом.

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

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

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

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

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

On Hold (Review) Status (по умолчанию Pending): Square ответил платежом, который не COMPLETED (например APPROVED или PENDING), либо с другой суммой, валютой, ссылкой или локацией. Примечание Платёж Square требует проверки показывает ID платежа, статус и суммы. Этот статус также используется, когда заказ изменился во время оплаты, и когда ответ Square потерян и не может быть проверен (тогда платёж не записывается, а примечание просит проверить платежи локации в Square Dashboard по номеру заказа в качестве ссылки). Проверьте платёж в Square Dashboard перед отправкой заказа.

Refunded Status (по умолчанию Refunded): платёж полностью возвращён через расширение.

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

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

Вкладка VibeFox Square Gateway

В Sales > Orders откройте заказ, оплаченный через Square. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Square Gateway показывает Payment ID Square (со ссылкой на платёж в Square Dashboard) с меткой Sandbox для платежей песочницы, Status Square, бренд Card и последние 4 цифры, суммы Paid / order / refunded, Environment / location, ссылку на Square receipt, форму возврата, историю возвратов и Square notes заказа. Номера карт никогда не сохраняются. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

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

Возвраты товаров в Sales > Returns не возвращают деньги через Square. Square выполняет возвраты на своей стороне: возврат, который Square отклонит позже, не сообщается обратно, а возвраты, сделанные в Square Dashboard, не появляются в OpenCart.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Square Gateway — первый блок в Extensions > Extensions > Payments > VibeFox Square Gateway > Edit, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой лицензия активна, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-square и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Менять ключ могут только администраторы с правом Modify на расширение. Тексты блока следуют языку админки (включены английский и русский).

Если ключ не принят, блок указывает причину, например Ключ не найден, Этот ключ относится к другому продукту, Достигнут лимит доменов или Лицензия истекла с датой. После смены адреса магазина или после освобождения места для домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

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

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

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

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

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

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

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

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

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

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

Покупатель увидел сообщение «Платёж получен, но заказ не удалось завершить автоматически»: карта была списана, но OpenCart не смог установить статус заказа. Прочитайте журнал, затем завершите заказ вручную или верните платёж в Square Dashboard.

Покупатель видит сообщение «Этот способ оплаты недоступен для вашего заказа»: оформление заказа больше не соответствует заказу, способ оплаты в это время был выключен или валюту заказа нельзя списать. Покупатель перезагружает оформление заказа или выбирает другой способ оплаты.

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

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

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

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

Удаление

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

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

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