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

Вимоги

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

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

Обліковий запис Braintree: вам потрібні Merchant ID, Public Key і Private Key вашого облікового запису Braintree. Їх можна знайти в Braintree Control Panel (sandbox: sandbox.braintreegateway.com, live: www.braintreegateway.com) під значком шестерні, API, API Keys. В облікових записів sandbox і live різні ключі. 3-D Secure має бути увімкнено для вашого облікового запису мерчанта Braintree, якщо тільки ви не встановили 3-D Secure у значення Disabled. Вебхук не потрібен: платежі картками підтверджуються одразу.

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

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

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

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

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

4. Скопіюйте Merchant ID, Public Key і Private Key з Braintree Control Panel у поля sandbox або live.

5. Увімкніть Enable/Disable і натисніть Save. Залиште Sandbox mode увімкненим і зробіть тестове замовлення тестовою карткою Braintree sandbox. Потім вимкніть Sandbox mode, щоб приймати реальні платежі з робочими обліковими даними.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Braintree Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Якщо спосіб оплати увімкнено, але Merchant ID, Public Key або Private Key обраного середовища не заповнено, сторінка попереджає, що спосіб оплати приховано на оформленні замовлення, доки їх не буде заповнено. Поки увімкнено режим sandbox, сторінка показує Sandbox mode is on: test payments, no real money.

Braintree

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

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

Description: текст, який відображається під способом оплати на оформленні замовлення. За замовчуванням: Pay securely with your credit or debit card via Braintree.

Облікові дані API

Увійдіть до Braintree Control Panel (sandbox або live), натисніть значок шестерні, а потім API і API Keys. Там перелічено Public Key і Private Key, а Merchant ID показано на тій самій сторінці. Сторінка показує лише поля облікових даних обраного середовища; обидва набори залишаються збереженими.

Sandbox mode: використовує тестове середовище Braintree (тестові платежі, без реальних грошей). За замовчуванням: on. Вимкніть, щоб приймати реальні платежі з робочими обліковими даними. Повернення, захоплення та анулювання завжди використовують те середовище, в якому було оплачено замовлення. Поки режим увімкнено, покупці бачать SANDBOX / TEST MODE — no real money is charged. під способом оплати.

Sandbox Merchant ID і Live Merchant ID: Merchant ID тестового або робочого облікового запису.

Sandbox Public Key і Live Public Key: Public Key цього облікового запису.

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

Sandbox merchant account ID(s) і Live merchant account ID(s): необов'язково. Braintree списує кошти у валюті облікового запису мерчанта. Залиште поле порожнім, щоб використовувати обліковий запис мерчанта за замовчуванням, або введіть один ID (наприклад mystore_EUR) чи по одному ID на кожну валюту: EUR=mystore_EUR, USD=mystore_USD. Якщо списана валюта не збігається з валютою замовлення, транзакція автоматично анулюється, і з покупця кошти не стягуються.

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

Оплата

Transaction type: як саме списуються кошти з картки.

3-D Secure: 3-D Secure 2 (Strong Customer Authentication) є обов'язковим для більшості платежів картками в ЄЕЗ та Великій Британії. Його також має бути увімкнено для вашого облікового запису Braintree (зверніться до служби підтримки Braintree, якщо платежі не проходять через помилку конфігурації 3-D Secure).

Результат 3-D Secure перевіряється на сервері, а не лише в браузері, до списання з картки.

Додатково

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Credit / debit card) і вводить картку у формі Braintree всередині варіанта оплати. Форма завантажується з Braintree лише на сторінці оформлення замовлення і використовує мову магазину. Коли 3-D Secure увімкнено, покупець проходить перевірку у банку під час оформлення замовлення; до неї передаються сума кошика, e-mail і платіжна адреса.

Далі модуль списує одноразовий токен через API Braintree на суму кошика у валюті кошика, використовуючи номер кошика як ID замовлення в Braintree. До цього моменту замовлення не існує. Сума та валюта списання перевіряються відносно кошика. Замовлення створюється лише після того, як Braintree прийме платіж, і покупець бачить стандартну сторінку підтвердження замовлення PrestaShop.

