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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта магазину: бразильський реал (BRL). Vindi здійснює списання лише в BRL, тому спосіб оплати приховано для кошиків у будь-якій іншій валюті.

Обліковий запис Vindi: вам потрібен API-ключ вашого облікового запису Vindi. Sandbox Vindi — це окремий тестовий обліковий запис Vindi з власним ключем. Boleto, PIX і BolePix також мають бути увімкнені у вашому обліковому записі Vindi, якщо ви хочете їх пропонувати.

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

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

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

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

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

4. Вставте Sandbox API key і, коли будете готові, Live API key. Виберіть Offered methods.

5. Скопіюйте URL вебхука з налаштувань у Vindi (див. Налаштування).

6. Увімкніть Enable / Disable і натисніть Save. Перевірте платіж у режимі sandbox, а потім вимкніть Sandbox mode, щоб приймати реальні платежі.

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

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

Усі налаштування розташовано на сторінці модуля: Modules > Module Manager > VibeFox Vindi Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо валюта магазину не BRL або якщо API-ключ поточного режиму порожній. В обох випадках спосіб оплати не показується на оформленні замовлення. Під час збереження ключі очищуються від зайвих пробілів. Якщо не вибрано жодного способу оплати, вибирається кредитна картка і сторінка показує Choose at least one payment method — credit card was selected. Порожній Title не зберігається: сторінка показує Enter a title for the payment method.

Vindi

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

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

Description: текст під способом оплати на оформленні замовлення. За замовчуванням: Pay by credit card on the secure Vindi page, or by boleto / PIX.

API-ключі

Ключі створюються в панелі Vindi у розділі Settings > API keys: на app.vindi.com.br для робочого середовища та на sandbox-app.vindi.com.br для sandbox. Робоче середовище і sandbox мають окремі адреси та ключі. Кожен платіж запам'ятовує, де створено його рахунок, тож перевірки, скасування та повернення завжди виконуються в цьому середовищі.

Sandbox mode: створює нові платежі в sandbox Vindi, використовуючи sandbox-app.vindi.com.br і sandbox API-ключ. Покупці бачать на оформленні замовлення примітку TEST MODE: Vindi sandbox: no real charges. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі.

Live API key: закритий ключ робочого облікового запису Vindi. Він надсилається лише до API Vindi.

Sandbox API key: закритий ключ облікового запису sandbox Vindi.

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

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

Способи оплати

Offered methods: способи, які покупці можуть обрати. За замовчуванням: кредитна картка. Способи також мають бути увімкнені у вашому обліковому записі Vindi.

Для boleto, PIX і BolePix потрібні CPF або CNPJ покупця, які запитуються на оформленні замовлення.

Повідомлення про оплату (вебхук)

Вебхук повідомляє вашому магазину, що рахунок оплачено, скасовано, відхилено або повернуто. Поле Webhook URL у цьому розділі показує URL. З дружніми URL він має такий вигляд: https://your-shop/module/wcp_vindi_gateway/webhook?token=... і містить секретний токен, створений модулем. Скопіюйте його точно так, як його показують налаштування. У Vindi перейдіть до Settings > Webhooks — в робочому обліковому записі та в обліковому записі sandbox, додайте цей URL і виберіть такі події:

Vindi не підписує свої сповіщення, тому запити з відсутнім або неправильним токеном відхиляються, а кожне сповіщення лише змушує модуль знову зчитати рахунок через API Vindi, перш ніж змінитися замовленню. Без вебхука платіж карткою враховується лише тоді, коли покупець знову оформлює замовлення з тим самим кошиком (тоді оплачений рахунок знаходиться і замовлення створюється), а платіж boleto або PIX — коли покупець знову відкриває сторінку підтвердження замовлення.

Додатково

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

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

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

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

Покупець вибирає спосіб оплати (за замовчуванням Vindi). Коли пропонується більше одного способу, блок оплати показує Pay with і вибір між кредитною карткою, boleto, PIX або BolePix. Коли пропонується boleto, PIX або BolePix, у блоці є також поле CPF or CNPJ. Воно обов'язкове, якщо кредитна картка не пропонується; інакше показується Required for boleto and PIX. Поле заповнюється з Identification number або VAT-номера платіжної адреси, якщо там є дійсний CPF або CNPJ. Номер перевіряється за контрольними цифрами. Якщо чогось бракує, покупець бачить Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. або Please enter your CPF or CNPJ — it is required for boleto and PIX.

