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 може списувати кошти лише у валюті локації: плагін запам'ятовує валюту перевіреної локації та приховує спосіб оплати на сторінці оформлення замовлення для будь-якої іншої валюти, а сторінка налаштувань продовжує показувати попередження. Плагін також попереджає, якщо 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 суму замовлення у валюті замовлення, з ID замовлення як посиланням, приміткою Order # з номером замовлення та назвою вашого сайту, а також з електронною поштою для рахунку. Платіж фіксується одразу. Замовлення позначається оплаченим лише після підтвердження Square: відповідь Square має показувати платіж зі статусом COMPLETED на точну суму замовлення, у його валюті, з його ID і для тієї самої локації. Після цього покупець переходить на сторінку підтвердження замовлення. Якщо платіж не COMPLETED або будь-яке значення відрізняється, замовлення переводиться на утримання з приміткою, а покупець однаково переходить на сторінку підтвердження замовлення.

Одночасно виконується лише одна спроба оплати на замовлення. Якщо покупець натискає двічі або платить у двох вкладках, друга спроба показує Це замовлення вже оплачується. Зачекайте мить і перевірте свою електронну пошту, перш ніж повторювати спробу. Запити ідемпотентні: те саме замовлення, токен і сума ніколи не створюють другий платіж.

Якщо Square не відповідає (проблема з мережею, тайм-аут, помилка сервера), запит повторюється один раз з тим самим ключем ідемпотентності. Якщо відповіді все ще немає, покупець бачить Не вдалося отримати підтвердження від платіжного провайдера. Зачекайте хвилину і спробуйте знову: якщо з вашої картки вже було списано кошти, платіж буде визнано, і з вас не стягнуть плату двічі. У примітці до замовлення пропонується перевірити Square Dashboard. Під час наступної спроби плагін спершу шукає в Square попередній платіж цього замовлення і завершує замовлення з ним, а не списує картку знову.

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

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці 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.