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). Ключи песочницы выдаются в отдельном аккаунте песочницы 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. Введите ключи песочницы и рабочие ключи (см. раздел «Настройка»). В панели Tpay ничего не нужно задавать, кроме кода безопасности: адрес для уведомлений передаётся с каждой транзакцией.

6. Включите Enable/Disable, проверьте платёж в режиме песочницы, а затем снимите отметку Sandbox mode, чтобы принимать настоящие платежи.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Tpay. Над полями страница показывает Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged., пока включён режим песочницы. Она предупреждает, если ключи текущего режима заполнены не полностью (тогда 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). Режим песочницы использует ключи песочницы и 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.

Ключи песочницы

Песочница — это отдельный тестовый аккаунт Tpay со своими ключами (см. документацию API Tpay). Они используются только при включённом Sandbox mode.

Sandbox Merchant ID: Merchant ID аккаунта песочницы.

Sandbox Client ID: Open API Client ID аккаунта песочницы.

Sandbox Client secret: Open API Client secret аккаунта песочницы.

Sandbox Security code: код безопасности уведомлений аккаунта песочницы.

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

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

JWS signature: 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 переносятся автоматически: ключи, которые использовались при включённом тестовом режиме, становятся ключами песочницы.

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

Покупатель выбирает способ оплаты (по умолчанию Tpay) и оформляет заказ. В режиме песочницы при оформлении заказа показывается 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. Чарджбэк, о котором сообщил Tpay, добавляет примечание.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Tpay (на кнопке отображается ваш Title). Полные и частичные возвраты поддерживаются для заказов с платежом, полученным через Tpay; для неоплаченных заказов кнопка не отображается. Возврат отправляется в ту среду (песочницу или рабочую), где был оплачен заказ, поэтому должны быть заданы ключи этой среды. Возврат считается выполненным только после подтверждения 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 (песочница или рабочая среда), к которому относится платёж.

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.