VibeFox Tap for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

Валюта магазина: 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_. Секретный ключ нужен всегда; публичный — только для всплывающего окна. Какие способы оплаты предлагаются (mada, KNET, Benefit и другие) и подтверждение домена Apple Pay настраиваются в вашей учётной записи Tap.

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

Установка

1. В бэк-офисе откройте Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Tap Payments в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. раздел «Лицензионный ключ»).

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

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

При установке модуль создаёт два статуса заказа: Tap payment authorized и Tap payment on hold. PrestaShop предлагает новый способ оплаты для всех валют, стран и групп покупателей. Ограничить его можно в разделе Payment > Preferences.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Tap Payments > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Test mode is on: payments use your Tap test keys and no real money is charged. или Live mode: real payments are accepted. Она также предупреждает, если ключи текущего режима не заполнены (тогда способ оплаты не показывается на странице оформления заказа), и если валюта магазина по умолчанию не поддерживается Tap.

При сохранении ключ с неверным префиксом для своего поля не сохраняется: остаётся предыдущее значение, остальные настройки сохраняются, и появляется сообщение вида Test secret key was not saved: a Tap key for this field starts with "sk_test_". Например, рабочий ключ в тестовом поле отклоняется. Пустое поле Title не принимается: страница показывает Enter a title for the payment method., и ничего не сохраняется.

Tap Payments

В заголовке раздела также отображается TEST или LIVE для текущего режима.

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: использует тестовые ключи, реальные деньги не списываются. Платежи, проверки статуса, списания и возвраты всегда используют ключи того режима, в котором был произведён платёж, поэтому тестовый платёж и после переключения на рабочий режим проверяется и возвращается тестовым ключом. По умолчанию: включено. Пока режим включён, покупатели видят под способом оплаты Test mode: no real payment will be made.

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

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

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

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

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

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

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

Оплата

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

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

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

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

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

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

Debug log: записывает события платежей в logs/tap_p_debug.log.php в папке модуля. Файл нельзя прочитать через веб. Ошибки и предупреждения записываются всегда; включите эту опцию, чтобы записывать также каждое событие платежа. В журнале никогда нет ключей, данных карт или покупателей. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete data on uninstall: если включено, при удалении модуля удаляются настройки шлюза и журнал. Записи о платежах заказов сохраняются. По умолчанию: выключено.

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Tap Payments) и подтверждает заказ. На этом этапе заказа ещё не существует.

Tap payment page: модуль создаёт списание Tap (или авторизацию в режиме Authorize only) на сумму корзины в валюте корзины с описанием Cart # и номером корзины и отправляет покупателя на страницу оплаты Tap. Имя, e-mail и телефон покупателя передаются в 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 payment модуля, где открывается форма оплаты Tap. На странице также есть ссылка Pay on the Tap payment page instead. Если окно закрыто, кнопка Pay now открывает его снова. Если форму не удаётся загрузить, покупателю предлагается использовать страницу оплаты Tap. Перезагрузка страницы использует ту же попытку оплаты.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Tap: модуль получает платёж через API Tap с ключом режима платежа, проверяет, что он относится к этой корзине и был запущен её оформлением, и сверяет сумму и валюту с корзиной. Идентификатор Tap в адресе возврата сам по себе никогда не создаёт заказ. Вебхук выполняет ту же проверку в фоновом режиме. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа. Для авторизованного платежа страница показывает Your payment has been authorized. We will process the order as soon as the payment is captured., для заказа на удержании — Your payment is being reviewed. We will contact you if anything else is needed.

Если Tap ещё не подтвердил платёж к моменту возврата покупателя, появляется страница Payment confirmation с текстом 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. и кнопками Check again и Back to checkout. Вебхук создаст заказ сразу, как только его получит.

Если платёж отклонён, прерван или отменён, заказ не создаётся. Покупатель возвращается к оформлению заказа с сообщением Your payment was not completed. Please try again or choose another payment method. (с причиной от Tap, если Tap её указывает). Незавершённый платёж показывает The payment was not completed. You can try again or choose another payment method. Корзина сохраняется и может быть оплачена снова.

Прочие сообщения на оформлении заказа: Tap does not accept payments in и код валюты, если валюта корзины не поддерживается, а также The order total must be greater than zero to pay with Tap.

Вебхук работает, когда магазин находится в режиме обслуживания, и не блокируется ограничением по стране вашего магазина.

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

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

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

Заказа ещё нет: покупатель был отправлен в Tap и не оплатил, или Tap ещё не подтвердил платёж. Существует только корзина.

