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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

Валюта: чилійський песо (CLP) або долар США (USD). Для кошиків в інших валютах спосіб оплати приховано на етапі оформлення замовлення. Для CLP встановіть точність валюти CLP на 0 у розділі International > Localization > Currencies, оскільки Flow стягує цілі песо.

Обліковий запис Flow: потрібні API Key і Secret Key вашого облікового запису Flow, у Flow в розділі Mis datos, Datos técnicos. Для тестів створіть окремий тестовий обліковий запис на sandbox.flow.cl і використовуйте його ключі. Ключі тестового та робочого режимів різні. В обліковому записі Flow нічого налаштовувати не потрібно.

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

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

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

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

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

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

4. Введіть API Key і Secret Key тестового середовища, увімкніть Enable / Disable, натисніть Save і зробіть тестове замовлення.

5. Щоб приймати реальні платежі, заповніть робочі ключі та вимкніть Sandbox mode.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Flow Gateway > Configure. Кожен розділ із полями має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо ключі поточного режиму порожні (тоді Flow приховано на етапі оформлення замовлення), якщо валюта магазину за замовчуванням не CLP і не USD, та якщо у валюти CLP є десяткові знаки (встановіть її точність на 0, щоб ціни, суми та повернення коштів збігалися точно). У тестовому режимі вона показує Sandbox mode — payments go to sandbox.flow.cl, no real money is charged.

Flow.cl

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

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

Description: текст під способом оплати на етапі оформлення замовлення. За замовчуванням: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.

API-ключі Flow

Скопіюйте API Key і Secret Key з вашого облікового запису Flow (Mis datos, Datos técnicos): робочі ключі — на www.flow.cl, тестові — на sandbox.flow.cl (окремий тестовий обліковий запис).

Sandbox mode: використовує тестове середовище Flow (sandbox.flow.cl) і тестові ключі. У тестовому режимі реальні гроші не списуються. За замовчуванням: on. Вимкніть його та заповніть робочі ключі, щоб приймати реальні платежі. Повернення коштів завжди виконуються в середовищі, у якому було оплачено замовлення.

Sandbox API Key: API Key вашого облікового запису sandbox.flow.cl.

Sandbox Secret Key: Secret Key вашого облікового запису sandbox.flow.cl. Він використовується для підпису кожного запиту.

Live API Key: API Key вашого облікового запису www.flow.cl.

Live Secret Key: Secret Key вашого облікового запису www.flow.cl. Тримайте його в таємниці.

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

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

Сповіщення

Модуль надсилає три URL до Flow з кожним платежем і поверненням коштів, тож в обліковому записі Flow нічого налаштовувати не потрібно. Поле Flow URLs цього розділу їх перелічує. За увімкнених зрозумілих URL вони виглядають так:

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

Додатково

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

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

Delete data on uninstall: якщо увімкнено, видалення модуля видаляє його налаштування та журнал. Дані Flow, збережені в замовленнях, зберігаються. За замовчуванням: off.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Flow) і бачить опис. У тестовому режимі показується SANDBOX MODE — платежі йдуть до тестового середовища Flow, реальних списань немає. Після підтвердження модуль створює платіж Flow на суму кошика у валюті кошика з призначенням Cart #, номером кошика та назвою магазину і надсилає покупця на платіжну сторінку Flow. Адреса електронної пошти покупця передається до Flow. Там покупець обирає спосіб оплати, увімкнений у вашому обліковому записі Flow. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається як оплачене лише після підтвердження Flow: підтвердженням або підписаним запитом статусу, коли покупець повертається. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з Your payment with Flow has been received. Якщо покупець створив купон Servipag або Multicaja, замовлення створюється в статусі Awaiting Flow payment, а сторінка показує Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. Якщо оплата замовлення за купоном пізніше не вдалася або її скасовано, сторінка показує Your Flow payment was not completed. Please contact us about this order. Якщо сума не збіглася, сторінка показує Your Flow payment was received and is being reviewed by the shop.

Якщо Flow недоступний, коли покупець повертається, або в цей момент замовлення створює інший запит, сторінка Payment confirmation просить покупця не платити повторно та пропонує Check again і Back to checkout.

Якщо платіж відхилено, покупець повертається до оформлення замовлення з повідомленням Your Flow payment was rejected. Please try again or choose another payment method. Якщо покупець вийшов зі сторінки Flow без оплати, повідомлення таке: The Flow payment was not completed. You can try again or choose another payment method. Якщо результат не вдалося перевірити, повідомлення таке: We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. Кошик зберігається, і кожна нова спроба створює новий платіж Flow, прив'язаний до кошика.

Якщо Flow не може розпочати платіж, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад Could not connect to Flow. Please try again in a moment. Подробиці записано в журналі.

