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

Вимоги

WordPress: 5.8 або новіша версія.

WooCommerce: 7.0 або новіша, встановлений і активний. Без нього плагін не активується.

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

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

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

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна і натисніть Install Now. Також можна завантажити папку wcp_tpay_payment до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Tpay > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки і натисніть Activate.

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

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

Налаштування

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

Загальні

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

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

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

Sandbox mode: Use the Tpay sandbox (test payments, no real money). Режим sandbox використовує ключі Sandbox і тестовий API Tpay. Вимкніть його, щоб приймати справжні платежі з ключами продакшн. Повернення завжди надсилаються в те середовище, де було оплачено замовлення. За замовчуванням: увімкнено.

Ключі продакшн

Де їх знайти: на панелі мерчанта 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

Sandbox — це окремий тестовий обліковий запис Tpay з власними ключами (див. документацію API Tpay). Вони використовуються лише тоді, коли ввімкнено 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.

Сповіщення про платежі

Tpay підтверджує платежі на адресу, яку показано в цьому розділі. Вона має такий вигляд: https://your-site/wc-api/wc_tp_payment/. Адреса надсилається автоматично з кожною транзакцією; на панелі Tpay нічого налаштовувати не потрібно, окрім коду безпеки. Замовлення позначається оплаченим лише після сповіщення з дійсною контрольною сумою та підписом і відповідною сумою. Tpay повторює сповіщення, доки ваш магазин його не прийме.

Підпис JWS: Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended). Потребує розширення PHP OpenSSL та вихідних HTTPS-з'єднань з secure.tpay.com. Контрольна сума MD5 перевіряється завжди. За замовчуванням: увімкнено.

Додатково

Debug log: Log payment events. Лише технічні події (без ключів і даних покупців) у WooCommerce > Status > Logs, джерело wcp_tpay_payment. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. Деактивація нічого не видаляє. Замовлення та їхні платіжні дані Tpay завжди зберігаються. За замовчуванням: вимкнено.

Налаштування версії 1.0 переносяться автоматично: ключі, які використовувалися з увімкненим тестовим режимом, стають ключами Sandbox.

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

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

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

Після оплати покупець повертається на сторінку «Замовлення отримано». Саме повернення не позначає замовлення оплаченим. Якщо сповіщення ще не надійшло, сторінка запитує в API Tpay статус транзакції (не частіше ніж раз на 10 секунд) і застосовує ті самі перевірки. Поки оплату не підтверджено, сторінка показує 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: з посиланням Pay again. Коли Tpay повідомляє про невдалий платіж, сторінка показує Tpay reports that the payment did not go through. You can try again: з тим самим посиланням. Якщо платіж не проходить на сторінці Tpay, Tpay повертає покупця на сторінку Pay for order цього самого замовлення.

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

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

Спосіб оплати працює в класичному оформленні замовлення, у блоці «Оформлення замовлення» та на сторінці Pay for order. Він сумісний з WooCommerce High-Performance Order Storage (HPOS).

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

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

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

Pending payment: транзакцію Tpay створено, але платіж ще не підтверджено. У примітці до замовлення показано транзакцію Tpay та середовище.

Processing: Tpay підтвердив платіж. Це стандартний статус WooCommerce після оплати (замовлення лише з віртуальними товарами для завантаження переходять у статус «Виконано»). У примітці вказано, чи підтверджено платіж сповіщенням або перевіркою статусу, і показано переплату, якщо вона є. Ідентифікатор транзакції — це назва транзакції Tpay (TR-...).

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

Failed: Tpay повідомив, що платіж не пройшов. У статус «Невдалий» переводиться лише замовлення, що очікує оплати. Покупець може оплатити знову.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму і натисніть Refund via Tpay (на кнопці відображається ваш Title). Повні та часткові повернення підтримуються для замовлень із платежем, отриманим через Tpay; для неоплачених замовлень кнопка не показується. Повернення надсилається в те середовище (sandbox або продакшн), де було оплачено замовлення, тому мають бути налаштовані ключі саме цього середовища. Повернення вважається виконаним лише після підтвердження Tpay; повернення, яке Tpay відхилив або не підтвердив, показується як помилка і не фіксується в WooCommerce. Успішне повернення додається до приміток замовлення разом із причиною, яку ви вказали (причина до Tpay не надсилається).

Повернення, зроблені на панелі мерчанта Tpay, автоматично до WooCommerce не додаються.

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташовано вгорі сторінки WooCommerce > Settings > Payments > Tpay. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, та ваш домен. Натисніть Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис на vibefox.net.

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

Без активного ключа Tpay не показується покупцям під час оформлення замовлення. Якщо оплату все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Адміністратори магазину, які ввійшли в систему, і далі бачать спосіб оплати з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати й перевірити плагін до купівлі ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються: вже розпочаті платежі й далі підтверджуються, повернення працюють.

Коли ліцензія спливає, плагін продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову у фоновому режимі.

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

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

Платіж пройшов, але замовлення залишається в статусі Pending payment: Tpay не зміг доставити сповіщення або його відхилено. Увімкніть Debug log і перегляньте WooCommerce > Status > Logs, джерело wcp_tpay_payment. Типові причини: неправильний код безпеки або 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 і далі перевіряється.

Замовлення має статус On hold: прочитайте примітку до замовлення. Сплачена сума не збіглася із замовленням, або платіж надійшов за скасоване замовлення. Перевірте платіж на панелі Tpay і завершіть або поверніть кошти за замовлення.

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

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть місце у своєму обліковому записі на vibefox.net і натисніть Check now. Якщо адресу сайту змінено, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати з останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб його видалити, деактивуйте його та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються, так само як кешовані токени доступу Tpay і сертифікати. Налаштування шлюзу та журнали видаляються лише тоді, коли було увімкнено Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Наявні замовлення зберігають свої примітки про оплату, дані транзакцій Tpay і ідентифікатори транзакцій.

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