VibeFox Tap for WooCommerce — Помощь

Требования

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

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

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

Валюта магазина: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR или USD. Для других валют способ оплаты скрыт при оформлении заказа.

Доступ к вашему сайту из Интернета: Tap отправляет результат платежа на вебхук вашего магазина, поэтому сайт должен быть доступен из Интернета. URL вебхука передаётся с каждым платежом; в панели Tap ничего настраивать не нужно.

Учётная запись Tap: вам нужны ключи API из панели Tap (goSell, учётные данные API). Тестовые ключи начинаются с pk_test_ / sk_test_, рабочие — с pk_live_ / sk_live_. Секретный ключ нужен всегда; публичный ключ — только для всплывающего окна Tap Checkout. Какие способы оплаты предлагаются (mada, KNET, Benefit и другие) и подтверждение домена для Apple Pay настраиваются в вашей учётной записи Tap.

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите тестовые и рабочие ключи Tap, выберите действие при оплате, тип оформления и язык страницы Tap (см. Настройки).

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

Настройки

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Tap Payments. Над полями страница показывает Test mode is on: payments use your Tap test keys and no real money is charged., пока включён тестовый режим. Она также сообщает, если для текущего режима не хватает ключей (тогда шлюз не отображается при оформлении заказа), и если валюта магазина не поддерживается Tap. В списке способов оплаты Tap Payments помечен как требующий настройки, пока для текущего режима не задан секретный ключ (а для всплывающего окна — и публичный ключ).

При сохранении ключ с неверным префиксом для своего поля не сохраняется: появляется ошибка, а прежнее значение остаётся. Например, рабочий ключ в поле тестового ключа отклоняется.

Общие

Enable / Disable: Enable Tap Payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое показывается при оформлении заказа. По умолчанию: Tap Payments.

Description: текст, который показывается под способом оплаты при оформлении заказа. По умолчанию: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Ключи API Tap

Ключи находятся в панели Tap (goSell, учётные данные API). Тестовые ключи начинаются с pk_test_ / sk_test_, рабочие — с pk_live_ / sk_live_.

Test mode: Use the test keys (no real money is charged). Платежи, проверки статуса и возвраты всегда используют ключи того режима, в котором был произведён платёж. Поэтому тестовый платёж и после переключения на рабочий режим проверяется и возвращается тестовым ключом. По умолчанию: включено.

Test publishable key: начинается с pk_test_. Нужен для всплывающего окна.

Test secret key: начинается с sk_test_.

Live publishable key: начинается с pk_live_. Нужен для всплывающего окна.

Live secret key: начинается с sk_live_.

Merchant ID: необязательно. Ваш идентификатор мерчанта Tap; нужен только если Tap попросил направлять платежи на определённую учётную запись мерчанта.

Оплата

Payment action: что происходит с деньгами, когда покупатель платит.

Checkout type: где покупатель платит.

Tap page language: English (по умолчанию) или Arabic.

Уведомления об оплате (вебхук)

Tap передаёт результат платежа на URL, показанный в этом разделе. Он выглядит так: https://your-site/wc-api/tap_p_webhook/. URL передаётся с каждым платежом, поэтому в панели Tap ничего настраивать не нужно. Просто убедитесь, что он доступен из Интернета (не заблокирован брандмауэром, режимом обслуживания или HTTP-аутентификацией). Каждое уведомление проверяется по подписи hashstring (HMAC-SHA256 с секретным ключом режима платежа). Вебхуки без действительной подписи отклоняются. Даже подписанному уведомлению не доверяют безусловно: плагин повторно считывает платёж через API Tap, прежде чем изменить заказ. Без работающего вебхука заказ обновляется только тогда, когда покупатель возвращается в магазин после оплаты.

Дополнительно

Debug log: Log payment events (WooCommerce → Status → Logs, source "wcp_tap_payment_gateway"). Ошибки записываются всегда. Журнал никогда не содержит ключей, данных карты или покупателя. По умолчанию: выключено.

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

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

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

Tap payment page: плагин создаёт платёж Tap (или авторизацию в режиме Authorize only) на сумму заказа в валюте заказа с описанием Order # и номером заказа и перенаправляет покупателя на страницу оплаты Tap. Там покупатель выбирает карту, mada, KNET, Benefit, Apple Pay или Google Pay (в зависимости от того, что включено в вашей учётной записи Tap), и платит. Если Tap не может начать платёж, покупатель видит The Tap payment could not be started. Please try again or choose another payment method., а причина добавляется в примечания к заказу.

Tap checkout popup: покупатель переходит на страницу оплаты заказа, где открывается форма оплаты Tap. На странице также есть ссылка Pay on the Tap payment page instead. Если окно закрыто, кнопка Pay now открывает его снова. Если форму не удаётся загрузить, покупателя просят воспользоваться страницей оплаты Tap.

После оплаты покупатель возвращается на страницу получения заказа. Заказ отмечается оплаченным только после подтверждения Tap: плагин считывает платёж через API Tap с ключом режима платежа, проверяет, что он относится к этому заказу и был инициирован его оформлением, и сверяет сумму и валюту с заказом. Одного только идентификатора Tap в адресе возврата недостаточно, чтобы отметить заказ оплаченным. Вебхук выполняет ту же проверку в фоновом режиме. Повторные вебхуки и возвраты никогда не меняют заказ дважды (одно изменение за раз для каждого заказа).

