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.braintreegateway.com, рабочая среда: www.braintreegateway.com) в разделе со значком шестерёнки: API, API Keys. У тестовой и рабочей учётных записей ключи разные. 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 в поля для тестовой или рабочей среды.

5. Включите Enable/Disable и нажмите Save. Оставьте включённым Sandbox mode и оформите тестовый заказ с тестовой картой песочницы 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. Страница настроек и её поля одинаковы в обеих версиях.

Новая установка стартует с выключенным способом оплаты и включённым режимом песочницы.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Если способ оплаты включён, но не заполнены Merchant ID, Public Key или Private Key выбранной среды, страница предупреждает, что способ оплаты скрыт при оформлении заказа, пока эти поля не заполнены. Пока режим песочницы включён, страница показывает 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 (тестовая или рабочая среда, ссылки в этом разделе), нажмите значок шестерёнки, затем API и API Keys. Там перечислены публичный и приватный ключи, а Merchant ID показан на той же странице. Страница показывает только поля учётных данных выбранной среды; оба набора остаются сохранёнными.

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

Sandbox Merchant ID и Live Merchant ID: Merchant ID тестовой или рабочей учётной записи.

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 на сумму заказа в валюте заказа; в Braintree в качестве ID заказа указывается номер заказа 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 часов. До расчёта полный возврат выполняется как отмена; частичный возврат в этом случае завершается ошибкой с сообщением подождать расчёта. Возврат отправляется в ту среду (тестовую или рабочую), в которой был совершён платёж, поэтому учётные данные этой среды должны быть заданы. Если Braintree не принимает возврат, вкладка показывает ошибку, и возврат не регистрируется. Успешный возврат добавляется в историю возвратов и примечания. Полный возврат устанавливает заказу Refunded Status; частичный возврат статус не меняет. Изменения статуса на вкладке не уведомляют покупателя и не возвращают товары на склад, как и при ручном изменении статуса.

Возвраты товаров в Sales > Returns деньги через Braintree не возвращают. Споры по платежам (чарджбэки), отказы при расчёте и возвраты, выполненные в 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 часов. Верните полную сумму, чтобы отменить транзакцию сейчас, или выполните частичный возврат после расчёта.

На вкладке нет кнопок или сообщение о среде: у вашей группы пользователей нет права изменять расширение, либо платёж был совершён в тестовой или рабочей среде, а учётные данные этой среды не заданы. Введите их и повторите попытку.

Удаление

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

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

Braintree — товарный знак его владельца. Это расширение не связано с Braintree и не одобрено компанией Braintree.