VibeFox Satispay for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша версія з розширенням OpenSSL. Розширення створює свої ключі RSA за допомогою OpenSSL.

Валюта: EUR. Satispay приймає платежі лише в євро. Валюта EUR має бути увімкнена в System > Localisation > Currencies, а спосіб оплати відображається лише тоді, коли покупець вибрав EUR.

Обліковий запис Satispay: обліковий запис Satispay Business. Жодних ключів API копіювати не потрібно: розширення підключається за допомогою одноразового коду активації, який ви створюєте в Satispay Business Dashboard (див. Configuration). Для тестів потрібен тестовий обліковий запис sandbox Satispay, який запитується в Satispay для розробників.

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

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

Встановлення

Архів для завантаження — це один zip-файл з пакетами для обох версій OpenCart. Розпакуйте його на своєму комп’ютері. Він містить README.txt, пакет для OpenCart 3 wcp_satispay_gateway-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_satispay_gateway.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

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

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Satispay Gateway і натисніть Install (зелена кнопка +). Вашому користувачу-адміністратору потрібне право змінювати список розширень оплати.

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

4. Оберіть середовище: увімкніть Sandbox Mode для тестів, залиште вимкненим для реальних платежів.

5. Вставте код активації цього середовища в Activation Code і натисніть Save. Поле Status тоді покаже Connected з Key ID.

6. Увімкніть Enable/Disable і натисніть Save. Протестуйте платіж у sandbox, потім вимкніть Sandbox Mode і підключіть робоче середовище з робочим кодом активації.

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_satispay_gateway.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з’являється у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Satispay Gateway, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ, оберіть середовище і підключіть його кодом активації, як у кроках з 3 до 6 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише callback URL (див. Payment notifications).

Нова інсталяція починає роботу з вимкненим способом оплати та вибраним робочим середовищем.

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Satispay Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо спосіб оплати увімкнено, але використовуване середовище не підключено (тоді спосіб оплати приховано під час оформлення замовлення), і якщо валюта магазину за замовчуванням не EUR (тоді спосіб оплати показується лише тоді, коли покупець вибрав EUR). Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження Title має містити від 1 до 128 символів, Sort Order має бути цілим числом (від’ємні значення дозволені), Total має бути числом, 0 або більше, а геозона та статуси замовлень мають існувати. Якщо значення неправильне, нічого не зберігається, а код активації не надсилається.

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

Enable/Disable: Enable Satispay payment вмикає або вимикає спосіб оплати. Default: off.

Title: назва способу оплати, яку бачать покупці під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. Default: Satispay. Обов’язкове поле, до 128 символів.

Description: текст, який показується покупцю на кроці Confirm Order над кнопкою підтвердження. Default: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Sort Order: положення Satispay серед способів оплати під час оформлення замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати Satispay лише для платіжних адрес із вибраної геозони. Default: All zones. Геозони налаштовуються в System > Localisation > Geo Zones.

Total: сума оформлення замовлення у валюті магазину за замовчуванням, яку має досягти замовлення, перш ніж буде запропоновано Satispay: число, 0 або більше. Залиште порожнім, щоб пропонувати Satispay за будь-якої суми.

Підключення до Satispay

Status: стан обох середовищ, наприклад Live: Connected з Key ID або Sandbox: Not connected, а також яке середовище in use. Поки використовуване середовище не підключено, у полі написано: Satispay is hidden at checkout until the environment in use is connected.

Sandbox Mode: використовує тестове середовище (sandbox) Satispay. Платежі в sandbox не списуються. Default: off. У sandbox і робочого середовища різні ключі: підключайте кожне середовище за допомогою коду активації саме цього середовища. Поки використовується sandbox, покупці бачать на кроці Confirm Order повідомлення Sandbox mode: no real money is charged.

Activation Code: щоб підключити вибране вище середовище, вставте новий 6-символьний код активації та натисніть Save. Робочі коди створюються в Satispay Business Dashboard, у розділі Online shop (поле містить посилання на нього). Коди sandbox видаються разом з тестовим обліковим записом Satispay. Код використовується один раз і не зберігається. Залиште поле порожнім, щоб зберегти поточне підключення.

