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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша з розширенням OpenSSL. Модуль не встановлюється на старіших версіях PHP або без OpenSSL.

Валюта: EUR. Satispay приймає лише євро, тому спосіб оплати приховано, якщо валюта кошика не EUR.

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

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

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

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

1. У back office відкрийте Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Satispay Gateway у списку модулів і натисніть Configure.

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

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

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

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

Під час встановлення модуль створює статус замовлення Satispay payment on hold. PrestaShop пропонує новий платіжний модуль для всіх валют, країн і груп клієнтів. Обмежити їх можна в Payment > Preferences. Там модуль має бути дозволений для євро.

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

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox Satispay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку.

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

Що бачать клієнти у списку способів оплати.

Enable/Disable: Enable Satispay payment вмикає або вимикає спосіб оплати. За замовчуванням: off.

Title: назва способу оплати, що показується на етапі оформлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Satispay. Обов'язково.

Description: текст під способом оплати на етапі оформлення. За замовчуванням: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

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

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

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

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

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

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

У Satispay нічого налаштовувати не потрібно. Кожен платіж має власний callback URL, який Satispay викликає, коли платіж змінюється, а модуль перед створенням або зміною замовлення повторно отримує платіж через API Satispay. Поле Callback URL показує приклад цієї URL. За увімкнених дружніх URL вона має такий вигляд: https://your-shop/module/wcp_satispay_gateway/callback?id_cart={cart}&payment_id={uuid}, можливо з кодом мови, наприклад /en/. URL має бути доступний з інтернету: без базової автентифікації перед ним. Callback працює, коли магазин у режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

Додатково

Debug log: записує виклики API та події платежів у logs/satispay_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Ключі та дані покупців не журналюються. Помилки журналюються завжди, навіть коли опція вимкнена. За замовчуванням: off.

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

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

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

На етапі оплати клієнт обирає спосіб оплати (за замовчуванням Satispay) і підтверджує замовлення. Модуль створює платіж Satispay на суму кошика в євро з номером кошика як посиланням і надсилає клієнта на сторінку оплати Satispay. На комп'ютері клієнт сканує QR-код застосунком Satispay. На телефоні клієнт підтверджує платіж у застосунку. На цьому етапі замовлення ще не існує.

Після оплати клієнт повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Satispay: модуль отримує платіж через API Satispay, перевіряє, що його створено для цього кошика, і порівнює його статус, суму (в центах) та валюту з кошиком. Це відбувається і коли Satispay викликає callback URL, і коли клієнт повертається, — залежно від того, що станеться першим. Потім замовлення створюється, і клієнт бачить стандартну сторінку підтвердження замовлення. Якщо 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. Те саме повідомлення з'являється, якщо клієнт відхилив платіж у застосунку. Кошик зберігається.

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

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

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

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

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

No order yet: клієнта відправили в Satispay, і він не заплатив, або Satispay ще не підтвердив платіж. Існують лише кошик і платіж Satispay модуля.

Payment accepted: платіж підтверджено. Його записано з ID платежу Satispay як ID транзакції, а примітка показує платіж Satispay, суму та спосіб перевірки (callback, redirect or checkout).

Satispay payment on hold: Satispay повідомив суму або валюту, що відрізняються від суми кошика (наприклад, кошик змінили в іншій вкладці після початку оплати), або платіж прийнято після скасування замовлення. Отримані кошти записуються в замовлення, а примітка це пояснює. Перевірте платіж у Satispay Dashboard, потім виконайте замовлення або поверніть платіж. Якщо пізніше буде прийнято інший платіж для того самого кошика з правильною сумою, замовлення перейде у статус Payment accepted.

Refunded: платіж повністю повернено через модуль.

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

Блок оплати Satispay

На сторінці замовлення показано блок Satispay payment з ID платежу Satispay, його статусом, сплаченою та поверненою сумою, позначкою Sandbox для платежів у sandbox, історією повернень, списком Satispay payments of this cart з усіма спробами оплати та їх середовищем, а також Satispay notes замовлення.

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

У блоці Satispay payment введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via Satispay. Підтвердьте питання Refund this amount through Satispay? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення; доступ до сторінок Modules не потрібен. Повернення обмежені сумою, яку Satispay списав за платіж, тож після розбіжності суми можна повернути не більше того, що клієнт фактично заплатив, а не суму замовлення. Повернення надсилається в те середовище, у якому пройшов платіж (продуктивне або sandbox), тому це середовище має залишатися підключеним. Повернення вважається виконаним лише тоді, коли його приймає Satispay: успішне повернення додається до історії повернень і приміток з ID повернення Satispay та причиною. Якщо Satispay не прийняв повернення, блок показує помилку, і повернення не записується. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

Модуль не створює кредитні ноти. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Satispay. Повернення, зроблені в Satispay Dashboard, у PrestaShop не фіксуються. За потреби оновіть замовлення вручну.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Satispay Gateway — перший блок на сторінці Modules > Module Manager > VibeFox Satispay Gateway > Configure, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен), а також кнопки Check now, щоб знову перевірити статус, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовані рядок Product: presta-payment-satispay і посилання 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.

Без активного ключа Satispay не показується клієнтам під час оформлення замовлення. Якщо платіж все ж розпочато, клієнт бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли в back office, тож спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але не можна протестувати на етапі оформлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не зачіпаються: платежі, які вже розпочато, як і раніше підтверджуються, а повернення працюють.

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

Вирішення проблем

Satispay не з'являється на етапі оформлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, середовище, що використовується, підключено (поле Status показує для нього Connected) і валюта кошика — EUR. У Payment > Preferences перевірте, що модуль дозволений для євро, країни клієнта та групи клієнта.

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

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

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

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

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Satispay Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, видаляються налаштування, ключі Satispay обох середовищ і журнал. Якщо вимкнено, усі налаштування та ключі зберігаються для подальшого повторного встановлення. Платежі та повернення Satispay, збережені для замовлень, і статус замовлення Satispay payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення, коли середовище знову підключено. Наявні замовлення зберігають свої примітки про оплату та ID транзакцій.

Satispay — торговельна марка її правовласника. Цей модуль не пов'язаний із Satispay і не схвалений компанією Satispay.