VibeFox PayPal for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
PayPal 账户：在 PayPal Developer Dashboard 中拥有 REST API 应用的 PayPal Business 账户。您需要该应用的 Client ID 和 Secret。沙盒应用和正式应用的凭据不同。无需 Webhook：扩展会在顾客停留在结账页面期间，在您的服务器上确认每笔付款。
货币：PayPal 支持的货币之一：AUD、BRL、CAD、CHF、CNY、CZK、DKK、EUR、GBP、HKD、HUF、ILS、JPY、MXN、MYR、NOK、NZD、PHP、PLN、SEK、SGD、THB、TWD 或 USD。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请在您的计算机上解压。压缩包包含 README.txt、OpenCart 3 安装包 wcp_paypal_gateway-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 wcp_paypal_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_paypal_gateway-oc3-(version).ocmod.zip。本扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayPal Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要拥有修改付款扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。在页面顶部的许可证区块中将 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见 License key）。
4. 在 PayPal Developer Dashboard 中创建 REST API 应用（沙盒和/或正式环境），并将其 Client ID 和 Secret 复制到 API credentials 部分。
5. 选择 Capture 或 Authorize，开启 Enable/Disable，然后点击 Save。
6. 使用 PayPal 沙盒买家账户进行测试，然后关闭 Sandbox mode 并输入正式环境凭据。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_paypal_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PayPal Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按 OpenCart 3 的第 3 至 6 步输入许可证密钥、PayPal 凭据和付款操作。两个版本的设置页面及其字段相同。本扩展不会改动 OpenCart 4 自带的 PayPal 扩展：两者可以安装在同一家店铺中。
新安装默认关闭付款方式，并开启沙盒模式。
配置
所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox PayPal Gateway > Edit。各部分列于左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当付款方式已开启但所选模式的 Client ID 或 Secret 为空，以及当 PayPal 不支持店铺默认货币时，页面会发出警告。在这两种情况下，结账时都会隐藏该付款方式。沙盒模式开启时，页面会显示 Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. 如果没有修改扩展的权限，页面会显示设置，但无法保存。
保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，并且订单状态必须存在。如果任何检查未通过，则不会保存任何内容，并且页面会列出错误。保存设置会清除已缓存的 PayPal 访问令牌，以便立即使用新凭据。
常规
Enable/Disable：Enable PayPal Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：PayPal。必填，最多 128 个字符。
Description：顾客在 Confirm Order 步骤中、PayPal 按钮上方看到的文字。默认：Pay with your PayPal account or a card via PayPal.
Sort Order：PayPal 在结账时付款方式中的位置。留空或输入整数。
Geo Zone：仅为所选地理区域内的付款地址提供 PayPal。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单在店铺默认货币下必须达到的结账总额，才会提供 PayPal。留空则对任何总额都提供 PayPal。
API credentials
在 PayPal Developer Dashboard 中创建 REST API 应用，并复制其 Client ID 和 Secret。该部分提供沙盒应用和正式应用的链接。仅显示所选模式的字段；两种模式的凭据都会保持保存状态。
Sandbox mode：付款使用沙盒凭据发送至 PayPal 沙盒；不会转移真实资金。默认：开启。关闭后才会接受正式付款。捕获、撤销和退款始终使用订单付款时所在的环境。开启期间，顾客在 Confirm Order 步骤会看到 Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged.
Sandbox Client ID：您的沙盒 REST API 应用的 Client ID。
Sandbox Secret：您的沙盒 REST API 应用的 Secret。
Live Client ID：您的正式 REST API 应用的 Client ID。
Live Secret：您的正式 REST API 应用的 Secret。
已保存的密钥永远不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的密钥，请勾选字段下方的 Clear the saved secret on save，然后点击 Save。
付款
Payment action：顾客批准付款后执行的操作。默认：Capture。
订单
OpenCart 在 Confirm Order 步骤创建订单，此时不带状态（即缺失订单）。只有在 PayPal 在您的服务器上对捕获或授权作出响应后，订单才会获得状态。被拒绝的付款会使订单保持无状态，顾客则停留在 Confirm Order 步骤。下方每个字段都会列出您的 OpenCart 订单状态。
Order Status After Payment：捕获已完成，包括在订单选项卡中捕获授权或完成待处理捕获的情况。默认：处理中。
Awaiting Payment Status：捕获在 PayPal 处于 PENDING 状态（付款审核中，资金尚未结算）。默认：待付款。
Authorized Status：付款操作为 Authorize：资金已预留，但尚未付款。默认：待付款。
On Hold (Review) Status：PayPal 已收取款项，但无法读取付款，或金额或币种与订单不符。备注会说明需要检查的内容。默认：待付款，因为 OpenCart 没有搁置状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。
Voided Status：授权已在订单选项卡中撤销，预留资金已释放。默认：已取消。
Refunded Status：付款已全额退款。部分退款仅添加备注。默认：已退款。
Failed Status：待处理的捕获被 PayPal 拒绝。默认：失败。
高级
Debug log：将 API 请求记录到 OpenCart 日志文件夹（storage/logs）中的 wc_plg_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会移动到 wc_plg_debug.old.log.php。即使此开关关闭，错误和警告也始终会被记录。凭据、令牌和买家数据永远不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载扩展会删除网关设置和日志。已缓存的令牌始终会被删除。订单的付款数据（订单的 PayPal ID、退款）始终保留，因此之前已付款的订单在重新安装后仍可退款、捕获或撤销。默认：关闭。
导入 / 导出
Export：Download JSON 将设置保存为 JSON 文件。密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥会被保留。
结账
在 Payment Method 步骤，顾客选择付款方式（默认为 PayPal）。OpenCart 在 Confirm Order 步骤创建订单，仍然没有状态。顾客在此看到您的描述和 PayPal 按钮。点击按钮后，服务器会按订单币种以订单总额创建一笔 PayPal 订单。金额始终在服务器端计算，绝不在浏览器中计算。在 OpenCart 4 中，顾客在付款方式区块中点击 Choose 按钮，在 Payment method options 窗口中选择付款方式；随后，描述和 PayPal 按钮会出现在结账页面底部的确认区块中，并带有 Confirm Order 按钮。
顾客在 PayPal 窗口中使用 PayPal 账户或 PayPal 提供的其他资金来源批准付款。结账页面随后显示 PayPal payment approved. Completing your order…，并自动完成订单。如果顾客没有批准付款就点击 Confirm Order，则提示 Please click the PayPal button and approve the payment first.
您的服务器随后会读取 PayPal 订单，并检查其是否已批准、是否在本次结账中创建、是否不属于其他订单，以及其金额和币种是否与订单一致。只有通过这些检查后，才会捕获（或授权）付款。只有在 PayPal 确认之后，订单才会被标记为已付款。随后订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，购物车被清空，顾客会看到 OpenCart 的订单成功页面。
如果订单总额在批准后发生变化，则不会捕获任何款项。顾客会看到 The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. 如果 PayPal 拒绝付款，订单将保持无状态，并提示顾客再次点击 PayPal 按钮或选择其他付款方式。如果顾客关闭了 PayPal 窗口，结账页面会显示 You cancelled the PayPal payment.
如果 PayPal 在捕获期间没有响应，顾客会看到 We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. 该批准会针对此购物车保留，即使刷新页面之后也是如此：结账页面会显示 PayPal payment approved. Click "Confirm Order" to complete it.，而 Confirm Order 会再次使用该批准。如果 PayPal 已完成之前的尝试，则使用该笔付款，不会再捕获新的批准。如果付款已被收取但无法设置订单状态，顾客会看到 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. 下一次尝试会根据已保存的付款设置状态，不会再次收费。
OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，而 OpenCart 4 会更新结账的订单，因此付款归属于购物车：针对同一购物车的较早订单所做的批准，如果总额相同，就会支付当前订单；已付款的购物车永远不会被再次收费。购物车的任何变化（包括新的数量）都视为需要单独付款的新购物车。PayPal 脚本仅在 Confirm Order 步骤从 PayPal 加载，并且位于其自己的命名空间中，因此不会与页面上的另一个 PayPal 扩展冲突。
OpenCart 4 会将结账中的订单保留到显示成功页面为止。如果该订单期间已被关闭（例如您取消了它，或待处理的捕获被拒绝），或者它已为之前的购物车付过款，顾客会看到 Your previous order of this checkout is already closed or paid. Please refresh the page and confirm the order again — a new order will be created. 页面刷新后，下一笔付款将支付一个新订单。已付款的订单绝不会被显示为已为其他购物车付款。
本扩展没有 PayPal Webhook，没有 Pay Later 信息，没有银行卡输入栏，也没有 Venmo、Apple Pay、Google Pay 或 Fastlane，不支持保存的付款方式或订阅，商品页面和购物车页面也没有按钮。使用的是在 OpenCart 结账中输入的地址，而不是 PayPal 中的地址。
订单与退款
订单状态
无状态（缺失订单）：顾客尚未批准付款，或 PayPal 拒绝了付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。
付款后的订单状态（默认处理中）：捕获已完成。备注会显示金额、PayPal 订单和捕获。
已授权状态（默认待付款）：付款已授权，等待捕获（付款操作为 Authorize）。
付款等待状态（默认待付款）：捕获在 PayPal 处于 PENDING 状态，例如处于付款审核中。
搁置（审核）状态（默认待付款）：已付金额或币种与订单不符，或无法从 PayPal 的响应中读取付款。备注会说明原因。请检查订单并完成订单，或退还已付款项。
已撤销状态（默认已取消）：授权已通过 Void PayPal authorization 撤销。
失败状态（默认失败）：待处理的捕获被 PayPal 拒绝或失败。
已退款状态（默认已退款）：付款已通过扩展全额退款。
如果已付款的购物车又收到了第二笔付款，已付款的订单不会被更改。备注会要求您在 PayPal 账户中核对并退款。
备注是订单 History 中的条目，顾客看不到。在订单选项卡中进行的状态更改（捕获、撤销、状态查询、退款）会直接写入，不会通知顾客，也不会更改库存。
VibeFox PayPal Gateway 选项卡
在 Sales > Orders 中打开一笔通过 PayPal 付款的订单。在订单页面底部，与 History 和 Additional 并列，VibeFox PayPal Gateway 选项卡会显示 PayPal order ID 和 intent（沙盒付款会带有 Sandbox 标签）、Capture ID（链接到您 PayPal 账户中的付款，沙盒或正式环境）、Authorization ID、付款 Status、Amount、Paid / refunded 金额、退款记录以及订单的 PayPal notes。该选项卡会显示给有权访问本扩展的用户；其中的按钮需要修改扩展的权限（在 System > Users > User Groups 中设置）。每项操作的结果都会显示在该选项卡中。
退款
在 VibeFox PayPal Gateway 选项卡中输入金额（尚未退款的金额会自动填入），也可以选填 Reason (optional, sent to the buyer)，然后点击 Refund via PayPal。确认提示 Refund this amount through PayPal? This cannot be undone. 支持全额和部分退款。退款原因会作为给买家的备注发送至 PayPal。退款以 PayPal 实际收取的金额和币种进行，因此在金额或币种不符之后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会发送至付款所在的 PayPal 环境（沙盒或正式环境），因此该环境的凭据必须已设置。如果 PayPal 不接受退款，选项卡会显示错误，并且不会记录任何退款。成功的退款会添加到退款记录和备注中，并附带 PayPal 退款 ID 和状态；处于 PENDING 状态的退款稍后由 PayPal 完成。全额退款会将订单设置为 Refunded Status。部分退款不会更改状态。
仅授权的付款无法退款：请改用 Void PayPal authorization。Sales > Returns 中的商品退货不会通过 PayPal 退还款项。在您的 PayPal 账户中进行的退款、争议和拒付不会同步到 OpenCart。
许可证密钥
本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox PayPal Gateway 许可证区块是 Extensions > Extensions > Payments > VibeFox PayPal Gateway > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会显示被遮盖的密钥、状态（例如许可证有效期至何时以及您的域名），以及按钮 Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除该密钥）。其下方是 Product: opencart-payment-paypal 一行，以及打开您 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 PayPal。如果仍然发起了付款，店铺会拒绝创建 PayPal 订单，顾客会看到 An error occurred during PayPal checkout. Please try again. 以同一浏览器登录后台的管理员用户仍会在店铺中看到该付款方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成设置和测试。在 OpenCart 4 中，此预览不可用：店铺看不到后台登录状态，因此在没有有效密钥时，该付款方式对所有人都会隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：退款和订单选项卡中的操作仍可正常使用。
许可证到期后，本扩展仍会继续运行，但更新和支持需要续期。当您打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载本扩展始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 PayPal：请检查许可证是否有效、Enable/Disable 是否已开启、所选模式的 Client ID 和 Secret 是否已填写、订单币种是否受 PayPal 支持，以及订单总额是否大于零。如果问题出在凭据或店铺币种，设置页面会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。
付款已完成，但订单仍无状态：本扩展没有 Webhook，因此付款仅在结账期间得到确认。这种情况发生在 PayPal 在捕获期间没有响应，或无法设置订单状态时。请开启 Debug log 并查看 Log 字段，在您的 PayPal 账户中核对付款，或让顾客重试：重试永远不会重复收费，并会根据已保存的付款设置状态。
无法加载 PayPal：PayPal 脚本未能在浏览器中加载，例如浏览器扩展屏蔽了 www.paypal.com，或出现网络问题。
PayPal 目前不可用：凭据错误，或属于另一种模式。请重新复制正确应用的 Client ID 和 Secret。
您的 PayPal 批准无法与此次结账匹配：PayPal 订单不是在此次结账中创建的，例如会话过期之后。顾客需要再次点击 PayPal 按钮。
您的会话已过期，请刷新页面后重试：结账页面打开的时间过长。顾客需要重新加载页面。
此付款正在处理中：同一购物车在同一时刻被提交了两次。顾客应稍等片刻，并查看电子邮件后再重试。
订单在付款后处于审核或待处理状态：请阅读 VibeFox PayPal Gateway 选项卡中的备注。付款已被授权（请使用 Capture PayPal payment 捕获），捕获在 PayPal 处于 PENDING 状态（稍后可使用 Check PayPal payment status），或者已付金额或币种与订单不符（请完成订单或退还已付款项）。
授权的捕获失败：该授权可能已超过 29 天，或已被撤销。选项卡和备注会显示 PayPal 错误。
选项卡中没有按钮：选项卡会说明原因：您的用户组没有修改扩展的权限，付款已全额退款，或付款所在环境的 Client ID 和 Secret 未配置。
退款失败：订单没有 PayPal 捕获（仅有授权），金额超过了剩余可退款金额，或付款所在环境的凭据缺失。选项卡会说明具体是哪一种情况。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox PayPal Gateway 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态；重新安装时这些设置会恢复为默认值。已缓存的 PayPal 访问令牌始终会被删除。如果 Delete data on uninstall 已开启，其余网关设置（标题、描述、沙盒模式、凭据、付款操作、日志记录）以及日志都会被删除。如果已关闭，这些设置会保留，供以后重新安装时使用。PayPal 交易和退款始终保留，因此之前已付款的订单即使在重新安装后，仍可退款、捕获或撤销。现有订单会保留其付款备注。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox PayPal Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
PayPal 是其各自所有者的商标。本扩展与 PayPal 无关联，也未获得 PayPal 的认可。