Коли ви зберігаєте з кодом, спочатку зберігаються налаштування. Далі розширення створює пару ключів RSA, надсилає відкритий ключ і код до Satispay та зберігає Key ID і ключі використовуваного середовища. Закриті ключі ніколи не показуються та не експортуються. У разі успіху сторінка показує, наприклад, Satispay Live connected. Key ID: і далі ідентифікатор. Якщо Satispay відхиляє код, сторінка показує Satispay activation failed: з повідомленням Satispay і просить перевірити, що код належить цьому середовищу і ще не використаний; поточне підключення зберігається. Код, що містить не від 4 до 64 букв і цифр, відхиляється до надсилання будь-чого. Збереження нового коду для середовища замінює його попереднє підключення.

Сповіщення про платежі

У Satispay нічого налаштовувати не потрібно. Кожен платіж має власну callback URL, яку Satispay викликає, коли платіж змінюється, а розширення повторно зчитує платіж з API Satispay перед зміною замовлення. Поле Callback URL показує приклад цієї URL. У OpenCart 3 вона має такий вигляд: https://your-store/index.php?route=extension/payment/wcp_satispay_gateway/callback&satispay_p_order={order}&payment_id={uuid}, в OpenCart 4 — https://your-store/index.php?route=extension/wcp_satispay_gateway/payment/wcp_satispay_gateway.callback&satispay_p_order={order}&payment_id={uuid}. Вона формується з адреси вітрини вашої інсталяції OpenCart. URL має бути доступною з інтернету: перед нею не повинно бути брандмауера чи базової автентифікації. Режим технічного обслуговування OpenCart її не блокує. Якщо callback не може дістатися до вашого магазину, замовлення підтверджується, коли покупець повертається.

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення, missing order). Замовлення отримує статус лише після того, як Satispay прийняв платіж. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Order Status After Payment: статус, який отримує замовлення після прийняття платежу. Default: Processing.

Satispay Payment On Hold Status: гроші отримано, але замовлення потребує перевірки (див. Order statuses). Default: Pending, бо в OpenCart немає статусу On hold. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

Refunded Status: встановлюється після повного повернення платежу зі сторінки замовлення. Default: Refunded.

Додатково

Debug log: записує виклики API та події платежів у файл satispay_p_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити через веб; при досягненні 5 МБ його переміщують до satispay_p_debug.old.log.php. Ключі, код активації та дані покупців не записуються. Помилки записуються завжди, навіть коли цю опцію вимкнено. Default: off.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Delete data on uninstall: коли увімкнено, видалення розширення прибирає налаштування шлюзу, ключі Satispay обох середовищ і журнал. Збережені для замовлень платежі та повернення Satispay завжди зберігаються. Default: off.

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

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

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Підключення до Satispay зберігається.

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

На кроці Payment Method покупець вибирає спосіб оплати (за замовчуванням Satispay). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to the Satispay page: scan the QR code with the Satispay app or confirm the payment on your phone. OpenCart створює замовлення на цьому кроці, все ще без статусу. Коли покупець натискає Confirm Order, розширення створює платіж Satispay на суму замовлення в євро з номером замовлення як посиланням і перенаправляє покупця на сторінку оплати Satispay. На комп’ютері покупець сканує QR-код застосунком Satispay. На телефоні покупець підтверджує платіж у застосунку. В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Satispay: розширення зчитує платіж через API Satispay, перевіряє, що його створено для цього замовлення, і порівнює його статус, суму (у центах) та валюту із замовленням. Це відбувається і тоді, коли Satispay викликає callback URL, і тоді, коли покупець повертається, — що станеться раніше. Далі замовлення отримує статус стандартним способом OpenCart, зі звичайними листами про замовлення та оновленням запасів, а покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо Satispay ще не підтвердив платіж, коли покупець повертається, сторінка Payment confirmation показує Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. і кнопку Check again. Callback встановлює статус замовлення, щойно отримує сповіщення.

Якщо покупець залишає сторінку Satispay без оплати, розширення скасовує платіж у Satispay, тож покинуту сторінку вже не можна оплатити. Покупець повертається до оформлення замовлення з повідомленням Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. Таке ж повідомлення з’являється, коли покупець відхиляє платіж у застосунку. Кошик зберігається.

OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його, тож після скасованого платежу те саме замовлення оплачується новим платежем Satispay. Перед створенням нового платежу Satispay перевіряються попередні платежі кошика: платіж в очікуванні скасовується в Satispay, а якщо якийсь уже оплачено, він підтверджує своє замовлення; другий платіж не виконується, і покупець одразу переходить на сторінку успіху.