Если оплата ещё не подтверждена, страница получения заказа показывает We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. Для авторизованного платежа показывается Your payment has been authorized. We will process the order as soon as the payment is captured.

Если платёж был отклонён или покупатель его прервал, заказ получает статус «Неудачный», а покупатель возвращается на страницу Pay for order с сообщением Your payment was not completed. Please try again or choose another payment method. (с причиной от Tap, если она есть). Незавершённый платёж показывает The payment was not completed. You can try again below. Покупатель может снова оплатить заказ с этой страницы.

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

В плагине нет сохранённых карт и токенизации, подписок и полей для ввода карты, встроенных в страницу оформления заказа. Capture Tap payment всегда списывает всю сумму заказа; частичное списание не поддерживается.

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

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

Pending payment: покупатель был перенаправлен в Tap и ещё не оплатил, или Tap ещё не подтвердил платёж.

Processing: Tap подтвердил списанный платёж. Это стандартный статус WooCommerce после оплаты (заказы, содержащие только виртуальные загружаемые товары, сразу переходят в «Выполнен»). В примечании к заказу указаны сумма, идентификатор платежа Tap (chg_...), способ оплаты и (в тестовом режиме) отметка о тестовом платеже. Идентификатор транзакции — это идентификатор платежа Tap.

On hold: платёж только авторизован и ожидает списания; либо оплаченная сумма или валюта не совпали с заказом (Tap: amount/currency mismatch — manual review required.); либо платёж поступил после отмены заказа. Примечание к заказу поясняет причину.

Failed: платёж был отклонён, прерван, отменён или истёк по времени. Статус «Неудачный» получает только заказ, который всё ещё ожидает оплаты; неудачная попытка никогда не меняет оплаченный, авторизованный или отменённый заказ. Покупатель может оплатить снова.

Cancelled: авторизация аннулирована через Void Tap authorization, поэтому зарезервированные средства освобождены.

Если для уже оплаченного заказа поступает второй успешный платёж, заказ не меняется. Примечание сообщает, что это повторный платёж, и предлагает вернуть его через панель Tap. Платёж, который относится к заказу, но не был инициирован его оформлением, только отмечается в примечании.

Списание и отмена

В режиме Authorize only откройте заказ «На удержании» и выберите в Order actions: Capture Tap payment списывает сумму заказа; после этого заказ становится оплаченным. Void Tap authorization освобождает средства и отменяет заказ. Если Tap отклоняет действие, показывается ошибка и она добавляется в примечания к заказу. Если авторизация списана напрямую в панели Tap, вебхук отмечает заказ как оплаченный; возвраты по такому платежу нужно делать в панели Tap.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Tap Payments (на кнопке отображается ваш Title). Полные и частичные возвраты поддерживаются для списанных платежей Tap. Возврат отправляется с секретным ключом того режима, в котором был произведён платёж, поэтому этот ключ должен быть задан. Возврат, принятый Tap, добавляется в примечания к заказу с идентификатором и статусом возврата Tap. Если Tap его отклоняет, WooCommerce показывает ошибку, и возврат не регистрируется. Возвраты, сделанные в панели Tap, в WooCommerce не отображаются.

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

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

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

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

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

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

Tap Payments не отображается при оформлении заказа: проверьте, что лицензия активна, Enable / Disable включено и в текущем режиме задан секретный ключ (а также публичный ключ, если Checkout type — всплывающее окно). Проверьте, что валюта магазина (или валюта заказа на странице Pay for order) входит в список AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD. На странице настроек показывается уведомление для каждой из этих проблем.

Платёж прошёл, но заказ остаётся в статусе Pending payment: вебхук не может достучаться до вашего сайта. Проверьте, что URL из настроек (/wc-api/tap_p_webhook/) доступен из Интернета (без брандмауэра, режима обслуживания и HTTP-аутентификации), и посмотрите WooCommerce > Status > Logs, источник wcp_tap_payment_gateway. Заказ также обновляется, когда покупатель возвращается из Tap.

Webhook answers invalid signature: уведомление не подписано секретным ключом режима платежа. Проверьте секретные ключи в настройках.

Webhook answers gateway not configured: секретный ключ режима платежа (тестового или рабочего) пуст. Введите его.

Webhook answers verification failed: не удалось обратиться к API Tap для проверки платежа. Tap повторит вебхук позже.

Ключ не сохраняется: ключ должен начинаться с префикса своего поля: pk_test_, sk_test_, pk_live_ или sk_live_.

Заказ On hold: прочитайте примечание к заказу. Платёж только авторизован (спишите его через действия с заказом), оплаченная сумма или валюта не совпали с заказом, или платёж поступил после отмены заказа.

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

Хуки для разработчиков: доступны фильтры tap_p_supported_currencies, tap_p_currency_decimals, tap_p_charge_payload, tap_p_icon, tap_p_checkout_sdk_url и tap_p_payment_page_hosts.

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

Удаление

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

Tap Payments — торговая марка её правообладателя. Этот плагин не связан с Tap Payments и не одобрен ею.