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

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

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. Там перечислены открытый (public) и закрытый (private) ключи, а 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 списывает деньги в валюте учётной записи мерчанта. Оставьте поле пустым, чтобы использовать учётную запись мерчанта по умолчанию, укажите один ID (например, mystore_EUR) или по одному ID на каждую валюту: EUR=mystore_EUR, USD=mystore_USD. Если валюта списания не совпадает с валютой заказа, транзакция автоматически отменяется, и покупатель не платит.

Оплата

Transaction type: как списываются деньги с карты.

3-D Secure: 3-D Secure 2 (сильная аутентификация клиента, SCA) обязательна для большинства платежей картами в ЕЭЗ и Великобритании. Она также должна быть включена для вашей учётной записи 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 / 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.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с High-Performance Order Storage (HPOS) WooCommerce.

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

Заказы и возвраты

Статусы заказа

Pending payment: платёж ещё не произведён или был отклонён.

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

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

Оплата прошла, но заказ остаётся в статусе Ожидание оплаты: платежи картами подтверждаются сразу, без вебхука. Если в примечании к заказу сказано, что ответ от Braintree потерян, проверьте в Braintree Control Panel транзакцию с этим номером заказа, прежде чем принимать очередной платёж. Включите Debug log и посмотрите в WooCommerce > Status > Logs, источник wcp_braintree_gateway.

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

3-D Secure не работает для каждого платежа: 3-D Secure должен быть включён для вашей учётной записи мерчанта Braintree. Обратитесь в поддержку Braintree или установите 3-D Secure в значение Disabled (не рекомендуется в ЕЭЗ и Великобритании, где SCA обязательна).

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

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

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

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина всегда удаляются. Настройки платёжного шлюза и журналы удаляются, только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Данные Braintree, сохранённые в заказах, всегда остаются, потому что они нужны для возвратов после повторной установки. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

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