VibeFox Tpay for PrestaShop — Допомога

Вимоги

PrestaShop: від 8.0 до 9.x.

PHP: 8.0 або новіша. Модуль відмовляється встановлюватися на старіших версіях PHP. Для перевірки підпису JWS сповіщень потрібні розширення OpenSSL і вихідний HTTPS-доступ до secure.tpay.com.

Валюта магазину: лише польський злотий (PLN). Tpay проводить розрахунки в PLN, а в Open API Tpay немає поля валюти, тому спосіб оплати приховується, якщо в кошику інша валюта.

Доступ до вашого магазину з інтернету: Tpay надсилає сповіщення про оплату до вашого магазину, тож адреса сповіщень має бути доступна з інтернету (її не повинні блокувати брандмауер чи HTTP-автентифікація).

Обліковий запис Tpay: вам потрібні такі значення з панелі мерчанта Tpay: Merchant ID (ідентифікатор вашого облікового запису Tpay), ключі Open API Client ID і Client secret (Integration, API) та код безпеки (Settings, Notifications). Ключі sandbox беруться з окремого облікового запису sandbox Tpay.

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

Встановлення

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

2. Після завершення завантаження натисніть Configure або згодом знайдіть VibeFox Tpay Payment у списку модулів і натисніть Configure.

3. Введіть ліцензійний ключ VibeFox у поле License key у блоці ліцензії вгорі сторінки Configure та натисніть Activate (див. розділ «Ліцензійний ключ»).

4. Введіть ключі Sandbox і ключі Production (див. Configuration). На панелі Tpay нічого налаштовувати не потрібно, окрім коду безпеки: адреса сповіщень надсилається з кожною транзакцією.

5. Увімкніть Enable/Disable і натисніть Save. Протестуйте платіж у режимі sandbox, а потім вимкніть Sandbox mode, щоб приймати справжні платежі.

Під час встановлення модуль створює статус замовлення Tpay payment on hold. PrestaShop пропонує новий платіжний модуль для всіх валют, країн і груп клієнтів. Їх можна обмежити в Payment > Preferences; для модуля має залишитися дозволеною валюта PLN.

Configuration

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Tpay Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged., поки ввімкнено режим sandbox. Вона попереджає, якщо ключі поточного режиму заповнені не повністю (тоді Tpay не відображається на етапі оформлення замовлення), якщо валюта магазину за замовчуванням не PLN і якщо бракує розширення OpenSSL для PHP за ввімкненої перевірки JWS (платежі тоді не підтверджуватимуться). Пробіли, вставлені разом із Merchant ID або Client ID, видаляються під час збереження.

Tpay

Enable/Disable: Enable Tpay payments вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачить покупець на етапі оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Tpay. Обов'язкове поле.

Description: опис способу оплати, який бачить покупець на етапі оформлення замовлення. За замовчуванням: Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode: використовує sandbox Tpay (тестові платежі, без реальних грошей) з ключами Sandbox і openapi.sandbox.tpay.com. Вимкніть, щоб приймати справжні платежі з ключами Production. Повернення завжди надсилаються в те середовище, де було оплачено замовлення. За замовчуванням: увімкнено.

Production keys

Де їх знайти: на панелі мерчанта Tpay у розділі Integration, API (ключі Open API: Client ID і Secret); Merchant ID — це ідентифікатор вашого облікового запису Tpay; код безпеки знаходиться в Settings, Notifications.

Merchant ID: ідентифікатор вашого облікового запису Tpay (цифри). Tpay надсилає його в кожному сповіщенні.

Client ID: Open API Client ID.

Client secret: Open API Client secret.

Security code: використовується для перевірки контрольної суми MD5 сповіщень Tpay.

Sandbox keys

Sandbox — це окремий тестовий обліковий запис Tpay зі своїми ключами (див. документацію Tpay API). Вони використовуються лише тоді, коли ввімкнено Sandbox mode.

Sandbox Merchant ID: Merchant ID облікового запису sandbox.

Sandbox Client ID: Open API Client ID облікового запису sandbox.

Sandbox Client secret: Open API Client secret облікового запису sandbox.

Sandbox Security code: код безпеки сповіщень облікового запису sandbox.

Збережені секрети (Client secret і Security code обох середовищ) більше ніколи не відображаються. Поле залишається порожнім і показує Saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved secrets: позначте секрет і натисніть Save, щоб його видалити. Порожнє поле зберігає збережене значення.

Payment notifications

Notification URL: Tpay підтверджує платежі на адресу, яка показана тут. З дружніми URL вона має такий вигляд: https://your-shop/module/wcp_tpay_payment/notify, можливо з кодом мови, наприклад /en/. Адреса надсилається автоматично з кожною транзакцією; на панелі Tpay потрібно налаштувати лише код безпеки. Замовлення створюється лише після сповіщення з дійсними контрольною сумою та підписом і відповідною сумою (або після відповідної перевірки статусу, коли покупець повертається до магазину). Tpay повторює сповіщення, доки ваш магазин його не прийме.

