VibeFox Windcave for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша версія. Модуль відмовляється встановлюватися на старіших версіях PHP.

Обліковий запис Windcave: потрібен обліковий запис мерчанта Windcave з обліковими даними REST API: ім'я користувача API та API-ключ. Windcave видає їх окремо для тестового середовища UAT (uat.windcave.com) і для робочого середовища (sec.windcave.com). Запитайте їх у служби підтримки Windcave або у свого менеджера. Ключі PxPay з цим модулем не працюють. Способи оплати, які ви хочете пропонувати (картки, гаманці та інші), мають бути увімкнені у вашому обліковому записі Windcave.

Сповіщення: ваш магазин має бути доступним з інтернету, щоб Windcave міг надіслати своє сповіщення про платіж. Нічого налаштовувати в Windcave для цього не потрібно.

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

Встановлення

1. В адмінпанелі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox Windcave Payment Gateway у списку модулів і натисніть Configure.

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

4. Введіть ім'я користувача та ключ REST API: облікові дані UAT для тестового режиму та облікові дані робочого середовища для реальних платежів (див. Налаштування).

5. Оберіть тип транзакції та способи оплати, увімкніть Enable/Disable і натисніть Save. Зробіть тестовий платіж із увімкненим Test mode, а потім вимкніть Test mode, щоб приймати реальні платежі.

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

Налаштування

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Поки тестовий режим увімкнено, сторінка показує Test mode увімкнено: платежі йдуть до тестового середовища Windcave UAT, реальні кошти не списуються. Якщо модуль увімкнено, але для поточного режиму не вказано ім'я користувача або ключ API, сторінка попереджає, що спосіб оплати приховано на оформленні замовлення, наприклад: Windcave увімкнено, але ім'я користувача або ключ API UAT порожні — спосіб оплати приховано на оформленні замовлення. Поле Title не може бути порожнім: тоді сторінка показує Введіть назву способу оплати. і нічого не зберігається.

Windcave

Enable/Disable: Enable Windcave payments вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачить покупець на оформленні замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Credit/Debit Card (Windcave). Обов'язкове поле.

Description: текст, який показується під способом оплати на оформленні замовлення. За замовчуванням: You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

Введіть облікові дані REST API, видані Windcave (ім'я користувача та API-ключ, а не ключі PxPay). Облікові дані робочого середовища та UAT можна зберегти поруч. Тестовий режим використовує лише облікові дані UAT, робочий режим — лише облікові дані робочого середовища. Розділ містить посилання на документацію REST API Windcave.

Test mode: використовує тестове середовище Windcave UAT (uat.windcave.com). Реальні кошти не списуються. Нові платежі використовують облікові дані UAT. Повернення і списання завжди надсилаються в те середовище, у якому було сплачено замовлення. За замовчуванням: вимкнено.

Production API username: ім'я користувача REST API для sec.windcave.com.

Production API key: ключ REST API для sec.windcave.com.

UAT API username: ім'я користувача REST API для uat.windcave.com (тестовий режим).

UAT API key: ключ REST API для uat.windcave.com (тестовий режим).

Збережені ключі API більше не показуються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved keys: позначте Production API key або UAT API key і натисніть Save, щоб видалити ключ. Порожнє поле залишає збережене значення.

Notification URL: показує адресу, на яку Windcave надсилає своє сповіщення про платіж (Fail-Proof Result Notification). За зрозумілих URL вона виглядає так: https://ваш-магазин/module/wcp_windcave_payment_gateway/notification. У Windcave нічого налаштовувати не потрібно: модуль передає свої адреси повернення і цю адресу сповіщення з кожною платіжною сесією. Адреса має бути доступною з інтернету, інакше замовлення підтверджуються лише тоді, коли покупець повертається з Windcave. Ані повернення покупця, ані сповіщення не підписані Windcave, тож модуль ніколи не довіряє їм самостійно: він завжди зчитує результат сесії через REST API Windcave, використовуючи облікові дані того середовища, у якому створено сесію.

Payment

Transaction type: як саме списуються кошти. За замовчуванням: Purchase.

Payment methods: способи, які показуються на платіжній сторінці Windcave: Cards, Account2Account (банківський переказ у Новій Зеландії), Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. Щоб вибрати кілька, використовуйте Ctrl або Cmd і клік. Способи мають бути увімкнені у вашому обліковому записі Windcave. Залиште поле порожнім, щоб показувати всі способи, увімкнені в обліковому записі. За замовчуванням: Cards.

Advanced

Debug log: записує запити до API і події оплати у файл logs/windcave_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Поки цей параметр вимкнено, записуються лише помилки і попередження. Ключі API, дані картки та персональні дані покупців ніколи не записуються. За замовчуванням: вимкнено.

Log: показує розмір журналу та його останні записи. Натисніть Clear log, щоб очистити журнал.

Clean uninstall: під час видалення модуля видаляє його налаштування та журнали. Платіжні дані, збережені із замовленнями (ідентифікатори транзакцій Windcave, потрібні для повернень), завжди зберігаються. За замовчуванням: вимкнено.

Версія модуля вказана внизу сторінки.

Оформлення замовлення

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Credit/Debit Card (Windcave)) з його описом. У тестовому режимі покупець також бачить Test mode: платежі йдуть до тестового середовища Windcave UAT, реальні кошти не списуються. Після підтвердження модуль створює платіжну сесію Windcave на суму кошика у валюті кошика і надсилає покупця на Windcave Hosted Payment Page. Номер кошика передається як референс мерчанта разом із мовою магазину, а також ім'ям, e-mail, телефоном і платіжною адресою покупця (та адресою доставки, якщо кошику потрібна доставка). На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Windcave: модуль запитує у REST API Windcave результат сесії і тоді, коли покупець повертається, і тоді, коли надходить сповіщення від Windcave. Блокування на рівні кошика гарантує, що платіж застосовується лише один раз. Потім замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з Your Windcave payment has been received. Для замовлення на утриманні (авторизація або платіж, що не відповідає кошику) сторінка показує Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again.

