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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша версія.

Обліковий запис 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. Один ключ працює для одного домену.

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

Архів для завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп’ютері. Він містить README.txt, пакет для OpenCart 3 wcp_braintree_gateway-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_braintree_gateway.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_braintree_gateway-oc3-(version).ocmod.zip. Розширення не має модифікацій OCMOD, тож оновлювати Extensions > Modifications не потрібно. Замість інсталятора ви також можете скопіювати вміст папки upload з цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions, оберіть тип Payments, знайдіть VibeFox Braintree Gateway і натисніть Install (зелена кнопка +). Вашому користувачу-адміністратору потрібне право змінювати список розширень оплати.

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

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

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

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_braintree_gateway.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з’являється у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Braintree Gateway, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і облікові дані Braintree та перевірте платіж так само, як у кроках з 3 до 5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Нове встановлення починає роботу з вимкненим способом оплати та увімкненим режимом sandbox.

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

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

Під час збереження поле Title має містити від 1 до 128 символів, Sort Order має бути цілим числом, а Total — числом 0 або більше. Якщо в якомусь полі помилка, нічого не зберігається, і сторінка вказує на це поле.

Braintree

Enable/Disable: вмикає або вимикає оплату картками Braintree. Спосіб оплати приховано на етапі оформлення замовлення, доки не заповнені Merchant ID, Public Key і Private Key вибраного середовища. За замовчуванням: вимкнено.

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

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

Sort Order: позиція Braintree серед способів оплати на етапі оформлення замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати Braintree лише для платіжних адрес у вибраній географічній зоні. За замовчуванням: All zones. Географічні зони налаштовуються в System > Localisation > Geo Zones.

Total: сума замовлення у валюті магазину за замовчуванням, якої має досягти замовлення, щоб було запропоновано Braintree. Залиште поле порожнім, щоб пропонувати Braintree за будь-якої суми.

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

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

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

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

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

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

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

Оплата

Transaction type: спосіб списання коштів з картки.

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

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

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Статус воно отримує лише після того, як Braintree прийняв платіж карткою. Відхилена картка залишає замовлення без статусу, а покупець залишається на кроці підтвердження. Кожне поле нижче перелічує статуси замовлень вашого OpenCart.

Order Status After Payment: продаж списано або авторизацію захоплено на вкладці замовлення. За замовчуванням: Обробляється.

Authorized Status: лише авторизація: сума зарезервована, але ще не оплачена. За замовчуванням: Очікує оплати, оскільки в OpenCart немає статусу На утриманні; примітка до замовлення та вкладка замовлення це пояснюють. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

On Hold (Review) Status: Braintree повернув неочікуваний статус транзакції, або списана сума чи валюта не збіглися, і автоматичне анулювання не вдалося. Примітка пояснює, що перевірити. За замовчуванням: Очікує оплати.

Voided Status: авторизацію анульовано на вкладці замовлення, і утримувана сума звільняється. За замовчуванням: Скасовано.

Refunded Status: платіж повністю повернено або анульовано як повне повернення до розрахунку. Часткові повернення лише додають примітку. За замовчуванням: Повернено.

Додатково

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

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

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

Імпорт / експорт

Export: Download JSON зберігає налаштування у файл JSON. Приватні ключі не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені приватні ключі зберігаються.

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Credit / debit card). На кроці Confirm Order покупець бачить ваш опис і форму картки Braintree, яку завантажує Braintree мовою вітрини. OpenCart створює замовлення на цьому кроці, все ще без статусу. Коли покупець натискає Confirm Order, форма перевіряє картку, а за увімкненого 3-D Secure покупець проходить перевірку у своєму банку; до форми передаються сума замовлення, e-mail і платіжна адреса. До вашого магазину доходить лише одноразовий токен. В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose в блоці способу оплати, у вікні Payment method options. Форма картки тоді з’являється в блоці підтвердження внизу сторінки оформлення замовлення, над кнопкою Confirm Order. Якщо магазин не запитує платіжну адресу (типова поведінка OpenCart 4), перевірка 3-D Secure використовує адресу доставки.

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

Якщо платіж не вдався, замовлення залишається без статусу, до нього додається примітка з причиною, і покупець залишається на кроці Confirm Order з повідомленням, наприклад 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. Повторне підтвердження вже оплаченого замовлення одразу веде на сторінку успіху; для авторизованого платежу показується A payment for this order has already been received and is awaiting review. Якщо картку списано, але OpenCart не зміг встановити статус замовлення, покупець бачить Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Наступна спроба з тим самим кошиком встановлює статус цього замовлення за збереженою транзакцією, без повторного списання. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order, тому в одного кошика може бути кілька замовлень (OpenCart 4 зберігає одне замовлення для оформлення і оновлює його, тож після відхиленої картки покупець сплачує те саме замовлення): щойно одне з них оплачено, інше замовлення того самого кошика не списується, і покупець бачить This cart has already been paid with order #…. Please check your order history — do not pay again.

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

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

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

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