В OpenCart 4 повідомлення про скасований платіж показується над сторінкою оформлення замовлення. Якщо замовлення оформлення тим часом було закрито магазином (наприклад, скасовано або повернуто кошти), або його вже оплачено, але кошик відтоді змінився, зокрема нова кількість, покупця повертають до оформлення з повідомленням Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. над сторінкою оформлення, а наступне натискання Confirm Order оплачує нове замовлення.

Якщо платіж не вдалося розпочати, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою: Satispay is not available at the moment. Please choose another payment method., коли Satispay відхиляє ключі; Satispay supports EUR currency only. для замовлення в іншій валюті; або Unable to create the Satispay payment. Please try again or choose another payment method. для інших помилок. Причина записується в журнал.

Callback і повернення покупця працюють і тоді, коли магазин перебуває в режимі технічного обслуговування: OpenCart 3 пропускає запити розширень оплати, а в OpenCart 4 розширення додає для них стартову дію.

Розширення приймає лише разові платежі в євро. Воно не підтримує підписок, збережених способів оплати, попередніх авторизацій і талонів на харчування. Планової перевірки платежів в очікуванні немає: якщо ні callback Satispay, ні повернення покупця не дійдуть до вашого магазину, замовлення залишиться без статусу, а платіж буде видно в Satispay Dashboard.

Замовлення та повернення коштів

Статуси замовлень

No status (missing order): покупця перенаправили до Satispay, і він не оплатив, або Satispay ще не підтвердив платіж. У Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders. Скасований платіж Satispay залишає замовлення без статусу, і покупець може оплатити знову.

Order Status After Payment (default Processing): платіж прийнято. Примітка показує платіж Satispay, суму та те, як його було перевірено (callback, перенаправлення або оформлення замовлення).

Satispay Payment On Hold Status (default Pending): Satispay повідомив про суму або валюту, що відрізняються від суми замовлення, або платіж було прийнято після того, як замовлення отримало інший статус (наприклад, скасовано). Примітка пояснює це. Перевірте платіж у Satispay Dashboard, а потім виконайте замовлення або поверніть платіж. Якщо пізніше буде прийнято інший платіж того самого кошика з правильною сумою, замовлення перейде до Order Status After Payment.

Refunded Status (default Refunded): платіж повністю повернено через розширення.

Якщо другий платіж прийнято для замовлення, яке вже оплачено, або для іншого замовлення того самого кошика, оплачене замовлення не змінюється. Примітка просить повернути дублікат платежу через Satispay Dashboard.

Примітки — це записи в History замовлення, які покупець не бачить.

VibeFox Satispay Gateway tab

У Sales > Orders відкрийте замовлення, оплачене через Satispay. У нижній частині сторінки замовлення, поруч із History і Additional, вкладка VibeFox Satispay Gateway показує Satispay payment ID з міткою Sandbox для платежів у sandbox, Status платежу, суми Paid / refunded, форму повернення, історію Refunds, список Satispay payments of this cart з кожною спробою оплати, її замовленням і середовищем, а також Satispay notes замовлення. Вкладка показується користувачам, які мають доступ до розширення.

Повернення коштів

На вкладці VibeFox Satispay Gateway введіть Amount (сума, яку ще не повернуто, підставляється автоматично), за бажанням Reason (optional), і натисніть Refund via Satispay. Підтвердьте питання Refund this amount through Satispay? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право змінювати розширення (встановлюється в System > Users > User Groups). Повернення обмежені сумою, яку Satispay списав за платіж, тож після розбіжності сум можна повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повернення надсилається в середовище, у якому було зроблено платіж (робоче або sandbox), тож це середовище має залишатися підключеним. Повернення вважається виконаним лише тоді, коли Satispay його приймає: успішне повернення додається до історії та приміток з ідентифікатором повернення Satispay і причиною. Якщо Satispay не приймає повернення, вкладка показує помилку, і повернення не записується. Повне повернення встановлює статус Refunded Status без сповіщення покупця і без повернення товарів на склад, як і ручна зміна статусу. Часткове повернення статус не змінює. Повернення доступні після того, як Satispay прийняв платіж.

Повернення товарів у Sales > Returns не повертають гроші через Satispay. Повернення, зроблені в Satispay Dashboard, в OpenCart не реєструються. За потреби оновіть замовлення вручну.

Ліцензійний ключ

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

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on і дату. Після зміни адреси магазину або після звільнення місця для домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, розширення продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: адреса магазину з налаштувань OpenCart. Видалення ключа з магазину не звільняє місце для домену. Звільніть місце у своєму обліковому записі vibefox.net.

