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. Там перечислены публичный и приватный ключи, а 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: публичный ключ этой учётной записи.

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

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

Удаление

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

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