VibeFox Stripe for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

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

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

Установка

Файл для загрузки — один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_stripe_gateway-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_stripe_gateway.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ один и тот же для обеих версий.

OpenCart 3

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

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Stripe Gateway и нажмите Install (зелёная кнопка +). Вашему пользователю админки нужно право на изменение списка платёжных расширений.

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

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

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

OpenCart 4

1. В админке перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_stripe_gateway.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Stripe Gateway, нажмите Install (зелёная кнопка +), а затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ, ключи Stripe и вебхук так же, как в шагах с 3 по 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL вебхука (см. Вебхук).

Новая установка стартует с выключенным способом оплаты и включённым тестовым режимом.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если для текущего режима не задан секретный ключ (тогда способ оплаты скрыт на оформлении заказа) или секрет подписи вебхука (тогда заказы подтверждаются только когда покупатель возвращается в магазин после оплаты), и показывает Тестовый режим включён: реальные платежи не принимаются., пока включён тестовый режим. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении Title должен содержать от 1 до 128 символов, Sort Order должен быть целым числом, а Total должен быть числом не меньше 0. Если ключ или секрет не начинается с ожидаемого префикса, настройки сохраняются, а над настройками выводится предупреждение с указанием поля.

Stripe Checkout

Enable/Disable: Enable Stripe Gateway включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель на оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Stripe. Обязательное поле.

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely with your credit or debit card via Stripe.

Sort Order: позиция Stripe среди способов оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Stripe только для адресов оплаты в выбранной географической зоне. По умолчанию: All zones. Географические зоны настраиваются в System > Localisation > Geo Zones.

Total: сумма заказа на оформлении в валюте по умолчанию магазина, которую заказ должен достичь, чтобы Stripe предлагался. Оставьте поле пустым, чтобы предлагать Stripe при любой сумме.

Ключи API

Скопируйте секретные ключи из Stripe Dashboard > Developers > API keys (на странице есть ссылка). Тестовые и рабочие ключи разделены. Тестовый режим использует только тестовые ключи, рабочий режим — только рабочие.

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

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 the saved value on save под полем и нажмите Save.

Вебхук

Вебхук сообщает вашему магазину, что платёж выполнен. В Stripe Dashboard > Developers > Webhooks добавьте endpoint в тестовом режиме и ещё один в рабочем режиме. Используйте URL, который показан в поле Endpoint URL в этом разделе. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_stripe_gateway/webhook, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_stripe_gateway/payment/wcp_stripe_gateway.webhook. Он формируется из адреса витрины вашей установки OpenCart. Копируйте URL точно так, как он показан в настройках.

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

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

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (незавершённый заказ). Заказ получает статус только после того, как Stripe подтвердит платёж. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Order Status After Payment: статус, который устанавливается после успешного платежа. По умолчанию: Processing.

Awaiting Payment Status: отложенный платёж: оформление заказа завершено, но Stripe ещё не подтвердил деньги. По умолчанию: Pending.

On Hold (Review) Status: платёж требует вашей проверки (см. Статусы заказов). По умолчанию: Pending, так как в OpenCart нет статуса On hold. Свой статус можно создать в System > Localisation > Order Statuses и выбрать его здесь.

Failed Payment Status: отложенный платёж не прошёл. По умолчанию: Failed.

Refunded Status: платёж полностью возвращён со страницы заказа. По умолчанию: Refunded.

Дополнительно

Logging: записывает запросы и вебхуки Stripe в strg_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть из браузера; при размере 5 МБ он переименовывается в strg_debug.old.log.php. Ключи и данные покупателей не записываются. По умолчанию: выключено. Пока выключено, ничего не записывается, в том числе ошибки.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete Data on Uninstall: если включено, при удалении расширения удаляются настройки шлюза и журнал. Транзакции и возвраты Stripe всегда сохраняются, поэтому старые заказы остаются доступными для возврата. По умолчанию: выключено.

Импорт / Экспорт

Экспорт: Download JSON сохраняет настройки в файл JSON. Секретные ключи не экспортируются.

Импорт: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые секретные ключи остаются.