Якщо платіж не пройшов, замовлення не створюється, причина записується в журнал модуля, а покупець залишається на етапі оплати з повідомленням, наприклад Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. або The card security code or billing address could not be verified. Please check your details and try again. Покупець може одразу спробувати знову. Якщо валюта або сума списання не збігаються з кошиком, транзакція анулюється, і покупець бачить This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us.

Кошик ніколи не списується двічі. Повторне надсилання, поки платіж виконується, показує This order is already being paid. Please wait a moment and check your e-mail before trying again. Якщо картку було списано, але PrestaShop не зміг створити замовлення, покупець бачить Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Наступна спроба для того самого кошика створює замовлення зі збереженої транзакції без повторного списання.

Модуль приймає лише оплату картками. Він не підтримує збережені картки, підписки чи регулярні платежі, PayPal, Venmo, Apple Pay, Google Pay або локальні способи оплати, а також не використовує вебхуки Braintree.

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

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

Замовлення ще немає: оплату не було здійснено або її відхилено. Існує лише кошик.

Payment accepted: картку було списано (Sale), або авторизацію захоплено. Платіж записується з ID транзакції Braintree, а приватна примітка в повідомленнях замовлення показує суму, ID транзакції та результат 3-D Secure.

Braintree payment authorized: кошти лише авторизовано (Authorize only). Жоден платіж не записується, доки ви його не захопите.

Braintree payment on hold: Braintree повернув неочікуваний статус транзакції, або списання у невірній валюті чи на невірну суму не вдалося автоматично анулювати. Примітка пояснює, що перевірити в Braintree Control Panel.

Canceled: авторизацію було анульовано.

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

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

Блок Braintree payment

Сторінка замовлення показує блок Braintree payment з ID транзакції (посилання на транзакцію в Braintree Control Panel відповідного середовища), статусом транзакції, сумою та обліковим записом мерчанта, результатом 3-D Secure, списаною та поверненою сумою, позначкою Sandbox для тестових платежів і історією повернень. Кнопки блока потребують права редагувати замовлення; доступ до сторінок Modules не потрібен.

Захоплення та анулювання

Для замовлення зі статусом Braintree payment authorized натисніть Capture Braintree payment, щоб списати суму замовлення, або Void Braintree authorization, щоб звільнити утриману суму. Захоплення переводить замовлення в статус Payment accepted і записує платіж; анулювання переводить його в статус Canceled. Якщо дія не вдалася, помилка показується в блоці та додається до приміток замовлення.

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

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

Модуль не створює кредитні ноти (credit slips). Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Braintree. Оскарження платежів (chargebacks), відмови при розрахунках і повернення, зроблені в Braintree Control Panel, не синхронізуються з PrestaShop.

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

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

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

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

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

Braintree не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і в обраному середовищі заповнено Merchant ID, Public Key і Private Key. Сторінка налаштувань показує попередження, якщо якогось ключа бракує. У Payment > Preferences перевірте, чи дозволено модуль для валюти кошика, країни покупця та групи покупця.

Картку списано, але замовлення не створено: платежі картками підтверджуються одразу, без вебхука. Перегляньте поле Log на сторінці модуля. Якщо журнал повідомляє, що відповідь Braintree втрачено, перевірте в Braintree Control Panel, чи є транзакція з номером кошика як ID замовлення, перш ніж приймати інший платіж. Якщо замовлення не вдалося створити після списання, наступна спроба оплати для того самого кошика створить його без повторного списання.

Форма картки показує Could not initialize payment form: ключі обраного середовища неправильні або ID облікового запису мерчанта не існує в цьому обліковому записі. Перевірте ключі та ID облікових записів мерчанта, а потім перезавантажте сторінку.

3-D Secure не працює для жодного платежу: 3-D Secure має бути увімкнено для вашого облікового запису мерчанта Braintree. Зверніться до служби підтримки Braintree або встановіть 3-D Secure у значення Disabled (не рекомендується в ЄЕЗ та Великій Британії, де SCA є обов'язковою).

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

Покупець бачить повідомлення The order total must be greater than zero to pay by card: сума кошика дорівнює нулю, наприклад після застосування купона. Такі замовлення не можна оплатити карткою.

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

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

Видалення

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

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