JWS signature: додатково перевіряє X-JWS-Signature сповіщень за сертифікатом Tpay (рекомендовано). Потребує розширення OpenSSL для PHP і вихідного HTTPS-доступу до secure.tpay.com. Сертифікати кешуються на добу. Контрольна сума MD5 перевіряється завжди. За замовчуванням: увімкнено.

Advanced

Debug log: фіксує події оплати: лише технічні події (без ключів і даних покупців) у файлі logs/wc_tp_debug.log.php у папці модуля. Файл не можна відкрити через веб. За замовчуванням: вимкнено. Поки журнал вимкнено, нічого не записується, зокрема помилки, тож увімкніть його до того, як шукати причину проблеми.

Log: показує розмір журналу та його останні записи. Натисніть Clear log, щоб очистити його.

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються його налаштування та журнал. Замовлення та їхні платіжні дані Tpay завжди зберігаються. За замовчуванням: вимкнено.

Оформлення замовлення

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Tpay). У режимі sandbox опція оплати показує Sandbox mode - no real money is charged. Після підтвердження модуль створює транзакцію Tpay на суму кошика в PLN з описом Cart # і номером кошика, передає ім'я, e-mail, адресу для рахунку та телефон покупця і перенаправляє покупця на сторінку оплати Tpay. Сторінка відображається польською, англійською або українською мовою залежно від мови магазину (для інших мов — англійська). Там покупець обирає BLIK, банківський переказ, картку або інший метод, увімкнений у вашому обліковому записі Tpay, і сплачує. На цьому етапі замовлення ще не існує.

Замовлення позначається оплаченим лише після підтвердження Tpay. Tpay надсилає сповіщення до вашого магазину; модуль перевіряє контрольну суму MD5 з кодом безпеки, Merchant ID і (якщо увімкнено) підпис JWS, використовуючи ключі того середовища, в якому розпочато платіж, а потім суму: вона має дорівнювати сумі, запитаній для цієї спроби оплати, і сумі кошика, а оплачена сума не може бути меншою. Сповіщення без дійсної контрольної суми або підпису відхиляються. Далі створюється замовлення, і покупець бачить стандартну сторінку підтвердження замовлення.

Після оплати покупець повертається до вашого магазину. Лише повернення нічого не позначає як оплачене. Якщо сповіщення ще не надійшло, модуль запитує в API Tpay статус транзакції (не частіше ніж раз на 10 секунд) і застосовує ті самі перевірки. Поки платіж не підтверджено, на сторінці Payment confirmation відображається Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: з кнопкою Refresh і кнопкою Pay again, яка повертає до оформлення замовлення. Сповіщення створює замовлення, щойно надходить.

Якщо Tpay повідомляє, що платіж не пройшов, покупець повертається до оформлення замовлення з повідомленням Tpay reports that the payment did not go through. Please try again or choose another payment method. Якщо платіж не проходить на сторінці Tpay, Tpay повертає покупця на сторінку оформлення замовлення. Кошик зберігається в обох випадках. Якщо замовлення перейшло на утримання, сторінка підтвердження показує Your payment is being verified. We will contact you as soon as it is confirmed.

Кожна спроба оплати має власний номер посилання. Коли покупець платить знову, раніше неоплачені транзакції Tpay цього кошика скасовуються в Tpay; платіж, який уже пройшов за попереднім посиланням, однаково приймається. Якщо в кошика вже є замовлення, покупець переходить на сторінку підтвердження цього замовлення замість нової оплати.

Якщо Tpay не може розпочати платіж, покупець залишається на оформленні замовлення з повідомленням The Tpay payment could not be started. Please try again or choose another payment method., а причина записується в журнал (якщо ввімкнено Debug log).

Адреса сповіщень працює навіть тоді, коли магазин у режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

Модуль працює лише в PLN. У магазині немає вибору банку чи коду BLIK (покупець обирає на сторінці Tpay), немає збережених карток, підписок, кнопок Apple Pay або Google Pay у магазині та калькуляторів розстрочки.

Замовлення та повернення коштів

Статуси замовлення

No order yet: покупця перенаправили до Tpay, і він не оплатив, або Tpay ще не підтвердив платіж. Існує лише кошик. Невдалий платіж також не створює замовлення.

Payment accepted: Tpay підтвердив платіж. Платіж записується з назвою транзакції Tpay (TR-...) як ідентифікатор транзакції. Примітка показує, чи платіж підтверджено сповіщенням або перевіркою статусу, середовище і переплату, якщо вона є.

Tpay payment on hold: платіж надійшов, але його сума відрізнялася від запитаної або від суми кошика (наприклад, кошик змінили після початку оплати), оплачено лише частину, або платіж надійшов після того, як замовлення було скасовано. Примітка пояснює це. Перевірте платіж на панелі Tpay, а потім виконайте замовлення або поверніть кошти. Якщо покупець згодом сплатить правильну суму новою спробою, замовлення перейде в статус Payment accepted.

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

Якщо Tpay повідомляє про інший платіж за замовлення, яке вже оплачене або повернене, замовлення не змінюється; примітка просить за потреби повернути зайвий платіж на панелі Tpay. Повідомлений Tpay chargeback додає примітку.

Блок оплати Tpay