Оформление заказа

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Stripe). На шаге Confirm Order покупатель видит ваше описание и примечание Вы будете перенаправлены на Stripe для безопасного завершения платежа. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт сессию Stripe Checkout на сумму заказа в валюте заказа и отправляет покупателя на страницу оплаты Stripe. Там покупатель платит кредитной или дебетовой картой. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. E-mail покупателя передаётся в Stripe, а на странице Stripe платёж отображается как Order # с номером заказа.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Stripe: по подписанному вебхуку или по серверному запросу к Stripe, когда покупатель возвращается. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Для отложенного платежа страница также показывает Ваш платёж подтверждается Stripe. Вы получите e-mail, как только он будет подтверждён. Если Stripe ещё не подтвердил платёж, когда покупатель возвращается, появляется страница Подтверждение платежа с тем же текстом и кнопкой Check again; вебхук установит статус заказа, как только придёт.

Если покупатель отменяет оплату на странице Stripe, сессия Stripe закрывается, и покупатель возвращается к оформлению заказа с сообщением Платёж отменён. Вы можете попробовать снова или выбрать другой способ оплаты. Если платёж не был завершён или отложенный платёж не прошёл, появляется сообщение Платёж не завершён. Вы можете попробовать снова или выбрать другой способ оплаты. Корзина сохраняется. В OpenCart 4 эти сообщения показываются над страницей оформления заказа. Каждая новая попытка (OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, OpenCart 4 обновляет заказ в процессе оформления) закрывает предыдущие открытые сессии Stripe этой корзины, поэтому её нельзя оплатить дважды. Если предыдущая сессия оказывается уже оплаченной, подтверждается этот платёж, а не запускается новый. Если другой заказ из той же корзины уже оплачен через Stripe, новый платёж не запускается, и покупатель видит страницу успешного оформления заказа. Изменение корзины, в том числе нового количества, считается новой корзиной, которой нужна собственная оплата.

OpenCart 4 хранит заказ на этапе оформления до показа страницы успешного оформления. Если этот заказ за это время закрылся без оплаты (например, отложенный платёж не прошёл или вы его отменили), покупатель возвращается к оформлению заказа с сообщением о том, что платёж не завершён, и следующее нажатие Confirm Order оплачивает новый заказ. Оплаченный заказ никогда не показывается как оплаченный для другой корзины.

Если Stripe не может запустить платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например Сумма заказа меньше минимальной суммы, которую Stripe может списать в этой валюте. Выберите другой способ оплаты. Техническая причина записывается в журнал.

Вебхук работает и тогда, когда магазин находится в режиме обслуживания, потому что OpenCart пропускает запросы платёжных расширений.

Расширение принимает только платежи картами, которые списываются сразу на странице Stripe. Нет сохранённых карт, подписок или регулярных платежей, нет формы карты на вашем сайте, нет кнопок Apple Pay или Google Pay на вашем сайте, и авторизация с последующим списанием не разделяются.

Заказы и возвраты

Статусы заказов

Без статуса (незавершённый заказ): покупателя отправили на Stripe, и он ещё не оплатил, или Stripe ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в Missing Orders.

Order Status After Payment (по умолчанию Processing): платёж подтверждён. Примечание показывает платёж Stripe (pi_...), сессию и способ подтверждения (вебхук или возврат покупателя).

Awaiting Payment Status (по умолчанию Pending): покупатель завершил оформление с отложенным способом оплаты. Когда Stripe подтверждает платёж, заказ переходит в Order Status After Payment; когда платёж не проходит, он переходит в Failed Payment Status. OpenCart уведомляет покупателя об этих изменениях.

On Hold (Review) Status (по умолчанию Pending): Stripe сообщил о сумме или валюте, отличных от суммы заказа, либо платёж пришёл после того, как заказ был отменён или изменил статус. Примечание объясняет это. Проверьте заказ и выполните его или верните платёж.

Refunded Status (по умолчанию Refunded): платёж полностью возвращён через расширение.

Если для заказа, который уже оплачен, приходит второй платёж, заказ не меняется. Примечание просит проверить его и вернуть дубликат в Stripe Dashboard. То же относится к случаю, когда платёж относится к другому заказу уже оплаченной корзины: тот заказ остаётся без статуса, а примечание добавляется к оплаченному заказу.

Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox Stripe Gateway

В Sales > Orders откройте заказ, оплаченный через Stripe. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Stripe Gateway показывает ID платежа Stripe (со ссылкой на платёж в Stripe Dashboard) с меткой Test mode для тестовых платежей, Checkout Session, Status платежа, суммы Paid / refunded, форму возврата, историю возвратов и Stripe notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

