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

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис Stripe: вам потрібні секретні API-ключі вашого облікового запису Stripe та кінцева точка вебхука в Stripe Dashboard (див. Налаштування). Використовуються лише секретні ключі та секрети підпису вебхуків. Публічні ключі (pk_...) не потрібні, бо Stripe Checkout — це сторінка, яку розміщує Stripe.

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

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

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

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

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

4. Вставте секретні ключі Stripe, налаштуйте вебхук у Stripe Dashboard і вставте його секрети підпису (див. Налаштування).

5. Увімкніть Enable/Disable і натисніть Save. Протестуйте платіж у тестовому режимі карткою 4242 4242 4242 4242, а потім вимкніть Test Mode.

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

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Stripe Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо для поточного режиму немає секретного ключа (тоді спосіб оплати приховано на оформленні замовлення) або немає секрету підпису вебхука (тоді замовлення підтверджуються лише тоді, коли клієнт повертається до магазину). Поки тестовий режим увімкнено, сторінка також показує Тестовий режим увімкнено: реальні платежі не списуються.

Stripe Checkout

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

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

Description: текст під способом оплати на оформленні замовлення. Default: Pay securely with your credit or debit card via Stripe.

API-ключі

Скопіюйте секретні ключі з Stripe Dashboard > Developers > API keys. Тестові та робочі ключі розділені. Тестовий режим використовує лише тестові ключі, робочий — лише робочі. Під час збереження модуль попереджає, якщо значення не починається з очікуваного префікса, наприклад коли замість секретного ключа вставлено публічний.

Test Mode: використовує тестові ключі Stripe. Реальні гроші не списуються; платіть тестовими картками Stripe, наприклад 4242 4242 4242 4242. Default: on. Вимкніть, щоб приймати реальні платежі. Поки режим увімкнено, клієнти бачать під способом оплати: Тестовий режим: реальний платіж не здійснюється.

Test Secret Key: секретний ключ тестового режиму. Починається з sk_test_ (або rk_test_ для обмеженого ключа).

Test Webhook Secret: секрет підпису (whsec_...) кінцевої точки вебхука, створеної в тестовому режимі.

Live Secret Key: секретний ключ робочого режиму. Починається з sk_live_ (або rk_live_ для обмеженого ключа).

Live Webhook Secret: секрет підпису (whsec_...) кінцевої точки вебхука, створеної в робочому режимі.

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

Clear saved secrets: позначте ключ або секрет і натисніть Save, щоб його видалити. Порожнє поле зберігає збережене значення.

Webhook

Вебхук повідомляє вашому магазину, що платіж здійснено. У Stripe Dashboard > Developers > Webhooks додайте кінцеву точку в тестовому режимі і ще одну в робочому. Використовуйте URL, показаний у Endpoint URL у цьому розділі. З дружніми URL він має такий вигляд: https://your-shop/module/wcp_stripe_gateway/webhook, можливо з кодом мови, наприклад /en/. Копіюйте URL точно так, як його показують налаштування, бо Stripe не переходить за перенаправленнями.

Оберіть для кожної кінцевої точки такі події (вони також перелічені в цьому розділі):

checkout.session.completed: клієнт завершив оплату на сторінці Stripe.

checkout.session.async_payment_succeeded: відкладений платіж підтверджено.

checkout.session.async_payment_failed: відкладений платіж не вдався.

charge.refunded: платіж повернено, наприклад у Stripe Dashboard.

Після створення кожної кінцевої точки скопіюйте її секрет підпису (whsec_...) зі Stripe і вставте його в Test Webhook Secret або Live Webhook Secret. Вебхуки без дійсного підпису відхиляються. Подія має бути підписана секретом того режиму, в якому здійснено платіж, тож тестовий секрет ніколи не підтверджує робочий платіж. Без вебхука замовлення створюється лише тоді, коли клієнт повертається до магазину після оплати.

Замовлення

