VibeFox Braintree for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。

PHP：8.0 或更高版本。

HTTPS：您的网站应使用 HTTPS。

Braintree 账户：您需要 Braintree 账户的 Merchant ID、Public Key 和 Private Key。它们位于 Braintree 控制面板（测试环境：sandbox.braintreegateway.com，正式环境：www.braintreegateway.com）中，路径为齿轮图标 > API > API Keys。测试环境和正式环境账户的密钥各不相同。除非您将 3-D Secure 设为 Disabled，否则必须为您的 Braintree 商户账户启用 3-D Secure。无需 Webhook。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_braintree_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Braintree > Manage，或在插件列表页点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 将 Braintree 控制面板中的 Merchant ID、Public Key 和 Private Key 分别填入测试环境或正式环境的字段。

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 控制面板（测试环境或正式环境），点击齿轮图标，然后点击 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 以商户账户的币种扣款。留空则使用默认商户账户；可输入一个 ID（例如 mystore_EUR），或每个币种一个：EUR=mystore_EUR, USD=mystore_USD。若扣款币种与订单币种不一致，交易会被自动撤销，顾客不会被扣款。

付款

Transaction type: 银行卡的扣款方式。

3-D Secure: 在欧洲经济区（EEA）和英国，大多数银行卡付款都必须进行 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 时，顾客在下单时需完成发卡行的验证。

插件通过 Braintree API 使用一次性令牌扣款，金额为订单总额（以订单币种计），并以订单号作为订单 ID。只有在根据 Braintree 经身份验证的响应确认，且扣款金额和币种与订单核对一致后，订单才会标记为已付款。付款获批后，顾客将被转到订单已接收页面。银行卡付款不需要 Webhook：结果立即可知。

若付款失败，订单将保持为待付款，失败原因会添加到订单备注中，顾客会看到明确提示，例如 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 页面。兼容 WooCommerce 高性能订单存储（HPOS）。

本插件仅接受银行卡付款。不支持保存银行卡（vaulting）、WooCommerce 订阅或预购、PayPal、Venmo、Apple Pay、Google Pay、ACH 或本地付款方式，不使用 Braintree Webhook，也不支持 Level 2/3 数据、订单明细或 Fastlane。

订单与退款

订单状态

Pending payment: 尚未完成付款或付款被拒绝。

Processing or Completed: 银行卡已扣款（Sale），或已对授权进行扣款。WooCommerce 会将订单设为处理中；仅包含可下载虚拟商品的订单则设为已完成。订单备注会显示金额、交易 ID 和 3-D Secure 结果。交易 ID 即 Braintree 交易 ID，在订单页面中会链接到 Braintree 控制面板中的该交易。

On hold: 资金仅为授权状态（Authorize only）。当 Braintree 返回意外的交易状态，或无法自动撤销币种错误的扣款时，订单也会被设为保留。订单备注会说明应在 Braintree 控制面板中核对什么。

Cancelled: 授权已通过 Void Braintree authorization 撤销。

扣款与撤销

对于已授权的订单，打开订单并在订单操作中选择 Capture Braintree payment 或 Void Braintree authorization，然后点击更新按钮。扣款会将订单标记为已付款；撤销会取消订单，并将冻结金额释放回顾客的银行卡。若操作失败，错误会显示在订单页面并添加到订单备注中。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Credit / debit card（按钮文字使用您的付款方式名称）。支持全额和部分退款。Braintree 仅能退还已结算的交易，通常在 24 小时内结算。结算前的全额退款会以撤销方式处理；此时部分退款会失败，并提示等待结算。退款会发送至订单付款时所在的环境（测试环境或正式环境）。若 Braintree 未接受退款，WooCommerce 会显示错误，且不会记录退款。退款或撤销成功后，会添加到订单备注中。

争议（拒付）和结算拒付不会同步到 WooCommerce。请在 Braintree 控制面板中查看。

许可证密钥

本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 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)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：扣款、撤销和退款仍可正常使用。

许可证到期后，插件仍可继续使用，但更新和支持需要续费。系统会在后台自动重新检查状态。

故障排除

结账时未显示 Braintree：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否已填写 Merchant ID、Public Key 和 Private Key。若缺少密钥，设置页面会显示警告。

付款已完成，但订单仍为待付款：银行卡付款会立即确认，不依赖 Webhook。若订单备注提示 Braintree 的响应丢失，请在接受另一笔付款之前，先在 Braintree 控制面板中查找该订单号对应的交易。请开启 Debug log，并在 WooCommerce > Status > Logs 中查看来源为 wcp_braintree_gateway 的日志。

银行卡表单显示 Could not initialize payment form：所选模式的密钥有误，或该账户中不存在所填的商户账户 ID。请检查密钥和商户账户 ID，然后重新加载页面。

所有付款的 3-D Secure 验证均失败：必须为您的 Braintree 商户账户启用 3-D Secure。请联系 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 无关联，也未获得 Braintree 认可。