VibeFox PayPal for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

PayPal 账户：一个 PayPal Business 账户，并在 PayPal Developer Dashboard 中创建 REST API 应用。您需要该应用的 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 购买。一个密钥只能用于一个域名。

安装

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

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

3. 在 Configure 页面顶部的许可证区块中，于 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

4. 在 PayPal Developer Dashboard 中创建 REST API 应用（沙盒和/或正式），并复制其 Client ID 和 Secret。

5. 输入您所用模式的凭据，选择 Capture 或 Authorize，开启 Enable/Disable，然后点击 Save。

6. 使用 PayPal 沙盒买家账户进行测试，然后关闭 Sandbox mode，并输入正式环境的凭据。

安装时，模块会创建三个订单状态：PayPal payment authorized、Awaiting PayPal payment 和 PayPal payment on hold。PrestaShop 会为所有币种、国家和客户组提供新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox PayPal Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果付款方式已启用但所选模式的 Client ID 或 Secret 为空，或者 PayPal 不支持店铺的默认币种，页面会发出警告。在这两种情况下，结账时都会隐藏该付款方式。沙盒模式开启时，页面会显示 Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. 保存设置会清除缓存的 PayPal 访问令牌，因此新凭据会立即生效。

General

Enable/Disable：Enable PayPal Gateway 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：PayPal。必填。

Description：结账时显示在付款方式下方的文字。默认：Pay with your PayPal account or a card via PayPal.

API 凭据

在 PayPal Developer Dashboard 中创建 REST API 应用，并复制其 Client ID 和 Secret。该部分提供了沙盒应用和正式应用的链接。只显示所选模式的字段；两种模式的凭据都会保持保存状态。

Sandbox mode：付款使用沙盒凭据进入 PayPal 沙盒；不会转移真实资金。默认：开启。关闭它即可接受正式付款。扣款、撤销和退款始终使用订单付款时所在的环境。开启时，顾客会在付款方式下方看到 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。

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

Clear saved secrets：勾选某个 Secret 并点击 Save 即可将其删除。空字段会保留已保存的值。

付款

Payment action：顾客批准付款时会发生什么。默认：Capture。

高级

Debug log：将 API 请求记录到模块文件夹中的 logs/wc_plg_debug.log.php。该文件无法通过网页打开。即使此开关关闭，错误和警告仍会始终记录。凭据、令牌和买家数据从不记录。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete data on uninstall：开启时，卸载模块会删除网关设置、缓存的令牌和日志。订单的付款数据（订单的 PayPal ID、退款）和订单状态始终保留。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 PayPal），PayPal 按钮会出现在付款表单的位置。点击按钮后，您的服务器会以购物车币种创建一个金额为购物车总额的 PayPal 订单。金额始终在服务器上计算，绝不在浏览器中计算。此时尚不存在任何订单。

顾客在 PayPal 窗口中使用 PayPal 账户或 PayPal 提供的其他资金来源批准付款。随后结账页面会显示 PayPal payment approved. Completing your order… 并创建订单。如果尚未接受服务条款，结账页面会显示 PayPal payment approved. Click "Place order" to complete it. 如果顾客未批准付款就点击 Place order，提示信息为 Please click the PayPal button and approve the payment first.

随后，您的服务器会读取 PayPal 订单，并检查它是否已批准、是否为该购物车创建、是否未被其他购物车使用，以及其金额和币种是否与购物车一致。只有这些检查都通过后，才会扣款（或授权）、创建订单，顾客随后看到标准的订单确认页面。

如果批准之后购物车总额发生变化，则不会扣款。顾客会看到 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. 该批准会被保留，即使刷新页面也一样，Place order 会再次使用它。如果 PayPal 已完成先前的尝试，则使用该付款，不会再扣一次。如果付款已收取但无法创建订单，顾客会看到 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. 下一次尝试会根据已保存的付款创建订单，且不会再次扣款。

PayPal 脚本仅在结账页面加载，并使用独立的命名空间，因此不会与页面上的其他 PayPal 模块冲突。本模块适用于 Classic 和 Hummingbird 主题。

本模块没有 PayPal Webhook、Pay Later 提示信息、银行卡输入框，也不支持 Venmo、Apple Pay、Google Pay 或 Fastlane，不支持已保存的付款方式或订阅，商品页和购物车页面也没有按钮。使用的是 PrestaShop 结账页面中输入的地址，而不是 PayPal 中的地址。

订单与退款

订单状态

No order yet：顾客未批准付款，或 PayPal 拒绝了付款。只存在购物车。

Payment accepted：扣款已完成。只有在 PayPal 确认后，订单才会被标记为已付款。付款会以 PayPal 扣款 ID 作为交易 ID 记录，备注中会显示金额、PayPal 订单和扣款信息。

PayPal payment authorized：付款已授权，等待扣款（付款操作 Authorize）。

Awaiting PayPal payment：扣款在 PayPal 处于 PENDING 状态，例如正在进行付款审核。

