VibeFox Braintree for OpenCart — 帮助

要求

OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP: 8.0 或更高版本。

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

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. 将 Braintree Control Panel 中的 Merchant ID、Public Key 和 Private Key 复制到沙盒或正式环境的字段中。

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. 请按照 OpenCart 3 步骤 3 至 5 输入许可证密钥和 Braintree 凭据并测试付款。两个版本的设置页面及其字段完全相同。

新安装时，支付方式默认关闭，沙盒模式默认开启。

配置

所有设置都位于扩展页面：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: 在 EEA 和英国，3-D Secure 2（强客户认证，SCA）是大多数银行卡付款的强制要求。您的 Braintree 账户也必须启用它（如果付款因 3-D Secure 配置错误而失败，请联系 Braintree 支持）。

在银行卡被扣款之前，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 调用和付款步骤记录到 OpenCart 日志文件夹（storage/logs）中的 wc_btg_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误也始终会被记录。日志绝不包含 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，顾客需要完成其银行的验证。订单总额、邮箱和账单地址会传递给表单。只有一次性令牌会到达您的店铺。在 OpenCart 4 中，顾客通过支付方式区块中的 Choose 按钮，在 Payment method options 窗口中选择支付方式。此时银行卡表单会出现在结账页面底部的确认区块中，位于 Confirm Order 按钮上方。如果店铺不要求付款地址（OpenCart 4 默认设置），3-D Secure 验证会改用配送地址。

随后，扩展会通过 Braintree API 以订单货币对订单总额的令牌进行扣款，并在 Braintree 中使用 OpenCart 订单号作为订单 ID。扣款金额和货币会与订单进行核对。只有在 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. 使用同一购物车的下一次尝试，会根据已保存的交易设置该订单的状态，而不会再次扣款。每次显示 Confirm Order 步骤时，OpenCart 3 都会创建一个新订单，因此同一购物车可能有多个订单（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 Webhook。

订单与退款

订单状态

无状态（缺失订单）：付款未完成或被拒绝。在 Sales > Orders 中，只有将 Order Status 筛选条件设为 Missing Orders，才会显示此类订单。

Order Status After Payment（默认 Processing）：银行卡已被扣款（Sale），或授权已扣款。备注会显示金额、Braintree 交易 ID 和 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。确认提示 Refund this amount through Braintree? This cannot be undone. 全额和部分退款均受支持，既适用于已扣款的付款，也适用于审核中的付款。退款金额和货币与 Braintree 的扣款一致。Braintree 只对已结算的交易进行退款，通常在 24 小时内完成。结算前，全额退款会以撤销的方式完成；此时部分退款会失败，并提示等待结算。退款会发送到付款所在的环境（沙盒或正式），因此该环境的凭据必须已设置。如果 Braintree 未接受退款，标签页会显示错误，且不会记录退款。成功的退款会添加到退款记录和备注中。全额退款会将订单设为 Refunded Status；部分退款不会改变状态。从标签页进行的状态更改不会通知顾客，也不会将商品退回库存，与手动更改状态相同。

Sales > Returns 中的商品退货不会通过 Braintree 退回款项。拒付、结算拒付以及在 Braintree Control Panel 中进行的退款不会同步到 OpenCart。

许可证密钥

该扩展需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Braintree Gateway 是 Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit 上的第一个区块，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会显示被隐藏部分的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除该密钥）。下方是 Product: opencart-payment-braintree 一行，以及打开您的 vibefox.net 账户的链接 Manage licenses and domains in your account。只有对该扩展拥有 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。

银行卡已被扣款，但订单仍无状态：银行卡付款会立即确认，无需 Webhook。请查看订单备注和扩展页面上的 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 都失败：必须为您的 Braintree 商户账户启用 3-D Secure。请联系 Braintree 支持，或将 3-D Secure 设置为 Disabled（在 EEA 和英国不推荐，因为那里要求 SCA）。

顾客被告知无法以订单货币处理付款：Braintree 以商户账户的货币进行了扣款。请在当前环境的商户账户字段中，输入订单货币对应的商户账户 ID。

顾客看到 The order total must be greater than zero to pay by card.:订单总额为零，例如使用优惠券之后。此类订单无法用银行卡支付。

付款后立即出现部分退款失败：Braintree 只能退款已结算的交易，通常在 24 小时内。如需立即撤销交易，请全额退款；或在结算后再进行部分退款。

标签页中没有按钮，或出现与环境相关的消息：您的用户组没有修改该扩展的权限，或付款是在沙盒或正式环境中进行的，而该环境的凭据未设置。请输入凭据后重试。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Braintree Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装后会恢复为默认值。如果 Delete data on uninstall 开启，则其余网关设置（标题、描述、沙盒模式、凭据、商户账户、交易类型、3-D Secure、调试日志）和日志会被删除。如果关闭，它们会被保留，以便日后重新安装。Braintree 的交易和退款始终会被保留，因此之前已付款的订单在重新安装后仍可退款、扣款或撤销。现有订单会保留其付款备注。

在 OpenCart 4 中，如需删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Braintree Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

Braintree 是其各自所有者的商标。本扩展与 Braintree 无关联，也未获得 Braintree 的认可。