Немає статусу (відсутнє замовлення): платіж не здійснено або його відхилено. У Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

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

Authorized Status (за замовчуванням Pending): кошти лише авторизовано (Authorize only). Примітка просить захопити платіж на сторінці замовлення перед відправленням.

On Hold (Review) Status (за замовчуванням Pending): Braintree повернув неочікуваний статус транзакції, або списання в неправильній валюті чи на неправильну суму не вдалося автоматично анулювати. Примітка пояснює, що перевірити в Braintree Control Panel.

Voided Status (за замовчуванням Canceled): авторизацію було анульовано.

Refunded Status (за замовчуванням Refunded): платіж повністю повернено через розширення.

Примітки — це записи в History замовлення, які покупець не бачить.

Вкладка VibeFox Braintree Gateway

У Sales > Orders відкрийте замовлення, оплачене через Braintree. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox Braintree Gateway показує Transaction ID (з посиланням на транзакцію в Braintree Control Panel відповідного середовища), позначку Sandbox для тестових платежів, Status транзакції, Amount і обліковий запис мерчанта, результат 3-D Secure, суми Charged / refunded, кнопки захоплення, анулювання та повернення, історію повернень і Braintree notes замовлення. Вкладка показується користувачам, які мають доступ до розширення; для кнопок потрібне право його змінювати (задається в System > Users > User Groups).

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

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

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

На вкладці VibeFox Braintree Gateway введіть Amount (підставляється сума, яку ще не повернуто), за бажанням Reason (optional), і натисніть Refund via Braintree. Підтвердьте запитання Повернути цю суму через Braintree? Цю дію неможливо скасувати. Підтримуються повне та часткове повернення як для захопленого платежу, так і для платежу на перевірці. Повернення виконуються в тій сумі та валюті, які списав Braintree. Braintree повертає кошти лише за розрахованими транзакціями, зазвичай протягом 24 годин. До розрахунку повне повернення виконується як анулювання; часткове повернення в цьому разі завершується помилкою з повідомленням почекати на розрахунок. Повернення надсилається в те середовище (sandbox або робоче), у якому був здійснений платіж, тому облікові дані цього середовища мають бути вказані. Якщо Braintree не приймає повернення, вкладка показує помилку, і повернення не реєструється. Успішне повернення додається до історії повернень і приміток. Повне повернення встановлює замовленню Refunded Status; часткове повернення статус не змінює. Зміни статусу з вкладки не сповіщають покупця і не повертають товари на склад, як і при ручній зміні статусу.

Повернення товарів у Sales > Returns не повертають гроші через Braintree. Оскарження платежів (chargebacks), відмови при розрахунках і повернення, виконані в Braintree Control Panel, не синхронізуються з OpenCart.

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

Розширення працює з ліцензійним ключем VibeFox, отриманим на vibefox.net. Блок ліцензії License — VibeFox Braintree Gateway — це перший блок на сторінці Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: opencart-payment-braintree і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Лише користувачі-адміністратори з правом Modify на розширення можуть змінити ключ. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

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

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

Без активного ключа Braintree не показується покупцям на етапі оформлення замовлення. Якщо платіж все одно ініційовано, покупець бачить This payment method is not available. Please choose another one. Адміністратор, який увійшов в адмін-панель у тому самому браузері, усе ще бачить спосіб оплати в магазині, позначений (unlicensed — visible to admins only), щоб ви могли налаштувати й протестувати розширення до купівлі ключа. В OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тож без активного ключа спосіб оплати приховано для всіх. Після одноразового відкриття сторінки Edit на Dashboard адмін-панелі з'являється нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються: вже ініційовані платежі все одно підтверджуються, а захоплення, анулювання та повернення працюють.

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

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

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

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

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

Покупець бачить Your session has expired. Please refresh the page and try again.: сесія оформлення змінилася, поки форма була відкрита. Покупець має перезавантажити сторінку оформлення замовлення.

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 чи робочому, а облікові дані цього середовища не вказано. Введіть їх і повторіть спробу.

Видалення

Перейдіть до Extensions > Extensions, оберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox Braintree Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total та статуси замовлень із розділу Orders, які при повторному встановленні повертаються до значень за замовчуванням. Якщо Delete data on uninstall увімкнено, видаляються решта налаштувань шлюзу (назва, опис, режим sandbox, облікові дані, облікові записи мерчанта, тип транзакції, 3-D Secure, журнал налагодження) і журнал. Якщо вимкнено, вони зберігаються для наступного повторного встановлення. Транзакції та повернення Braintree завжди зберігаються, тож замовлення, оплачені раніше, можна повернути, захопити або анулювати й після повторного встановлення. Наявні замовлення зберігають свої примітки про платежі.

В OpenCart 4, щоб видалити також файли розширення, після цього перейдіть до Extensions > Installer і натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox Braintree Gateway у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

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