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 для sandbox (див. Налаштування). Натисніть Save: розширення перевірить облікові дані в Square.

5. Увімкніть Enable/Disable, збережіть і перевірте оплату тестовими картками з посібника Square щодо тестування в sandbox. Потім вимкніть 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. Сторінка налаштувань і її поля однакові в обох версіях.

Нове встановлення починається з вимкненим способом оплати та увімкненим режимом sandbox.

Налаштування

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Square Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка показує Square Gateway зараз у режимі SANDBOX. Реальні списання не виконуватимуться., поки увімкнено 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 із sandbox використовується в робочому режимі або навпаки.

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

Sandbox Mode: платежі надсилаються в sandbox Square, і реальні гроші не списуються. Використовуйте тестові картки Square. За замовчуванням: увімкнено. Повернення коштів за замовленням завжди виконуються в тому середовищі та на тій локації, де було оплачено замовлення.

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 для робочого середовища.

Збережені 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 за замовленнями завжди зберігаються. За замовчуванням: вимкнено.

Імпорт / Експорт

Export: Download JSON зберігає налаштування у файл JSON. Access Token не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені Access Token залишаються.

Оформлення замовлення

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Credit / debit card). На кроці Confirm Order покупець бачить Credit / debit card (Square), ваш опис, РЕЖИМ SANDBOX — реальні списання не виконуватимуться., поки увімкнено 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 цифрами та режим (sandbox або робоче середовище).

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, тож після розбіжності суми можна повернути лише те, що покупець фактично сплатив, а не суму замовлення. Повернення надсилається в середовище (sandbox або робоче) і на локацію, де було проведено платіж, тому 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 починаються з 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), платіж повністю повернено, або ваша група користувачів не має права змінювати розширення.

Повернення завершується помилкою з повідомленням про режим: платіж було проведено в sandbox або робочому середовищі, а 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 увімкнено, видаляються інші налаштування шлюзу (назва, опис, режим sandbox, облікові дані, журналювання) і файли логів. Якщо вимкнено, вони зберігаються для майбутнього повторного встановлення. Платежі й повернення Square за замовленнями завжди зберігаються, тому замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

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

Square є товарним знаком його відповідного власника. Це розширення не пов’язане з Square і не схвалене Square.