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 з увімкненими дружніми URL. Модуль передає її 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 не знає, що ви увійшли в back office, тому спосіб оплати приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете протестувати його на оформленні замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не зачіпаються: платежі, які вже розпочато, як і раніше підтверджуються, а повернення працюють.

Коли ліцензія закінчується, модуль продовжує працювати, але оновлення та підтримка потребують продовження. Статус перевіряється автоматично, поки ви працюєте в back office: раз на день протягом перших 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.