Коли покупець підтверджує замовлення, модуль створює для цього кошика клієнта Vindi на основі платіжної адреси та рахунок Vindi на суму кошика в один платіж. У Vindi рахунок називається Order # з номером кошика.

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

Boleto, PIX і BolePix: рахунок виставляється одразу, замовлення створюється зі статусом Awaiting Vindi payment, і покупець потрапляє на сторінку підтвердження замовлення. Там, а також у деталях замовлення в обліковому записі покупця, розділ Payment показує QR-код PIX, код PIX для копіювання з кнопкою Copy code та строк його дії, а також кнопку Open boleto. Лист із підтвердженням замовлення містить код PIX і посилання на boleto. Якщо Vindi не повертає дані boleto або PIX, рахунок скасовується і покупець бачить помилку.

Замовлення позначається оплаченим лише після підтвердження Vindi: модуль зчитує рахунок через API Vindi і перевіряє валюту, належність рахунку кошику (код кошика та клієнт Vindi), а також те, що оплачена сума дорівнює підсумку замовлення. Сторінка підтвердження замовлення повторно перевіряє очікуване замовлення через API, не частіше ніж раз на 15 секунд. Коли платіж отримано, вона показує Your payment with Vindi has been received. Поки рахунок перевіряється у Vindi, вона показує We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. Для скасованого замовлення вона показує This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.

Нова спроба оплати того самого кошика використовує очікуваний рахунок Vindi, якщо спосіб, сума і середовище ті самі. Інакше попередній рахунок скасовується у Vindi перед створенням нового, щоб покупець не міг оплатити той самий кошик двічі. Якщо попередній рахунок тим часом було оплачено, замовлення створюється і новий рахунок не виставляється.

Якщо Vindi не може розпочати платіж, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад: перевірити CPF / CNPJ, платіжну адресу (для boleto обов'язкові вулиця, поштовий індекс, місто та штат), e-mail або телефон, або повідомлення, що Vindi тимчасово недоступний. Технічна причина записується в журнал.

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

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

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

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

No order yet: платіж карткою розпочато, але Vindi його ще не підтвердив. Існує лише кошик.

Awaiting Vindi payment: платіж boleto, PIX або BolePix очікується (примітка Awaiting ... payment at Vindi.). Замовлення переходить у Payment accepted, коли Vindi повідомляє, що рахунок оплачено.

Payment accepted: платіж підтверджено. Він записується з ID рахунку Vindi як ID транзакції, а примітка показує рахунок Vindi, суму та середовище.

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

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

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

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

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

Блок оплати Vindi

На сторінці замовлення показано блок Vindi payment з рахунком і списанням Vindi, середовищем (з позначкою Sandbox для платежів sandbox), способом оплати, статусом, сумою оплати та повернення, історією повернень, усіма Bills of this cart та Vindi notes замовлення.

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

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

Vindi не може повернути платежі boleto. Блок показує Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.

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

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

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

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

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

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

Vindi не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable / Disable увімкнено, валюта кошика BRL, вибрано принаймні один спосіб у Offered methods, і в поточному режимі є API-ключ: Sandbox API key у режимі sandbox, Live API key у робочому режимі. Сторінка налаштувань показує попередження, якщо ключ відсутній або валюта не BRL. У Payment > Preferences перевірте, що модуль дозволений для BRL, для країни покупця та для його групи клієнтів.

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

Вебхук відповідає Forbidden: токен в URL відсутній або неправильний. Скопіюйте URL з налаштувань ще раз.

Вебхук відповідає Verification failed, retry later: рахунок не вдалося зчитати через API Vindi (наприклад, API-ключ цього середовища було видалено), кошик у цей момент оновлював інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Vindi надішле сповіщення повторно. Причину покаже журнал.

URL вебхука у браузері показує Method not allowed: це нормально. URL приймає лише запити від Vindi.

Покупець бачить This payment method is temporarily unavailable: Vindi відхилив API-ключ. Перевірте ключ поточного режиму.

Покупець бачить помилку під час оформлення замовлення: подивіться поле Log на сторінці модуля. Помилки записуються, навіть коли Debug log вимкнено. Для boleto в платіжній адресі мають бути вулиця, поштовий індекс, місто та штат.

Замовлення має статус Vindi payment on hold: прочитайте примітки в блоці Vindi payment (див. Статуси замовлення), а потім завершіть замовлення або поверніть платіж.

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

Повернення не виконується: прочитайте повідомлення. Платежі boleto не можна повернути через Vindi, а API-ключ середовища платежу має бути заданий.

Видалення

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

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