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 (см. Уведомления о платежах).

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

Настройка

Все настройки находятся на странице расширения: 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, проверяет, что он создан для этого заказа, и сравнивает его статус, сумму (в центах) и валюту с заказом. Это происходит как при вызове callback URL со стороны Satispay, так и при возврате покупателя, в зависимости от того, что случится раньше. Затем заказ получает статус стандартным способом 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.