VibeFox Redsys for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Мерчант-аккаунт Redsys: ваш банк (эквайер, который выдал вам виртуальный POS Redsys) предоставляет код мерчанта (FUC), номер терминала и доступ к административной панели Redsys, где показан секретный ключ SHA-256 каждой среды. Ключ тестовой среды отличается от боевого. Онлайн-уведомление (HTTP) должно быть включено для вашего терминала. Если не уверены, уточните у банка.

Валюта магазина: одна из валют, которые поддерживает модуль (см. Configuration), и ваш терминал Redsys должен быть подключён банком к этой валюте. Большинство терминалов принимают только EUR.

Доступный магазин: Redsys должен иметь доступ к вашему магазину из интернета, без логина и блокировки файрволом, чтобы доставлять уведомления о платежах.

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

Установка

1. В панели администрирования перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. После окончания загрузки нажмите Configure или позже найдите VibeFox Redsys Gateway в списке модулей и нажмите Configure.

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

4. Введите код мерчанта, терминал и секретный ключ каждой среды (см. Configuration).

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

При установке модуль создаёт статус заказа Redsys payment on hold. PrestaShop предлагает новый платёжный модуль для стран, которые активны на тот момент, и для всех валют и групп клиентов. Это можно изменить в разделе Payment > Preferences; страны, которые вы включите позже, нужно отметить там для модуля.

Configuration

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Redsys Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если код мерчанта не задан или содержит не только цифры, если секретный ключ не является допустимым ключом Redsys SHA-256, если ключ текущего режима пуст (тогда способ оплаты скрывается на оформлении заказа) и если валюта магазина не поддерживается. Пока включён тестовый режим, страница показывает Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. Если поле Title пустое, страница показывает Enter a title for the payment method., и ничего не сохраняется.

Redsys

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

Title: название способа оплаты, которое видят покупатели на оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Credit/Debit Card (Redsys). Обязательно.

Description: текст под способом оплаты на оформлении заказа. По умолчанию: Pay securely with your credit or debit card via Redsys.

Аккаунт Redsys

Ваш банк предоставляет код мерчанта, терминал и доступ к административной панели Redsys, где показан секретный ключ SHA-256 каждой среды. В разделе есть ссылка на административную панель Redsys.

Merchant Code (FUC): ваш код мерчанта Redsys, до 9 цифр. Всё, что не является цифрой, удаляется при сохранении.

Terminal Number: номер терминала, назначенный вашим банком, до 3 цифр. По умолчанию: 1. Пустое поле сохраняется как 1.

Secret Key (SHA-256) — live: ключ SHA-256 в Base64 боевой (производственной) среды, обычно 32 символа. Используется, когда тестовый режим выключен.

Тестовый режим (SIS-T)

Тестовая среда Redsys имеет собственный секретный ключ. В разделе показаны публичные тестовые данные Redsys: код мерчанта 999008881, терминал 1, ключ sq7HjrUOBfKmC576ILgskD5srU870gJ7, карта 4548 8100 0000 0003, срок действия 12/49, CVV 123. В тестовом режиме реальные деньги не списываются.

Test Mode: платежи и возвраты отправляются в тестовую среду Redsys (SIS-T) и подписываются тестовым ключом. По умолчанию: включено. Выключите, чтобы принимать реальные платежи. Пока режим включён, оформление заказа показывает под способом оплаты TEST MODE: Redsys test environment, no real money is charged.

Secret Key (SHA-256) — test: ключ SHA-256 в Base64 тестовой среды. Используйте свой тестовый ключ или публичный тестовый ключ, указанный выше.

Сохранённые ключи никогда не отображаются повторно. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

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

Страница оплаты и заказы

Commerce Name: название магазина, которое показывается на платёжной странице Redsys, не более 25 символов. По умолчанию: название вашего магазина, обрезанное до 25 символов.

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

Несовпадения суммы или валюты, тестовые платежи, когда магазин работает в боевом режиме, и платежи по отменённым попыткам всегда попадают в Redsys payment on hold.

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

Notification URL: Redsys сообщает о каждом платеже на этот адрес вашего магазина. Он показан в этом разделе и выглядит как https://your-shop/module/wcp_redsys_gateway/notify при включённых ЧПУ-адресах. Модуль передаёт его в Redsys с каждым платежом, поэтому ничего копировать в панель Redsys не нужно. Онлайн-уведомление (HTTP) должно быть включено для вашего терминала. Если после успешной оплаты заказ не создаётся, уточните у банка. Уведомления без действительной подписи отклоняются. Без уведомления заказ не создаётся.

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