Без активного ключа Satispay не показується покупцям під час оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Адміністратор, який увійшов в адмін-панель у тому самому браузері, все ще бачить спосіб оплати в магазині, позначений (unlicensed — visible to admins only), щоб ви могли налаштувати й протестувати розширення до купівлі ключа. В OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тож без активного ключа спосіб оплати приховано для всіх. Після того як ви один раз відкриєте сторінку Edit, на Dashboard адмін-панелі з’явиться нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не зачіпаються: платежі, які вже розпочато, як і раніше підтверджуються, а повернення працюють.

Коли ліцензія спливає, розширення продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус перевіряється автоматично, коли ви відкриваєте Dashboard або сторінку Edit в адмін-панелі: раз на день протягом перших 14 днів після введення ключа, далі раз на тиждень. Cron-завдання не потрібне. Видалення розширення завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Satispay не відображається під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, використовуване середовище підключено (поле Status показує для нього Connected) і покупець вибрав EUR. Також перевірте, що платіжна адреса входить до вибраної Geo Zone і що замовлення досягає Total, заданого в налаштуваннях.

Платіж пройшов, але замовлення залишилося без статусу: замовлення отримає статус, коли Satispay викличе ваш магазин або коли покупець повернеться. Перевірте, що ваш магазин доступний з інтернету, без брандмауера чи базової автентифікації перед callback URL, і увімкніть Debug log, щоб побачити виклики callback у полі Log. Платіж видно в Satispay Dashboard.

Callback відповідає Payment status unavailable, retry later. або Not configured.: розширення не змогло прочитати платіж у Satispay, або середовище платежу не підключено. Жодне замовлення не змінюється. Satispay викличе ще раз. Перевірте статус підключення та журнал.

Callback відповідає Busy, retry later.: кошик у той самий момент підтверджувався іншим запитом, або не вдалося встановити статус замовлення. Satispay викличе ще раз. Журнал показує причину.

Callback відповідає Unknown payment. або Missing or invalid payment_id.: платіж не був створений цим магазином для цього замовлення, або запит не є callback Satispay. Нічого не змінюється.

Активація не проходить: коди активації можна використати лише один раз. Перевірте, що код належить до середовища, вибраного в Sandbox Mode (робочий код для робочого середовища, код sandbox для sandbox), створіть новий код і збережіть знову. Якщо сторінка повідомляє, що не вдалося згенерувати пару ключів RSA, попросіть хостинг увімкнути розширення PHP OpenSSL. Якщо Satispay недоступний, перевірте, що ваш сервер може відкривати вихідні HTTPS-з’єднання.

Satispay зник з оформлення замовлення після переходу з sandbox на робоче середовище: sandbox і робоче середовище використовують різні ключі. Вставте робочий код активації при вимкненому Sandbox Mode і збережіть.

Покупець бачить This payment method is not available.: оформлення замовлення більше не відповідає замовленню, або спосіб оплати тим часом було вимкнено. Покупець перезавантажує сторінку оформлення замовлення.

Замовлення перебуває в статусі перевірки після оплати: прочитайте примітки на вкладці VibeFox Satispay Gateway (див. Order statuses), перевірте платіж у Satispay Dashboard, а потім виконайте замовлення або поверніть платіж.

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

Повернення не проходить, бо середовище більше не підключено: платіж було зроблено в робочому середовищі або в sandbox, а в цього середовища зараз немає ключів. Підключіть його знову за допомогою коду активації або поверніть платіж через Satispay Dashboard.

Повернення не проходить з повідомленням Satispay did not accept the refund: Satispay повернув статус, відмінний від accepted. OpenCart не зареєстрував повернення, і примітка про це є. Перевірте це в Satispay Dashboard.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox Satispay Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень у розділі Orders, які при повторному встановленні повертаються до значень за замовчуванням. В OpenCart 4 також видаляються подія розширення та його стартова дія, яка пропускає callback і повернення покупця в режимі технічного обслуговування. Якщо Delete data on uninstall увімкнено, видаляються решта налаштувань шлюзу (заголовок, опис, режим sandbox, журналювання), ключі Satispay обох середовищ і журнал. Якщо вимкнено, вони зберігаються для пізнішого повторного встановлення, включно з підключенням до Satispay. Збережені для замовлень платежі та повернення Satispay завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення, коли середовище знову підключено. Наявні замовлення зберігають свої примітки про оплату.

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

Satispay є торговою маркою її власника. Це розширення не афілійоване з Satispay і не схвалене Satispay.