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. Покупець може знову оплатити замовлення з цієї сторінки.

Спосіб оплати працює на класичному оформленні замовлення, у блоці Checkout і на сторінці 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 і не схвалений нею.