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 і не схвалений нею.