VibeFox TrustPay for WooCommerce — Помощь

Требования

WordPress: 6.0 или новее.

WooCommerce: 7.0 или новее, установлен и активен. Без него плагин не активируется.

PHP: 8.0 или новее.

Учётная запись finby (TrustPay): нужен проект в finby Merchant Portal с его ID проекта и секретным ключом. Для тестовых платежей нужен отдельный тестовый проект (playground) со своими ID проекта и секретным ключом. Никакие другие ключи не нужны: секретный ключ используется и для доступа к API, и для проверки подписи уведомлений о платежах.

Доступный адрес для уведомлений: finby должен иметь возможность обратиться к вашему сайту из интернета. Файервол, режим обслуживания или защита сайта паролем блокируют уведомления о платежах.

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

Установка

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

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > TrustPay / finby или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блок лицензии вверху страницы и нажмите Activate.

5. Введите ID проекта и секретный ключ рабочего проекта, а для тестов — тестового проекта (см. раздел Configuration).

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

При обновлении с версии 1.0 ваши ID проекта и секретный ключ сохраняются как рабочие учётные данные, а тестовый режим отключается. Проверьте настройки после обновления.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > TrustPay / finby. Над полями страница предупреждает, если шлюз включён, но ID проекта или секретный ключ текущего режима пусты, а также если валюта магазина не поддерживается. В обоих случаях способ оплаты скрывается при оформлении заказа. В списке способов оплаты шлюз помечен как требующий настройки, пока у текущего режима нет ID проекта и секретного ключа.

General

Enable / Disable: Enable TrustPay / finby card payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель при оформлении заказа. По умолчанию: Card payment (TrustPay).

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely by card on the TrustPay / finby payment page.

API credentials

Скопируйте ID проекта и секретный ключ вашего проекта из finby (TrustPay) Merchant Portal. В разделе есть ссылка на Merchant Portal. Тестовые платежи используют отдельный тестовый проект (playground) со своими ID проекта и секретным ключом. Реальные деньги там не списываются.

Test mode: Use the test project (no real payments). Новые платежи и возвраты используют тестовые учётные данные. Возвраты по заказу всегда выполняются в тот проект, через который был оплачен заказ. По умолчанию: включено.

Live Project ID: числовой ID вашего рабочего проекта.

Live Secret key: секретный ключ рабочего проекта. Он используется для получения токенов доступа к API и проверки уведомлений о платежах.

Test Project ID: числовой ID вашего тестового проекта (playground).

Test Secret key: секретный ключ тестового проекта.

ID проекта должен содержать только цифры. Если вы сохраните другое значение, страница покажет ошибку, а прежнее значение сохранится. Секретные ключи сохраняются ровно так, как введены; удаляются только пробелы в начале и в конце.

Payment notifications

Заказ отмечается оплаченным только после того, как finby подтвердит платёж подписанным уведомлением. Плагин автоматически передаёт URL для уведомлений при каждом платеже, поэтому настраивать его не нужно. В разделе показан URL, например https://your-site/wc-api/trustpay_payment_callback/. Вы также можете указать его как URL уведомлений ваших проектов в Merchant Portal. Уведомления без корректной подписи отклоняются.

Плагин сам не запрашивает у finby статус платежа. Если уведомление не доходит до вашего сайта, заказ остаётся в статусе Pending payment, пока finby его не доставит.

Advanced

Order status after payment: статус заказа, который устанавливается после успешной оплаты. Статус меняется за один шаг, поэтому покупатель получает одно письмо.

Debug logging: Log API requests and notifications добавляет подробности в журнал. Ошибки всегда записываются в журнал, даже если эта опция выключена. Журналы находятся в WooCommerce > Status > Logs, источник wcp_trustpay_gateway, и не содержат ключей, токенов, данных карт и данных покупателей. По умолчанию: выключено.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept). По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Card payment (TrustPay)) и оформляет заказ. В тестовом режиме под описанием при оформлении заказа отображается Test mode: no real payment will be taken.

Для оплаты картой нужен адрес для выставления счёта. Если не заполнены улица, город, почтовый индекс или страна, покупатель видит Please enter your billing address (street, city, postcode and country) — it is required for card payments.

Плагин создаёт в finby запрос на оплату картой на сумму заказа в валюте заказа. Имя, адрес и e-mail покупателя передаются для 3-D Secure, а ID заказа передаётся как ссылка. Покупатель перенаправляется на страницу оплаты finby и оплачивает картой там. Страница открывается на языке вашего магазина, если finby его поддерживает, в противном случае на английском. Примечание к заказу показывает запрос на оплату, сумму и проект (тестовый или рабочий).

После оплаты покупатель возвращается на страницу «Заказ получен» вашего магазина, и корзина очищается. Заказ отмечается оплаченным только после того, как finby подтвердит оплату подписанным уведомлением. Само возвращение никогда не меняет статус оплаты.

Если покупатель отменяет платёж на странице оплаты или страница оплаты возвращает ошибку, покупатель возвращается на страницу Pay for order с сообщением The card payment was cancelled. You can try again or choose another payment method. или The card payment was not completed. Please try again or choose another payment method. К заказу добавляется примечание. Покупатель может повторно оплатить со страницы.

Если finby не может начать платёж, покупатель видит We could not start the card payment. Please try again in a moment or choose another payment method. Техническая причина записывается в журнал.

Валюты: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF и USD. Суммы в HUF передаются без десятичных знаков. На странице Pay for order проверяется валюта заказа.

Способ оплаты работает в классическом оформлении заказа, в блоке оформления заказа и на странице Pay for order. Он совместим с WooCommerce High-Performance Order Storage (HPOS). Плагин поставляется с переводами на английский, словацкий и чешский языки.

