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, которую запрашивают у 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 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. Платежи в песочнице не списываются. По умолчанию: off. Песочница и боевая среда имеют отдельные ключи: подключайте каждую среду кодом активации этой среды. Пока используется песочница, покупатели видят под способом оплаты Sandbox mode: no real money is charged.

Activation Code: чтобы подключить выбранную выше среду, вставьте новый 6-значный код активации и нажмите Save. Боевые коды создаются в Satispay Business Dashboard, раздел Online shop. Коды для песочницы выдаются вместе с тестовой учётной записью Satispay. Код используется один раз и не сохраняется. Оставьте поле пустым, чтобы сохранить текущее подключение.

При сохранении с кодом модуль создаёт пару ключей RSA, отправляет открытый ключ и код в Satispay и сохраняет Key ID и ключи этой среды в настройках магазина. Закрытые ключи никогда не показываются. При успехе страница показывает, например, Satispay Live connected. Key ID: и далее ID. Если Satispay отклоняет код, страница показывает Satispay activation failed: с сообщением Satispay и просит проверить, что код относится к этой среде и ещё не использовался. Код с символами, отличными от букв и цифр, отклоняется до отправки чего-либо. Сохранение нового кода для среды заменяет её предыдущее подключение.

Уведомления об оплате

В Satispay ничего настраивать не нужно. Каждый платёж имеет собственный callback URL, который Satispay вызывает при изменении платежа, а модуль перед созданием или изменением заказа заново получает платёж через API Satispay. Поле Callback 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 для платежей в песочнице, историей возвратов, списком Satispay payments of this cart со всеми попытками оплаты и их средой, а также Satispay notes заказа.

Возвраты

В блоке Satispay payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Satispay. Подтвердите вопрос Refund this amount through Satispay? This cannot be undone. Поддерживаются полный и частичный возвраты. Нужно право редактировать заказы; доступ к страницам Modules не требуется. Возвраты ограничены суммой, которую Satispay списал за платёж, поэтому после расхождения суммы можно вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Возврат отправляется в среду, в которой прошёл платёж (боевую или песочницу), поэтому эта среда должна оставаться подключённой. Возврат считается выполненным только тогда, когда его принимает 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 (боевой код для боевой среды, код песочницы для песочницы), создайте новый код и сохраните снова. Если страница сообщает, что не удалось создать пару ключей RSA, попросите хостинг включить расширение PHP OpenSSL. Если Satispay недоступен, проверьте, что сервер может открывать исходящие HTTPS-соединения.

Satispay пропал при оформлении заказа после перехода из песочницы в боевой режим: песочница и боевая среда используют разные ключи. Вставьте боевой код активации при выключенном Sandbox Mode и сохраните.

Покупатель видит This payment method is not available.: способ оплаты не разрешён для корзины (страна, валюта или группа покупателей в Payment > Preferences), отключён или используемая среда не подключена.

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

Возврат не проходит, потому что среда больше не подключена: платёж был сделан в боевой среде или в песочнице, а у этой среды сейчас нет ключей. Подключите её снова кодом активации или сделайте возврат через 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.