Якщо покупець повернувся після схваленого платежу, але результат ще невідомий, сторінка Payment confirmation показує We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. і кнопку Check again. Сповіщення створює замовлення, щойно Windcave підтверджує платіж.

Якщо покупець повернувся без завершеного платежу, сторінка оформлення замовлення показує одне з цих повідомлень. Кошик зберігається.

Покупець може повторити спробу з тим самим кошиком. Нова спроба спершу перевіряє попередню сесію: якщо вона вже оплачена, замовлення створюється і другий платіж не починається; якщо покупець ніколи не використовував сторінку оплати і кошик не змінився, його повертають на ту саму сторінку. Якщо попередній платіж саме зараз підтверджується, покупець бачить Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.

Якщо Windcave не може розпочати платіж, покупець залишається на оформленні замовлення з коротким повідомленням: що Windcave не зміг розпочати платіж з даними цього замовлення або що платіжний сервіс тимчасово недоступний. Причина записується в журнал. Якщо для поточного режиму немає облікових даних, покупець бачить This payment method is not available at the moment. Please choose another payment method or contact us.

Сповіщення працює, навіть коли магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

Модуль не має підписок і періодичних платежів, збережених карток, вбудованої форми картки на вашому сайті (покупець завжди платить на сторінці Windcave), підтримки API PxPay 2.0 і не додає надбавок. Якщо Windcave додасть надбавку, замовлення зіставляється з основною транзакцією.

Замовлення та повернення

Order statuses

No order yet: покупця надіслано до Windcave, і він не оплатив, Windcave ще не підтвердив платіж, або платіж було відхилено, скасовано чи він прострочений. Існує лише кошик.

Payment accepted: платіж Purchase підтверджено і він відповідає кошику. Платіж записується з ідентифікатором транзакції Windcave, а примітка показує суму, ідентифікатор транзакції, код авторизації, тип картки з замаскованим номером і середовище (UAT або робоче).

Windcave payment on hold (authorised): платіж Auth схвалено, але ще не списано. Жоден платіж не записується до замовлення, доки його не захоплено. Примітка пояснює, як його списати або зняти резерв.

Windcave payment on hold (does not match): Windcave повідомив іншу суму, валюту, референс мерчанта або тип транзакції, ніж у кошику (наприклад, кошик змінили в іншій вкладці після початку оплати). Примітка перелічує відмінності. Для Purchase у валюті кошика платіж записується з сумою, яку Windcave фактично списав. Перевірте платіж у Windcave Payline перед відправленням і за потреби поверніть кошти.

Refunded: платіж повністю повернено або авторизацію знято через модуль.

Якщо для скасованого замовлення надходить схвалений платіж або для вже існуючого замовлення надходить другий схвалений платіж, замовлення не змінюється. Примітка з ідентифікатором транзакції просить повернути кошти в Windcave Payline (або вручну відновити скасоване замовлення).

Windcave payment block

На сторінці замовлення показано блок Windcave payment з ідентифікатором транзакції, ідентифікатором сесії, типом транзакції та статусом із зазначенням середовища, оплаченою сумою, кодом авторизації та карткою, транзакцією списання або скасування, загальною сумою платежу та сумою повернення, позначкою Test mode (UAT) для тестових платежів, історією повернень, усіма сесіями Windcave кошика та Windcave notes замовлення.

Capture (Auth mode)

Для замовлення в статусі Windcave payment on hold з авторизацією, яку ще не списано або не знято, блок показує Capture Windcave payment із сумою. Натисніть і підтвердьте Capture the authorised amount through Windcave now? Авторизовану суму списано (сума замовлення, якщо тільки платіж не відповідає замовленню), замовлення переходить у статус Payment accepted, а платіж записується з ідентифікатором транзакції списання. Якщо Windcave не приймає списання, блок показує Windcave capture failed: з причиною, причина додається до приміток, а замовлення залишається на утриманні.

Refunds