Плагин принимает только платежи картами в виде покупки в один шаг на странице finby. В нём нет банковских переводов и других способов оплаты finby, кнопок Apple Pay и Google Pay, сохранённых карт, подписок и регулярных платежей, раздельных авторизации и списания, а также запросов статуса.

Заказы и возвраты

Статусы заказа

Pending payment: покупатель был перенаправлен на finby и ещё не оплатил или уведомление ещё не поступило.

Processing or Completed: finby подтвердил оплату, сумма и валюта совпадают с запросом на оплату и суммой заказа. Статус соответствует Order status after payment. В примечании к заказу показаны сумма, запрос на оплату и проект. ID транзакции — это ID запроса на оплату finby.

On hold: устанавливается в трёх случаях. Платёж ещё ожидает решения finby, и заказ ждёт окончательного результата. Платёж только авторизован, но не списан: спишите или отмените его в finby Merchant Portal, затем обновите заказ. Либо оплаченная сумма или валюта отличаются от запроса на оплату или суммы заказа, например потому, что заказ был изменён после перехода покупателя на страницу оплаты: проверьте платёж перед отправкой. Примечание к заказу объясняет случай.

Failed: finby отклонил последний платёж по заказу. Примечание показывает причину, если finby её передал. Покупатель может повторно оплатить со страницы Pay for order.

Отменённые или возвращённые заказы никогда не переоткрываются из-за запоздалой оплаты. Примечание просит вас восстановить заказ или вернуть платёж в Merchant Portal. Если поступает вторая оплата уже оплаченного заказа, заказ не меняется, а примечание просит вас вернуть дубликат в Merchant Portal. Чарджбэки и споры, о которых сообщил finby, добавляются как примечания.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Card payment (TrustPay) (на кнопке отображается ваш Title). Поддерживаются полные и частичные возвраты. Возврат выполняется в тот проект, через который был оплачен заказ (тестовый или рабочий), даже если вы с тех пор переключили режим, поэтому ID проекта и секретный ключ этого режима должны быть заполнены. Возвраты в HUF должны быть целыми суммами.

Возврат фиксируется только тогда, когда finby его принимает. Иначе WooCommerce показывает TrustPay refused the refund: с причиной, и возврат не создаётся. Успешный возврат добавляется в примечания к заказу.

Возвраты, сделанные в finby Merchant Portal, не фиксируются как возвраты WooCommerce. Если finby присылает об этом уведомление, оно добавляется как примечание к заказу, а статус заказа не меняется.

Лицензионный ключ

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > TrustPay / finby. Вставьте ключ в поле License key и нажмите Activate. В блоке отображается статус, например дата, до которой лицензия активна, и ваш домен. Используйте Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает место под домен. Освободите место в своём аккаунте на vibefox.net.

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

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

Устранение неполадок

Card payment (TrustPay) не появляется при оформлении заказа: проверьте, что лицензия активна, Enable / Disable включён и у текущего режима есть ID проекта и секретный ключ: Test Project ID и Test Secret key в тестовом режиме, Live Project ID и Live Secret key в рабочем режиме. Валюта магазина или валюта заказа на странице Pay for order должна быть одной из поддерживаемых. В обоих случаях страница настроек показывает предупреждение. Разработчики могут изменить список валют с помощью фильтра trustpay_p_supported_currencies.

Платёж прошёл, но заказ остаётся в статусе Pending payment: уведомление не дошло до вашего магазина. Проверьте, что https://your-site/wc-api/trustpay_payment_callback/ доступен из интернета (без файервола, режима обслуживания и защиты паролем). finby повторяет уведомление. Посмотрите WooCommerce > Status > Logs, источник wcp_trustpay_gateway.

В журнале: Notification rejected: invalid signature or unknown project: уведомление пришло от проекта, ID которого нет в настройках, или секретный ключ этого проекта неверен. Магазин отвечает Invalid signature, заказ не меняется. Проверьте ID проекта и секретный ключ того режима, в котором была сделана оплата.

В журнале: Notification ignored: уведомление относится к запросу на оплату, который этот магазин не создавал для данного заказа, или к проекту, отличному от того, с которым был начат платёж. Заказ не меняется.

Уведомление получает ответ Busy, retry later: заказ в этот момент обновлялся другим уведомлением. finby повторит его.

Покупатель видит We could not start the card payment: откройте журнал. Неверные ID проекта или секретный ключ дают сообщение о том, что finby отклонил учётные данные проекта. Проверьте, что тестовые данные указаны в тестовых полях, а рабочие — в рабочих.

Оплата картой временно недоступна: покупатель видит это сообщение, когда у текущего режима нет ID проекта или секретного ключа. Введите их и сохраните.

Заказ On hold с примечанием о расхождении суммы или валюты: уведомление было подлинным, но оплаченная сумма или валюта не совпадают с запросом на оплату или суммой заказа. Проверьте платёж в Merchant Portal перед отправкой, затем выполните заказ или верните платёж.

Возврат не выполняется, сообщение касается проекта: заказ был оплачен через тестовый или рабочий проект, а ID проекта или секретный ключ этого режима не заполнены либо сейчас сохранён другой ID проекта. Введите учётные данные этого проекта или верните платёж в finby Merchant Portal.

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

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его, деактивируйте и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина, а также кэшированные токены доступа к API всегда удаляются. Настройки шлюза и журналы плагина (файлы журналов, включая старые ротированные файлы, и записи журнала в базе данных) удаляются только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Данные заказов сохраняются: существующие заказы сохраняют свои примечания об оплате, ID запросов на оплату и ID транзакций.

TrustPay и finby являются товарными знаками их владельцев. Этот плагин не связан с TrustPay или finby и не поддерживается ими.