PayPal payment on hold：已付金额或币种与订单不符，或无法从 PayPal 的响应中读取付款信息。备注会说明原因。当 PayPal 以订单币种扣款时，实际支付的金额会被记录为付款。请检查订单并进行处理，或退还该笔付款。

Canceled：授权已通过 Void PayPal authorization 撤销。

Payment error：待处理的扣款被拒绝或失败。

Refunded：该笔付款已通过模块全额退款。

如果针对已有订单的购物车又收到第二笔付款，订单不会被更改。备注会提醒您在 PayPal 账户中核实并退款。

PayPal 付款区块

订单页面会显示 PayPal payment 区块，其中包括 PayPal 订单 ID 和 intent、扣款 ID（链接到您 PayPal 账户中的付款，沙盒或正式）、授权 ID、付款状态、金额、已付和已退金额、沙盒付款的 Sandbox 标记、退款记录以及订单的 PayPal notes。该区块的按钮需要编辑订单的权限，但不需要访问模块页面的权限。每项操作的结果都会显示在该区块中。

退款

在 PayPal payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via PayPal。确认提问 Refund this amount through PayPal? This cannot be undone. 支持全额和部分退款。退款原因会作为备注传递给 PayPal 并提供给买家。退款以 PayPal 扣除的金额和币种进行；因此，在金额或币种不一致之后，您可以退还的最高金额是顾客实际支付的金额，而不是订单总额。退款会发送至付款时所用的 PayPal 环境（沙盒或正式），因此必须已设置该环境的凭据。如果 PayPal 不接受退款，该区块会显示错误，并且不会记录退款。成功的退款会连同 PayPal 退款 ID 和状态添加到退款记录和备注中；PENDING 状态的退款稍后由 PayPal 完成。全额退款会使订单变为 Refunded。部分退款不会更改状态。

仅经过授权的付款无法退款：请改用 Void PayPal authorization。本模块不会创建退款单据。PrestaShop 订单页面上的标准退款按钮不会通过 PayPal 退还资金。在 PayPal 账户中进行的退款、争议和撤回不会同步到 PrestaShop。

许可证密钥

本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox PayPal Gateway 位于 Modules > Module Manager > VibeFox PayPal Gateway > Configure 页面的最顶部，位于设置上方。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以遮蔽形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此商店中移除密钥）。其下方是 Product: presta-payment-paypal 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文本跟随后台语言显示（包括英语和俄语）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加某个日期。商店地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会按最近一次已知的状态继续运行。

一个密钥只能用于一个域名：主商店的域名，多店铺设置中也是如此。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效的密钥，结账时不会向顾客显示 PayPal。如果仍然启动了付款，商店会拒绝创建 PayPal 订单，顾客会看到 An error occurred during PayPal checkout. Please try again. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：退款和 PayPal 区块中的操作仍然可用。

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

故障排除

PayPal does not appear at checkout：请检查许可证是否有效，Enable/Disable 是否开启，所选模式的 Client ID 和 Secret 是否已填写，购物车币种是否受 PayPal 支持，以及购物车总额是否大于零。如果问题出在凭据或币种上，设置页面会显示警告。在 Payment > Preferences 中，检查模块是否允许用于购物车币种、顾客所在国家和顾客所在客户组。阻止 www.paypal.com 的浏览器扩展也会隐藏该按钮。

The payment went through, but no order was created：模块没有 Webhook，因此付款只会在结账期间得到确认。这种情况发生在扣款期间 PayPal 没有响应，或者无法创建订单时。请开启 Debug log 并查看 Log 字段，在您的 PayPal 账户中核实付款，或让顾客重试：重试绝不会重复扣款，并会根据已保存的付款创建订单。

PayPal could not be loaded：PayPal 脚本未能在浏览器中加载，例如因为拦截程序或网络问题。

PayPal is not available right now：凭据错误或属于另一种模式。请重新复制正确应用的 Client ID 和 Secret。

Your PayPal approval could not be matched to this checkout：PayPal 订单并非为此购物车创建，例如会话过期之后。顾客需再次点击 PayPal 按钮。

This payment is already being processed：同一购物车在同一时刻被提交了两次。顾客应稍等片刻并查看电子邮件后，再尝试重试。

The order is on hold after payment：请阅读 PayPal payment 区块中的备注。付款已授权（使用 Capture PayPal payment 进行扣款），扣款在 PayPal 处于 PENDING 状态（稍后使用 Check PayPal payment status），或者已付金额或币种与订单不符（处理订单或退还已付款项）。

Capture of an authorization fails：授权可能已超过 29 天，或已被撤销。区块和备注会显示 PayPal 的错误信息。

Refund fails：订单没有 PayPal 扣款（只有授权），金额超过了剩余可退金额，或付款所用环境的凭据缺失。区块会说明具体原因。

卸载

进入 Modules > Module Manager，打开 VibeFox PayPal Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置、缓存的 PayPal 访问令牌和日志都会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。PayPal 交易和退款，以及订单状态 PayPal payment authorized、Awaiting PayPal payment 和 PayPal payment on hold 始终保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。

PayPal 是其各自所有者的商标。本模块与 PayPal 无关联，也未获得 PayPal 的认可。