У блоці Windcave payment введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via Windcave. Підтвердьте запитання Refund this amount through Windcave? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Повернення враховуються в межах суми і валюти, схвалених Windcave, тож після невідповідності можна повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повернення після списання йде за транзакцією списання. Повернення надсилається в середовище (UAT або робоче) і на рахунок, з якого було здійснено платіж, тому облікові дані цього середовища мають бути збережені. Успішне повернення додається до історії повернень і приміток з ідентифікатором транзакції Windcave. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

Для платежу Auth, який не списано, кнопка називається Release authorisation (void), і знімати резерв можна лише на повну суму. Часткова сума призводить до помилки з проханням повернути повну суму або спершу списати платіж.

Якщо Windcave відхиляє повернення, блок показує Windcave declined the refund: з причиною, і повернення не записується. Якщо Windcave ще обробляє повернення, блок показує Windcave has not confirmed the refund yet. See the order notes., і повернення не записується. Перевірте транзакцію в Windcave Payline: якщо її схвалено, запишіть повернення вручну; інакше повторіть спробу. Повторна спроба того самого повернення не надсилається до Windcave двічі.

Модуль не створює кредитових нот. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через Windcave. Повернення, зроблені в Windcave Payline, магазину не передаються.

Ліцензійний ключ

Модуль працює з ліцензійним ключем VibeFox, отриманим на vibefox.net. Блок ліцензії License — VibeFox Windcave Payment Gateway — це перший блок у Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої діє ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче є рядок Product: presta-payment-windcave і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише працівники з дозволом Configure для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: домені основного магазину, також у мультимагазинній конфігурації. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму обліковому записі vibefox.net.

Без активного ключа Windcave не показується покупцям на оформленні замовлення. Якщо платіж все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли в back office, тому спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але протестувати його на оформленні замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, які вже розпочато, і далі підтверджуються сповіщенням або поверненням покупця, а повернення та списання працюють.

Коли ліцензія спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову, поки ви працюєте в back office: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Windcave не з'являється на оформленні замовлення: переконайтеся, що ліцензія активна, Enable/Disable увімкнено і в поточному режимі є обидві облікові дані: UAT API username і UAT API key у тестовому режимі, Production API username і Production API key у робочому режимі. Сторінка налаштувань показує попередження, якщо їх немає. В Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: модуль ще не зміг отримати результат від Windcave. Перегляньте поле Log на сторінці модуля: помилки завжди записуються, наприклад коли сесію не вдалося перевірити. Перевірте, що облікові дані середовища платежу збережено і вони правильні. Перевірка повторюється, коли Windcave знову надсилає сповіщення (модуль відповідає payment could not be verified yet, retry later з кодом помилки, щоб Windcave повторив запит), коли покупець натискає Check again і коли покупець починає новий платіж для того самого кошика. Ваш сервер має приймати запити від Windcave на Notification URL, показану в налаштуваннях.

Сповіщення відповідає order not found: сесію створив не цей магазин, наприклад сесія іншого магазину, який використовує той самий обліковий запис Windcave. Таке сповіщення ігнорується.

У журналі Authentication failed: ім'я користувача або ключ REST API неправильні або належать іншому середовищу. Облікові дані UAT працюють лише в тестовому режимі, облікові дані робочого середовища — лише в робочому. Ключі PxPay не працюють.

Покупець бачить, що Windcave не зміг розпочати платіж з даними цього замовлення: Windcave відхилив запит на сесію, наприклад через валюту або спосіб оплати, не увімкнений у вашому обліковому записі. Точна причина є в журналі.

Замовлення в статусі Windcave payment on hold після оплати: прочитайте примітки в блоці Windcave payment. Або платіж є авторизацією Auth, що чекає на списання, або оплачена сума, валюта чи референс мерчанта не збіглися з кошиком. Списуйте, відправляйте або повертайте платіж.

Тестові та реальні платежі: UAT і робоче середовище розділені. Кожну сесію перевіряють у тому середовищі, де її створено, а повернення та списання йдуть до середовища платежу, навіть якщо ви пізніше перемкнете Test mode.

Повернення завершується помилкою з повідомленням про середовище: платіж було здійснено в UAT або в робочому середовищі, а облікові дані для цього середовища не збережено. Введіть їх і повторіть спробу.

У блоці замовлення немає Capture Windcave payment: кнопка показується лише для замовлень у статусі Windcave payment on hold, оплачених через Auth і ще не списаних або не знятих, і лише працівникам, які мають право редагувати замовлення.

Де шукати деталі: помилки та попередження завжди записуються в журнал; увімкніть Debug log, щоб також записувати запити до API та події оплати.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Windcave Payment Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля видаляються завжди. Якщо Clean uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Сесії, транзакції та повернення Windcave, а також статус замовлення Windcave payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна й далі повертати та списувати після повторного встановлення. Наявні замовлення зберігають свої платіжні примітки та ідентифікатори транзакцій.

Windcave є торговельною маркою його власника. Цей модуль не пов'язаний із Windcave і не схвалений компанією Windcave.