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

Вимоги

WordPress: 6.0 або новіша.

WooCommerce: 8.0 або новіша, встановлений і активний.

PHP: 8.0 або новіша.

HTTPS: ваш сайт має працювати через HTTPS.

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку wcp_braintree_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Braintree > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії у верхній частині сторінки та натисніть Activate.

5. Скопіюйте Merchant ID, Public Key і Private Key з Braintree Control Panel у поля для sandbox або робочого режиму.

6. Увімкніть Enable/Disable. Залиште Sandbox mode увімкненим і оформіть тестове замовлення тестовою карткою Braintree, наприклад 4111 1111 1111 1111 з будь-якою майбутньою датою закінчення. Для 3-D Secure використовуйте тестові картки 3-D Secure від Braintree.

7. Зніміть позначку з Sandbox mode, щоб приймати справжні платежі за робочими обліковими даними.

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

Усі параметри розміщено на одній сторінці: WooCommerce > Settings > Payments > Braintree. Якщо шлюз увімкнено, але не заповнено Merchant ID, Public Key або Private Key вибраного режиму, сторінка попереджає, що спосіб оплати приховано на оформленні замовлення, доки ці поля не буде заповнено. Сторінка показує лише поля облікових даних вибраного режиму; обидва набори залишаються збереженими.

Загальні

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

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

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

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

Увійдіть до Braintree Control Panel (тестового або робочого середовища), натисніть значок шестерні, далі API і API Keys. Там показано публічний і приватний ключі, а Merchant ID — на тій самій сторінці.

Sandbox mode: Use the Braintree sandbox (test payments, no real money). За замовчуванням: увімкнено. Зніміть позначку, щоб приймати справжні платежі за робочими обліковими даними. Повернення, захоплення та анулювання завжди використовують середовище, в якому було оплачено замовлення.

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

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

Sandbox Private Key і Live Private Key: приватний ключ цього облікового запису.

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

Оплата

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

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

Додатково

Debug log: Also log API calls and payment steps (errors are always logged). Журнали доступні в WooCommerce > Status > Logs, джерело wcp_braintree_gateway. Вони ніколи не містять ключів API, даних картки чи покупця. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. За замовчуванням: вимкнено.

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

Покупець обирає спосіб оплати (за замовчуванням Credit / debit card) і вводить картку у формі Braintree на сторінці оформлення замовлення. У режимі sandbox форма показує SANDBOX / TEST MODE — no real money is charged. Коли 3-D Secure увімкнено, покупець проходить перевірку банку під час оформлення замовлення.

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

Якщо платіж не проходить, замовлення залишається в статусі Очікує оплати, причина додається до приміток замовлення, а покупець бачить зрозуміле повідомлення, наприклад 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.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

Плагін приймає лише оплату картками. Він не має збережених карток (vaulting), підтримки WooCommerce Subscriptions чи попередніх замовлень, PayPal, Venmo, Apple Pay, Google Pay, ACH або локальних способів оплати, вебхуків Braintree, а також даних Level 2/3, позицій замовлення (line items) та Fastlane.

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

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

Pending payment: платіж ще не проведено або його відхилено.

Processing or Completed: картку списано (Sale) або авторизацію захоплено. WooCommerce встановлює статус «Обробляється» або «Виконано» для замовлень лише з віртуальними товарами для завантаження. Примітка до замовлення показує суму, ID транзакції та результат 3-D Secure. ID транзакції — це ID транзакції Braintree, і на екрані замовлення він є посиланням на транзакцію в Braintree Control Panel.

On hold: кошти лише авторизовано (Authorize only). Замовлення також переходить у статус «На утриманні», коли Braintree повертає неочікуваний статус транзакції або коли списання у неправильній валюті не вдалося анулювати автоматично. Примітка до замовлення пояснює, що перевірити в Braintree Control Panel.

Cancelled: авторизацію анульовано через Void Braintree authorization.

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

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

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Credit / debit card (назва кнопки береться з назви вашого способу оплати). Підтримуються повне та часткове повернення коштів. Braintree може повертати кошти лише за розрахованими транзакціями, які зазвичай розраховуються протягом 24 годин. До розрахунку повне повернення виконується як анулювання; часткове повернення в цьому випадку не вдається з повідомленням дочекатися розрахунку. Повернення надсилається в те середовище (sandbox або робоче), в якому було оплачено замовлення. Якщо Braintree не приймає повернення, WooCommerce показує помилку, і повернення не записується. Успішне повернення або анулювання додається до приміток замовлення.

Оскарження платежів (chargebacks) та відмови при розрахунках не синхронізуються з WooCommerce. Перевіряйте їх у Braintree Control Panel.

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розміщено у верхній частині WooCommerce > Settings > Payments > Braintree. Вставте ключ у License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Використовуйте Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис на vibefox.net.

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

Без активного ключа Braintree не показується покупцям під час оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Менеджери магазину, які ввійшли в систему, як і раніше бачать спосіб оплати з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати та протестувати плагін до купівлі ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Існуючі замовлення не змінюються: захоплення, анулювання та повернення коштів працюють.

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

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

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

Платіж пройшов, але замовлення залишається Pending payment: карткові платежі підтверджуються одразу, без вебхука. Якщо в примітці до замовлення сказано, що відповідь від Braintree втрачено, перевірте в Braintree Control Panel транзакцію з номером цього замовлення, перш ніж приймати інший платіж. Увімкніть Debug log і перегляньте WooCommerce > Status > Logs, джерело wcp_braintree_gateway.

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

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

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

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу та журнали видаляються лише тоді, коли було увімкнено Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Дані Braintree, збережені в замовленнях, завжди зберігаються, оскільки вони потрібні для повернень після повторного встановлення. Існуючі замовлення зберігають свої примітки про оплату та ID транзакцій.

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