Order Status After Payment: статус замовлення, який встановлюється після успішної оплати.

Payment accepted (default): стандартний статус PrestaShop для оплачених замовлень.

Delivered (completed): кожне оплачене замовлення отримує статус «Доставлено».

Stripe payment on hold (review): кожне оплачене замовлення очікує вашої ручної перевірки. Платіж залишається записаним у замовленні.

Відкладені платежі очікують у статусі Awaiting Stripe payment. Розбіжності суми чи валюти завжди переводять замовлення в Stripe payment on hold.

Додатково

Logging: записує запити Stripe і вебхуки у файл logs/strg_debug.log.php у папці модуля. Файл не можна відкрити з веб. Ключі та дані клієнтів не записуються. Default: off. Поки вимкнено, нічого не записується.

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

Delete Data on Uninstall: якщо увімкнено, видалення модуля видаляє налаштування шлюзу і журнал. Транзакції та повернення Stripe, а також статуси замовлень модуля завжди зберігаються, щоб існуючі замовлення працювали далі. Default: off.

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

На етапі оплати клієнт обирає спосіб оплати (за замовчуванням Stripe) і бачить примітку Вас буде перенаправлено на Stripe для безпечного завершення оплати. Після підтвердження модуль створює сесію Stripe Checkout на суму кошика у валюті кошика і надсилає клієнта на сторінку оплати Stripe. Там клієнт платить кредитною або дебетовою карткою. E-mail клієнта передається в Stripe, а на сторінці Stripe платіж відображається як Cart # з номером кошика. На цьому етапі замовлення ще не існує.

Після оплати клієнт повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Stripe: через підписаний вебхук або через серверний запит до Stripe, коли клієнт повертається. Тоді замовлення створюється, і клієнт бачить стандартну сторінку підтвердження замовлення з повідомленням Ваш платіж через Stripe отримано. Для відкладеного платежу сторінка показує Ваш платіж підтверджується Stripe. Ви отримаєте e-mail, щойно його буде підтверджено. Якщо відкладений платіж пізніше не вдається, сторінка показує Ваш платіж через Stripe не було завершено. Будь ласка, зв'яжіться з нами щодо цього замовлення. Якщо Stripe ще не підтвердив платіж, коли клієнт повертається, сторінка Підтвердження платежу показує той самий текст і кнопку Check again; вебхук створить замовлення, щойно він надійде.

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

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

Якщо купон у кошику перестає бути дійсним між оплатою та її підтвердженням, PrestaShop видаляє його із замовлення. Замовлення тоді переходить у статус Stripe payment on hold з приміткою, бо клієнт заплатив ціну зі знижкою.

Вебхук працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами для вашого магазину.

Модуль приймає лише платежі карткою, які списуються одразу на сторінці Stripe. Він не підтримує збережені картки, підписки чи регулярні платежі, форму картки на сайті, кнопки Apple Pay чи Google Pay на вашому сайті, а також окремі авторизацію та списання.

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

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

Замовлення ще немає: клієнта надіслано на Stripe, і він не заплатив, або Stripe ще не підтвердив платіж. Існує лише кошик.

Payment accepted, Delivered or Stripe payment on hold: платіж підтверджено. Статус відповідає Order Status After Payment. Платіж записується з ID платежу Stripe (pi_...) як ID транзакції, а примітка показує платіж Stripe, сесію та спосіб підтвердження (вебхук або повернення).

Awaiting Stripe payment: клієнт завершив оформлення з відкладеним способом оплати. Замовлення переходить в оплачений статус, коли Stripe підтверджує платіж.

Stripe payment on hold after payment: Stripe повідомив суму або валюту, відмінні від суми замовлення (наприклад, кошик змінили після початку платежу), купон було видалено або платіж надійшов після скасування замовлення. Примітка пояснює. Перевірте замовлення та виконайте його або поверніть платіж.