Якщо купон у кошику перестає бути дійсним між оплатою та її підтвердженням, PrestaShop видаляє його із замовлення. Замовлення тоді переходить у статус Flow payment on hold із приміткою, бо покупець сплатив ціну зі знижкою.

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

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

Статуси замовлення

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

Payment accepted: Flow повідомив, що платіж оплачено, а сума та валюта збігаються. Платіж записується з номером замовлення Flow як ID транзакції, а примітка показує суму, номер замовлення Flow і спосіб оплати.

Awaiting Flow payment: покупець створив купон на оплату Servipag або Multicaja. Замовлення переходить у статус Payment accepted, коли Flow підтверджує платіж.

Flow payment on hold: Flow повідомив суму або валюту, що відрізняються від загальної суми замовлення (наприклад, кошик змінили після початку оплати), купон було видалено або платіж надійшов для скасованого замовлення. Платіж, списаний Flow, записується, а примітка пояснює ситуацію. Перевірте замовлення та відправте його або поверніть кошти за платіж.

Payment error: Flow відхилив платіж за купоном для замовлення в очікуванні.

Canceled: платіж за купоном для замовлення в очікуванні було анульовано у Flow.

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

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

Блок платежу Flow

На сторінці замовлення показано блок Flow payment з номером замовлення Flow і способом оплати, посиланням commerceOrder, статусом платежу, сплаченою та поверненою сумою, позначкою Sandbox для тестових платежів, історією повернень коштів і Flow notes замовлення.

Повернення коштів

У блоці Flow payment введіть суму (підставляється сума, яку ще не повернено), за потреби причину, і натисніть Refund via Flow. Підтвердьте запитання Refund this amount via Flow? Flow e-mails the customer to complete the refund. Підтримуються повне та часткове повернення. Потрібне право редагувати замовлення. Повернення обмежені сумою, яку Flow фактично списав, тож після розбіжності сум можна повернути лише до суми, сплаченої покупцем, а не загальну суму замовлення. Повернення в CLP мають бути цілими сумами. Повернення надсилається в те середовище, де було здійснено платіж (тестове чи робоче), тому ключі цього середовища мають бути заповнені, а в покупця має бути дійсна адреса електронної пошти. Якщо Flow відхиляє повернення, блок показує помилку, і повернення не записується. Успішний запит додається до історії повернень і приміток з номером і статусом повернення Flow. Повне повернення переводить замовлення в статус Refunded. Часткове повернення не змінює статус. Повернення доступні після підтвердження платежу Flow.

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

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

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

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

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

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

Flow не з'являється на етапі оформлення замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено, ключі поточного режиму заповнені (тестові — у тестовому режимі, робочі — у робочому) і валюта кошика — CLP або USD. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: підтвердження Flow не доходить до вашого магазину, а покупець не повернувся. Перевірте, що URL підтвердження з Flow URLs відкривається з інтернету і його не блокує захист паролем або брандмауер. Увімкніть Debug log і перегляньте поле Log на сторінці модуля.

Підтвердження відповідає Payment does not belong to the order: токен не є платежем, створеним цим магазином, або Flow повідомив для нього інше посилання. Нічого не змінюється.

Підтвердження відповідає Gateway not configured: ключі середовища платежу порожні. Введіть їх знову. Flow повторить підтвердження.

Підтвердження відповідає Flow API unavailable or Busy, retry: запит статусу до Flow не виконано, або замовлення в ту саму мить створював інший запит. Flow повторить підтвердження.

Покупець бачить Flow payments are not available at the moment: ключі відсутні або Flow їх відхилив. Перевірте API Key і Secret Key поточного режиму.

Покупець бачить A valid billing email is required for Flow payments: Flow потребує адресу електронної пошти покупця.

Покупець бачить The order total is too small to be paid with Flow: загальна сума кошика округлюється до нуля у валюті кошика.

Покупець сплатив, але замовлення має статус Awaiting Flow payment або Flow payment on hold: прочитайте примітки в блоці Flow payment. Покупець створив купон на оплату готівкою, який ще не сплачено, або сума чи валюта, повідомлені Flow, не збігаються із замовленням. Суми в CLP з десятковими знаками округлюються до цілих песо, тож встановіть точність CLP на 0.

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

Повернення коштів не вдається з Flow accepts CLP refunds in whole units only: введіть ціле значення суми.

Для розробників README перелічує хуки actionWcpFlowSupportedCurrencies (валюти, для яких пропонується спосіб оплати) і actionWcpFlowPaymentSubject (призначення платежу, що надсилається до Flow).

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Flow Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Записи платежів і повернень Flow та статуси замовлень Awaiting Flow payment і Flow payment on hold завжди зберігаються, тож замовлення, сплачені раніше, можна повернути й після повторного встановлення. Існуючі замовлення зберігають свої примітки про оплату та ID транзакцій.

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