VibeFox Stripe for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Учётная запись Stripe: вам нужны секретные API-ключи вашей учётной записи Stripe и endpoint для вебхука в 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_...) endpoint вебхука, созданного в тестовом режиме.

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

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

Сохранённые ключи и секреты больше никогда не показываются. Поле остаётся пустым и показывает Сохранено — оставьте пустым, чтобы не менять. Вводите новое значение, только если хотите его изменить.

Clear saved secrets: отметьте ключ или секрет и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Webhook

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

Выберите для каждого endpoint эти события (они также перечислены в этом разделе):

После создания каждого endpoint скопируйте его секрет подписи (whsec_...) из Stripe и вставьте его в Test Webhook Secret или Live Webhook Secret. Вебхуки без действительной подписи отклоняются. Событие должно быть подписано секретом того режима, в котором произведён платёж, поэтому тестовый секрет никогда не подтверждает рабочий платёж. Без вебхука заказ создаётся только тогда, когда покупатель возвращается в магазин после оплаты.

Заказы

Order Status After Payment: статус заказа, который устанавливается после успешной оплаты.

Отложенные платежи ждут в статусе 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. Вы получите письмо, как только платёж будет подтверждён. Если отложенный платёж позже не проходит, страница показывает Ваш платёж через 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 проверьте, что endpoint существует в том режиме, который вы используете (тестовом или рабочем), что его URL точно совпадает с показанным в Endpoint URL и что выбраны все четыре события. Проверьте, что секрет подписи этого endpoint находится в нужном поле (Test Webhook Secret или Live Webhook Secret). Stripe Dashboard показывает ответ вашего магазина на каждый вебхук. Заказ также создаётся, когда покупатель возвращается в магазин после оплаты.

Вебхук отвечает Webhook secret not configured: секрет вебхука не задан ни для одного режима. Вставьте секрет подписи в настройки.

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

Вебхук отвечает Busy, retry: заказ в этот момент подтверждал другой запрос, либо заказ не удалось создать (например, модуль отключён). Stripe автоматически повторяет вебхук. Включите Logging, чтобы увидеть причину.

URL вебхука показывает Method not allowed в браузере: это нормально. URL принимает только запросы от Stripe.

Предупреждение «The value does not look right» при сохранении: ключ вставлен не в то поле. Секретные ключи начинаются с 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 и не одобрен им.