На вкладке VibeFox Stripe Gateway введите Amount (подставляется сумма, которая ещё не возвращена), при желании Reason (optional), и нажмите Refund via Stripe. Подтвердите вопрос Вернуть эту сумму через Stripe? Это действие нельзя отменить. Поддерживаются полные и частичные возвраты. Нужно право на изменение расширения (задаётся в System > Users > User Groups). Возвраты выполняются в сумме и валюте, которые списал Stripe, а не в сумме заказа. Возврат отправляется в том режиме, в котором был выполнен платёж (тестовом или рабочем), поэтому секретный ключ этого режима должен быть задан. Если Stripe не принимает возврат, вкладка показывает ошибку, и возврат не записывается. Успешный возврат добавляется в историю и примечания с ID возврата Stripe. Полный возврат переводит заказ в Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Частичный возврат статус не меняет. Возвраты доступны после того, как Stripe подтвердил платёж.

Возвраты товаров в Sales > Returns не возвращают деньги через Stripe.

Возвраты, сделанные в Stripe Dashboard, приходят через вебхук charge.refunded и добавляются в примечания с общей суммой возвратов в Stripe. Статус заказа автоматически не меняется. При необходимости обновите его вручную.

Лицензионный ключ

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

Если ключ не принят, блок указывает причину, например Ключ не найден, Этот ключ относится к другому продукту, Достигнут лимит доменов или Лицензия истекла с датой. После смены адреса магазина или после освобождения места для домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает место для домена. Освободите его в аккаунте на vibefox.net.

Без активного ключа Stripe не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит Этот способ оплаты недоступен. Выберите другой. Администратор, вошедший в админку в том же браузере, по-прежнему видит способ оплаты в магазине, помеченный (unlicensed — visible to admins only), так что вы можете настроить и протестировать расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит, что администратор вошёл в админку, поэтому без активного ключа способ оплаты скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard админки появится напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи подтверждаются, возвраты работают.

Когда лицензия истекает, расширение продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется снова при открытии Dashboard или страницы Edit в админке: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Задание cron не нужно. При удалении расширения всегда удаляются лицензионный ключ и статус лицензии.

Устранение неполадок

Stripe не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и в текущем режиме задан секретный ключ: Test Secret Key в тестовом режиме, Live Secret Key в рабочем. На странице настроек появляется предупреждение, когда ключ отсутствует. Также проверьте, что адрес оплаты входит в выбранную Geo Zone и что заказ достигает Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: вебхук не работает. В Stripe Dashboard проверьте, что endpoint существует в используемом режиме (тестовом или рабочем), что его URL точно совпадает с 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_.

Покупатель видит ошибку после Confirm Order: включите Logging и посмотрите поле Log на странице расширения. Сообщение Этот способ оплаты недоступен. Перезагрузите страницу оформления заказа. означает, что сессия оплаты уже не соответствует заказу или способ оплаты в это время выключили: покупатель перезагружает оформление заказа. Неверный ключ даёт сообщение о том, что способ оплаты настроен неправильно. Сумма заказа ниже минимума Stripe для валюты (например, 0,50 EUR) не может быть оплачена через Stripe.

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

Заказ в статусе проверки после оплаты: прочитайте примечания на вкладке VibeFox Stripe Gateway (см. Статусы заказов), затем выполните заказ или верните платёж.

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

Возврат завершается ошибкой с сообщением о режиме: платёж был сделан в тестовом или рабочем режиме, а секретный ключ этого режима не задан. Введите его и попробуйте снова.

Для разработчиков: перед созданием сессии Stripe расширение вызывает событие OpenCart strg_checkout_session_params с параметрами сессии и заказом.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Stripe Gateway. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов в разделе Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения тоже удаляется (в OpenCart 4 также его события и стартовое действие, которое пропускает вебхук в режиме обслуживания). Если включён Delete Data on Uninstall, удаляются остальные настройки шлюза (название, описание, тестовый режим, ключи, секреты вебхуков, логирование) и журнал. Если выключен, они сохраняются для будущей повторной установки. Транзакции и возвраты Stripe всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

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

Stripe — товарный знак его владельца. Это расширение не связано с Stripe и не одобрено Stripe.