VibeFox Braintree for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块会拒绝安装在较旧的 PHP 版本上。

Braintree 账户：您需要 Braintree 账户的 Merchant ID、Public Key 和 Private Key。它们位于 Braintree Control Panel（沙盒：sandbox.braintreegateway.com，正式：www.braintreegateway.com）中，路径为齿轮图标、API、API Keys。沙盒和正式账户的密钥不同。除非您将 3-D Secure 设为 Disabled，否则必须为您的 Braintree 商户账户启用 3-D Secure。无需 Webhook：银行卡付款会立即确认。

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Braintree Gateway，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key，然后点击 Activate（参见“许可证密钥”）。

4. 将 Braintree Control Panel 中的 Merchant ID、Public Key 和 Private Key 复制到沙盒或正式环境的对应字段中。

5. 开启 Enable/Disable 并点击 Save。保持 Sandbox mode 开启，使用 Braintree 沙盒测试卡下一个测试订单。然后关闭 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 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（沙盒或正式），点击齿轮图标，然后点击 API 和 API Keys。Public Key 和 Private Key 都列在那里，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：该账户的 Public Key。

Sandbox Private Key 和 Live Private Key：该账户的 Private Key。已保存的 Private Key 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Sandbox merchant account ID(s) 和 Live merchant account ID(s)：可选。Braintree 按商户账户的币种扣款。留空则使用默认商户账户；可以输入一个 ID（例如 mystore_EUR），也可以按币种输入多个：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（强客户认证）对大多数银行卡付款是强制性的。您的 Braintree 账户也必须启用它（如果付款因 3-D Secure 配置错误而失败，请联系 Braintree 支持）。

在扣除银行卡之前，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 时，顾客在下单时完成发卡行的验证；购物车总额、电子邮件和账单地址会传递给该验证。

随后，模块会通过 Braintree API，以购物车币种按购物车总额扣款该一次性令牌，并将购物车编号用作 Braintree 中的订单 ID。在此之前不存在订单。扣款金额和币种会与购物车进行核对。只有在 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 Webhook。

订单与退款

订单状态

尚无订单：付款未完成或被拒绝。只存在购物车。

Payment accepted：银行卡已扣款（Sale），或授权已被扣款。付款会以 Braintree 交易 ID 记录，订单消息中的私人备注会显示金额、交易 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 小时内完成。结算之前，全额退款会以撤销方式处理；此时部分退款会失败，并提示需要等待结算。退款会发送到付款所在的环境（沙盒或正式），因此必须设置该环境的凭据。如果 Braintree 未接受退款，该区块会显示错误，且不会记录任何退款。成功的退款会添加到退款历史和备注中。全额退款会将订单设为 Refunded；部分退款不会改变订单状态。

模块不会创建退款凭证（credit slips）。PrestaShop 订单页面的标准退款按钮不会通过 Braintree 退回资金。争议（拒付）、结算拒付以及在 Braintree Control Panel 中进行的退款，都不会同步到 PrestaShop。

许可证密钥

该模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。位于 Modules > Module Manager > VibeFox Braintree Gateway > Configure 页面顶部、设置上方的第一个区块是许可证区块 License — VibeFox Braintree Gateway。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏部分字符的形式显示密钥，并显示状态（例如许可证有效期至的日期以及您的域名），还有以下按钮：Check now（再次检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺中移除该密钥）。其下方是 Product: presta-payment-braintree 这一行，以及用于打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字遵循后台语言（包括英语和俄语）。

如果密钥未被接受，区块会说明原因，例如 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 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时对其进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会被确认，扣款、撤销和退款也可以正常进行。

许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时没有显示 Braintree：检查许可证是否有效、Enable/Disable 是否已开启，以及所选环境是否具有 Merchant ID、Public Key 和 Private Key。缺少密钥时，设置页面会显示警告。在 Payment > Preferences 中，检查该模块是否允许用于购物车币种、顾客所在国家和顾客群组。

银行卡已扣款，但没有创建订单：银行卡付款会立即确认，不依赖 Webhook。请查看模块页面上的 Log 字段。如果日志显示未收到 Braintree 的响应，请在接受其他付款之前，先在 Braintree Control Panel 中检查是否存在以购物车编号作为订单 ID 的交易。如果扣款后未能创建订单，同一购物车的下一次付款尝试会在不再次扣款的情况下创建订单。

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

所有付款的 3-D Secure 都失败：必须为您的 Braintree 商户账户启用 3-D Secure。请联系 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 的认可。