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 використовується в режимі live або навпаки.

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, і поля live, коли його вимкнено. Обидва набори залишаються збереженими.

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 для production (починається з sq0idp-).

Live Access Token: ваш Access Token Square для production.

Live Location ID: ваш Location ID Square для production.

Збережені access token ніколи не показуються знову. Поле залишається порожнім і показує Збережено — залиште порожнім, щоб зберегти. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved secrets: позначте access token і натисніть 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 або production) і на локацію, де було здійснено платіж, тож має бути заданий 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 (референс = ID кошика). Якщо покупець пробує знову, модуль спершу шукає попередній платіж і створює замовлення з ним, замість повторного списання.

Покупець побачив Ваш платіж отримано, але замовлення не вдалося завершити автоматично: картку списано, але 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.