Debug log: записывает детали платежей, уведомлений и возвратов в logs/rdsg_debug.log.php в папке модуля. Файл нельзя открыть из веба. Ошибки записываются всегда, даже когда эта опция выключена. Ключи, подписи и данные карт никогда не записываются. По умолчанию: выключено.

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

Delete Data: если включено, при удалении модуля удаляются настройки шлюза и журнал. Записи о платежах Redsys по заказам (нужны для возвратов) и статус заказа Redsys payment on hold сохраняются всегда. По умолчанию: выключено.

Поддерживаемые валюты

EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, NOK, SEK, DKK, PLN, CZK, HUF, BGN, RON, ILS, INR, MYR, SGD, THB, SAR, ZAR, RUB, BRL, MXN, ARS, CLP, COP, PEN, CNY, TWD. Способ оплаты скрывается для корзин в других валютах.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Credit/Debit Card (Redsys)) и подтверждает заказ. Покупатель видит Redirecting to Redsys for payment. Please wait... и переходит на платёжную страницу Redsys вашего банка. Если браузер не переходит дальше сам, покупатель нажимает Pay via Redsys или Choose another payment method, чтобы вернуться. На этом этапе заказа ещё не существует.

На странице Redsys покупатель оплачивает картой с 3-D Secure, через Bizum или другой способ, включённый вашим банком для терминала. Страница использует язык корзины (испанский, английский, каталанский, французский, немецкий, итальянский, португальский и другие) или английский для остальных языков. Сумма — это итог корзины в минимальных единицах валюты корзины, например EUR 43,45 передаётся как 4345, а JPY или CLP — без десятичных знаков. Платёж описывается как Cart с номером корзины и названием вашего магазина.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Redsys подписанным уведомлением: именно уведомление создаёт заказ, и покупатель видит стандартную страницу подтверждения заказа с Your payment with Redsys has been received. Если заказ переведён в Redsys payment on hold, страница показывает Your payment with Redsys has been received and is being reviewed by the store. Если уведомление ещё не пришло, страница Payment confirmation показывает Redsys is confirming your payment. If you completed the payment, your order will be created in a few moments — please do not pay again. с кнопками Check again и Back to checkout.

Если покупатель отменяет платёж или платёж отклонён, Redsys возвращает покупателя на оформление заказа с сообщением The Redsys payment was not completed. You can try again or choose another payment method. Корзина сохраняется, и покупатель может оплатить снова. Каждая новая попытка получает новый номер заказа Redsys, а платёж, сделанный из любой из них, например из второй вкладки браузера, всё равно распознаётся.

Если платёж не удаётся отправить в Redsys, покупатель остаётся на оформлении заказа с коротким сообщением: Redsys payments are not configured correctly. Please choose another payment method or contact us., сообщением о том, что валюта не принимается, или The order total must be greater than zero.

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

Модуль принимает разовые платежи, которые авторизуются и сразу списываются на странице Redsys. Нет формы карты на вашем сайте (InSite или iframe), нет сохранённых карт, оплаты в один клик или токенизации, нет подписок и повторяющихся платежей, нет предавторизации с последующим списанием и нет платёжных ссылок для заказов, созданных в панели администрирования.

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

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

No order yet: покупатель был отправлен в Redsys и не оплатил, платёж был отклонён или отменён, либо уведомление Redsys ещё не пришло. Существует только корзина.

Payment accepted, Delivered or Redsys payment on hold: платёж подтверждён. Статус следует за Order Status After Payment. Платёж записывается с номером заказа Redsys (Ds_Order) как ID транзакции, а примечание показывает номер заказа Redsys, код авторизации и код ответа, с пометкой [TEST] для тестовых платежей.

Redsys payment on hold after payment: Redsys сообщил сумму или валюту, отличающиеся от итога корзины (например, корзину изменили в другой вкладке после начала оплаты), пришёл тестовый платёж, пока магазин работает в боевом режиме (реальные деньги не списаны, платёж не записывается), или покупатель оплатил после отмены этого платежа на странице Redsys. Примечание объясняет причину. Проверьте платёж в административной панели Redsys, затем обработайте заказ или сделайте возврат платежа.

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