На сторінці замовлення відображається блок Tpay payment з назвою та ідентифікатором транзакції Tpay, референсом платежу (CRC), середовищем (з позначкою Sandbox для тестових платежів), статусом платежу та способом його підтвердження, сплаченою сумою, сумою замовлення та сумою повернення, історією повернень, усіма Payment attempts кошика та Payment notes замовлення.

Повернення коштів

У блоці Tpay payment введіть суму (підставляється сума, яку ще не повернуто), за потреби причину, і натисніть Refund via Tpay. Підтвердьте запитання Refund this amount through Tpay? This cannot be undone. Повні та часткові повернення підтримуються для замовлень з платежем, отриманим через Tpay, включно із замовленнями на утриманні. Потрібне право редагувати замовлення; доступ до сторінок Modules не потрібен. Можна повернути суму не більше тієї, яку списала оплачувальна транзакція Tpay, і не більше суми замовлення: після часткової оплати або зміни кошика блок показує Refundable (paid through Tpay). Повернення надсилається в те середовище (sandbox або продакшн), де було оплачено замовлення, тож мають бути заповнені ключі цього середовища. Повернення вважається виконаним лише тоді, коли Tpay його підтвердить; повернення, відхилене або не підтверджене Tpay, відображається як помилка і не фіксується. Успішне повернення додається до історії повернень і приміток разом із причиною, яку ви ввели (причина Tpay не передається). Повернення всієї суми, що підлягає поверненню, переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

Модуль не створює кредитових нотаток (credit slips). Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Tpay. Повернення, зроблені на панелі мерчанта Tpay, автоматично в PrestaShop не додаються.

Ліцензійний ключ

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Tpay Payment — це перший блок на сторінці Modules > Module Manager > VibeFox Tpay Payment > Configure, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен), а також кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розміщено рядок Product: presta-payment-tpay і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові бек-офісу (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення місця для домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: домені основного магазину, також у мультимагазинній конфігурації. Видалення ключа з магазину не звільняє місце для домену. Звільніть його у своєму обліковому записі vibefox.net.

Без активного ключа Tpay не показується покупцям на сторінці оформлення замовлення. Якщо платіж все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви ввійшли в бек-офіс, тож спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але не можна перевірити на оформленні замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, що вже розпочалися, і далі підтверджуються, а повернення працюють.

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

Усунення несправностей

Tpay не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і введено всі чотири ключі поточного режиму (Merchant ID, Client ID, Client secret, Security code). Перевірте, що валюта кошика — PLN і що модуль дозволено для PLN, країни покупця та групи покупця в Payment > Preferences. На сторінці налаштувань відображається попередження про відсутні ключі та про валюту магазину, відмінну від PLN.

Платіж пройшов, але замовлення не створено: Tpay не зміг доставити сповіщення або його відхилили. Увімкніть Debug log і перегляньте поле Log на сторінці модуля. Типові причини: неправильний код безпеки або Merchant ID для середовища платежу, заблокована адреса сповіщень (брандмауер, HTTP-автентифікація) або сервер без OpenSSL чи без вихідного HTTPS для перевірки JWS. Замовлення також створюється, коли покупець після оплати повертається до магазину.

Notification answered FALSE - invalid checksum: Merchant ID або код безпеки в налаштуваннях не збігаються з обліковим записом Tpay (sandbox або продакшн), до якого належить платіж.

Notification answered FALSE - invalid JWS signature: підпис не вдалося перевірити, наприклад через відсутність OpenSSL або неможливість завантажити сертифікат Tpay. Виправте сервер або, за потреби, вимкніть JWS signature; контрольна сума MD5 перевіряється в будь-якому разі.

Notification answered FALSE - busy, retry later or FALSE - order could not be created: кошик у той самий момент обробляв інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Tpay автоматично повторює сповіщення. Увімкніть Debug log, щоб побачити причину.

URL сповіщення показує FALSE - POST only in the browser: це нормально. URL приймає лише сповіщення від Tpay.

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

Покупець побачив The Tpay payment could not be started: ключі поточного режиму неправильні або Tpay відхилив запит. Увімкніть Debug log; журнал покаже помилку Tpay.

Покупець побачив We could not match this payment to an order: посилання для повернення не належало кошику покупця. Якщо з покупця списали кошти, сповіщення все одно створить замовлення; перевірте панель Tpay.

Повернення не проходить: якщо в повідомленні сказано, що ключів немає, введіть ключі того середовища, де було оплачено замовлення. Якщо сказано, що сума занадто велика, можна повернути не більше показаної суми. Якщо Tpay не підтвердив повернення, перевірте транзакцію на панелі мерчанта Tpay, перш ніж повторювати спробу.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Tpay Payment і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Кешовані токени доступу Tpay і сертифікати завжди видаляються. Якщо Delete data on uninstall увімкнено, також видаляються налаштування модуля та журнал. Якщо вимкнено, налаштування зберігаються для майбутнього повторного встановлення. Транзакції та повернення Tpay, а також статус замовлення Tpay payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату та ідентифікатори транзакцій.

Tpay — торгова марка її власника. Цей модуль не пов'язаний із Tpay і не схвалений компанією Tpay.