Payment accepted: Tap подтвердил списанный платёж. Платёж записывается с идентификатором списания Tap (chg_...) как ID транзакции, а примечание показывает сумму, ID списания, способ оплаты и (в тестовом режиме) отметку, что платёж тестовый.

Tap payment authorized: платёж только авторизован и ждёт списания или аннулирования.

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

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

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

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

Блок оплаты Tap

На странице заказа есть блок Tap payment с ID Tap, авторизацией и списанием, режимом (значок Test mode для тестовых платежей), статусом и способом оплаты, Charged / refunded, историей возвратов, попытками оплаты корзины и Payment notes заказа. Кнопки блока работают прямо на странице заказа; нужно право редактировать заказы, а не доступ к настройкам модуля.

Списание и аннулирование

В режиме Authorize only откройте заказ в статусе Tap payment authorized. Capture Tap payment (с суммой заказа на кнопке) списывает сумму заказа после вопроса Capture the reserved funds of this order through Tap?; после этого заказ переходит в статус Payment accepted. Void Tap authorization спрашивает Release the reserved funds? The order will be canceled., освобождает средства и переводит заказ в статус Canceled. Если Tap отклоняет действие, в блоке показывается ошибка и она добавляется в примечания. Если авторизация списана напрямую в панели Tap, вебхук отмечает заказ оплаченным; возвраты по такому платежу нужно делать в панели Tap.

Возвраты

В блоке Tap payment введите сумму (подставляется сумма, ещё не возвращённая), при необходимости причину, и нажмите Refund via Tap. Подтвердите вопрос Refund this amount through Tap? This cannot be undone. Полные и частичные возвраты поддерживаются для списанных платежей Tap. Можно вернуть не больше суммы и валюты, которые Tap фактически списал, даже если заказ был изменён позже. Возврат отправляется с секретным ключом того режима, в котором был произведён платёж, поэтому этот ключ должен быть задан. Возврат, принятый Tap, добавляется в историю возвратов и примечания с ID и статусом возврата Tap. Если Tap его отклоняет, блок показывает ошибку, и возврат не записывается. Полный возврат переводит заказ в статус Refunded; частичный возврат статус не меняет. Для авторизованного заказа возвраты доступны после списания авторизации. Заказ на удержании после расхождения суммы или валюты возвращается в панели Tap.

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Tap. Возвраты, сделанные в панели Tap, в PrestaShop не отображаются.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Tap Payments — это первый блок на странице Modules > Module Manager > VibeFox Tap Payments > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-tap и ссылка 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.

Без активного ключа Tap Payments не отображается покупателям на странице оформления заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но нельзя проверить на оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты, списание и аннулирование работают.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в бэк-офисе: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Решение проблем

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

Платёж прошёл, но заказ не создан: вебхук не может достучаться до вашего магазина. Проверьте, что URL из Webhook URL доступен из интернета (без файрвола и HTTP-аутентификации), и включите Debug log, чтобы видеть ответы в поле Log. Заказ также создаётся, когда покупатель возвращается из Tap.

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

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

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

Webhook answers order not found: уведомление указывает на корзину, у которой нет попытки оплаты Tap в этом магазине.

Webhook answers busy, retry later or order could not be updated, retry later: заказ в этот момент подтверждался другим запросом, либо заказ не удалось создать (например, модуль отключён). Tap повторит вебхук. Причину ищите в поле Log.

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

Покупатель видит The Tap payment could not be started: посмотрите поле Log на странице модуля. Там записываются неверный ключ или отклонённый запрос.

Покупатель видит We could not match this payment to an order: платёж не относится к этой корзине или не был запущен её оформлением. Если деньги списаны, проверьте платёж в панели Tap.

Заказ в статусе Tap payment on hold: прочитайте примечания в блоке Tap payment. Оплаченная сумма или валюта не совпали с корзиной, либо платёж пришёл после отмены заказа.

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

Хуки для разработчиков: хуки actionWcpTapChargePayload, actionWcpTapSupportedCurrencies и actionWcpTapCurrencyDecimals позволяют разработчику изменить запрос на оплату, поддерживаемые валюты и количество знаков после запятой для валют.

Удаление

Откройте Modules > Module Manager, откройте меню рядом с VibeFox Tap Payments и выберите Uninstall. Ключ лицензии и статус лицензии этого модуля всегда удаляются. Если Delete data on uninstall включено, настройки шлюза и журнал удаляются. Если выключено, все настройки сохраняются для повторной установки. Попытки оплаты и возвраты Tap, а также статусы заказов Tap payment authorized и Tap payment on hold всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои примечания к платежам и ID транзакций.

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