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

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

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

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

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

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

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

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

Payment notifications

Notification URL: Tpay подтверждает платежи на адрес, указанный здесь. При использовании ЧПУ он выглядит так: 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 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-...) в качестве ID транзакции. Примечание показывает, подтверждён ли платёж уведомлением или проверкой статуса, среду и переплату, если она есть.

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

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

Если Tpay сообщает о другом платеже по заказу, который уже оплачен или возвращён, заказ не меняется; примечание просит вас при необходимости вернуть лишний платёж в панели Tpay. Опротестование платежа (chargeback), о котором сообщает Tpay, добавляет примечание.

Блок оплаты Tpay

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

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 сохраняются всегда, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

Tpay — товарный знак его владельца. Этот модуль не связан с Tpay и не одобрен компанией Tpay.