Отклонённый платёж никогда не меняет существующий заказ. Для частых кодов ответа журнал и примечания дают краткую причину, например Insufficient funds, Card expired или Cancelled by the customer. Если для корзины, у которой уже есть заказ, приходит второй, другой платёж, заказ не меняется. Примечание просит вас вернуть дублирующий платёж в административной панели Redsys. Если Redsys сообщает, что платёж ещё выполняется, добавляется примечание, и заказ ждёт окончательного результата.

Блок оплаты Redsys

На странице заказа показан блок Redsys payment с номером заказа Redsys (Ds_Order), кодом и ответом авторизации, средой (боевая или тестовая), оплаченной и возвращённой суммой, значком Test mode для тестовых платежей, подсказкой о проверке для заказов на удержании, историей возвратов, Redsys notes заказа и всеми номерами заказов Redsys, выданными для корзины.

Возвраты

В блоке Redsys payment введите сумму (невозвращённая сумма подставляется автоматически), при необходимости причину, и нажмите Refund via Redsys. Подтвердите вопрос Refund this amount through Redsys? This cannot be undone. Поддерживаются полные и частичные возвраты. Вам нужно право редактировать заказы; доступ к страницам модулей не требуется. Возвраты выполняются в сумме и валюте, которые Redsys списал, поэтому после несовпадения суммы или валюты можно вернуть не больше того, что покупатель фактически заплатил, а не итог заказа. Возврат отправляется через REST API Redsys в ту среду, в которой был сделан платёж (тестовую или боевую), подписывается ключом этой среды, и подпись ответа проверяется. Если Redsys не принимает возврат, блок показывает ошибку, и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания с номером заказа Redsys и причиной. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет.

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Redsys.

Возвраты, сделанные в административной панели Redsys, не записываются как возвраты модуля. Когда Redsys присылает уведомление о них, к заказу добавляется примечание. Статус заказа автоматически не меняется.

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

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

Без действующего ключа Redsys не показывается покупателям на оформлении заказа. Если всё же начат платёж, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в панель администратора, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать на оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи продолжают подтверждаться, а возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется, пока вы работаете в панели администратора: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

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

Redsys не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, код мерчанта и терминал заполнены, а у текущего режима есть действительный ключ: Secret Key (SHA-256) — test в тестовом режиме, Secret Key (SHA-256) — live в боевом. Проверьте, что валюта корзины есть в списке поддерживаемых валют. Страница настроек показывает предупреждение для каждой из этих проблем. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: уведомление Redsys не дошло до вашего магазина. Попросите банк проверить, что онлайн-уведомление (HTTP) включено для вашего терминала. Проверьте, что адрес из Notification URL доступен из интернета без логина и блокировки файрволом. Включите Debug log и посмотрите поле Log на странице модуля.

Уведомление отвечает Forbidden: подпись не совпала с секретным ключом среды, в которой был начат платёж, либо код мерчанта в уведомлении не ваш. Проверьте, что секретные ключи и код мерчанта в настройках соответствуют вашему терминалу.

Уведомление отвечает Order not found: уведомление подписано правильно, но ни одна корзина этого магазина не использует этот номер заказа Redsys.

Уведомление отвечает Busy: корзину в тот же момент обрабатывало другое уведомление, либо заказ не удалось создать (например, модуль отключён). Redsys повторит уведомление. Причину показывает журнал.

Уведомление отвечает Bad request: в запросе не было параметров Redsys или они были повреждены. Запрос не пришёл от Redsys в ожидаемом формате.

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

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

Возврат не проходит: прочитайте ошибку. Redsys refund: the merchant code or the TEST secret key is not configured. (или LIVE) означает, что отсутствует ключ среды платежа. Коды ошибок Redsys объясняются в сообщении, например SIS0057 (сумма превышает остаток платежа), SIS0056 (исходный платёж не найден: другая среда или терминал), SIS0042 (ошибка подписи, проверьте ключ этой среды), SIS0026 (неизвестный код мерчанта или терминала) и SIS0027 (валюта не настроена для терминала). Если Redsys недоступен, возврат не выполняется. Попробуйте позже.

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

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Redsys Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data включено, настройки шлюза и журнал удаляются. Если выключено, все настройки сохраняются для последующей переустановки. Записи о платежах и возвратах Redsys и статус заказа Redsys payment on hold сохраняются всегда, поэтому заказы, оплаченные раньше, можно вернуть и после переустановки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

Redsys — товарный знак его владельца. Модуль не связан с Redsys и не одобрен Redsys.