Payment error: відкладений платіж не вдався.

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

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

Блок Stripe payment

Сторінка замовлення показує блок Stripe payment з ID платежу Stripe (посилання на платіж у Stripe Dashboard), сесією Checkout, статусом платежу, сумою, яку списав Stripe, і сумою повернення, позначкою Test mode для тестових платежів, історією повернень і Stripe notes замовлення.

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

У блоці Stripe payment введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via Stripe. Підтвердьте питання Повернути цю суму через Stripe? Цю дію не можна скасувати. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення. Повернення виконуються в сумі та валюті, які списав Stripe, тож після розбіжності суми чи валюти можна повернути не більше того, що клієнт реально заплатив, а не суму замовлення. Повернення надсилається в тому режимі, в якому здійснено платіж (тестовому або робочому), тому секретний ключ цього режиму має бути вказаний. Якщо Stripe не приймає повернення, блок показує помилку і повернення не записується. Успішне повернення додається до історії повернень і приміток з ID повернення Stripe. Повне повернення переводить замовлення у статус Refunded. Часткове повернення статус не змінює. Повернення доступні після того, як Stripe підтвердив платіж.

Модуль не створює кредитні нотатки. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Stripe.

Повернення, зроблені в Stripe Dashboard, надходять через вебхук charge.refunded і додаються до приміток із загальною сумою повернень у Stripe. Статус замовлення та кредитні нотатки автоматично не змінюються. За потреби оновіть їх вручну.

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

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

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

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

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

Stripe не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і в поточному режимі є секретний ключ: Test Secret Key у тестовому режимі, Live Secret Key у робочому. Сторінка налаштувань показує попередження, коли ключа немає. У Payment > Preferences перевірте, що модуль дозволений для валюти кошика, країни клієнта та групи клієнта.

Платіж пройшов, але замовлення не створено: вебхук не працює. У Stripe Dashboard перевірте, що кінцева точка існує в режимі, який ви використовуєте (тестовому або робочому), що її URL точно збігається з показаним у Endpoint URL, і що вибрано всі чотири події. Перевірте, що секрет підпису цієї кінцевої точки є в потрібному полі (Test Webhook Secret або Live Webhook Secret). Stripe Dashboard показує відповідь вашого магазину на кожен вебхук. Замовлення також створюється, коли клієнт повертається до магазину після оплати.

Вебхук відповідає Webhook secret not configured: жодного секрету вебхука не встановлено. Вставте секрет підпису в налаштування.

Вебхук відповідає Invalid signature: секрет підпису належить іншій кінцевій точці або іншому режиму, або годинник сервера неправильний. Підписи Stripe приймаються протягом 5 хвилин від часу сервера. Відповідь також буде Invalid signature, якщо подія робочого платежу підписана тестовим секретом або навпаки: перевірте, що тестовий і робочий секрети не переплутані.

Вебхук відповідає Busy, retry: замовлення в цей момент підтверджував інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Stripe автоматично повторює вебхук. Увімкніть Logging, щоб побачити причину.

URL вебхука показує Method not allowed у браузері: це нормально. URL приймає лише запити від Stripe.

Попередження про те, що значення виглядає неправильно, під час збереження: ключ вставлено в не те поле. Секретні ключі починаються з sk_test_ / rk_test_ або sk_live_ / rk_live_, секрети вебхуків — з whsec_.

Клієнт бачить помилку, обираючи Stripe: увімкніть Logging і перегляньте поле Log на сторінці модуля. Невірний ключ дає повідомлення, що спосіб оплати налаштовано неправильно. Сума замовлення нижча за мінімум Stripe для валюти (наприклад, 0.50 EUR) не може бути сплачена через Stripe.

Тестові платежі не підтверджують робочий платіж: тестові та робочі платежі розділені. Перемкніть Test Mode на потрібний режим і використовуйте ключі та вебхук цього режиму.

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

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

Видалення

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

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