VibeFox PayU for WooCommerce — 帮助
系统要求
WordPress: 5.8 或更高版本。
WooCommerce: 7.0 或更高版本，已安装并激活。若未安装 WooCommerce，本插件将拒绝激活；如果随后停用了 WooCommerce，插件将不执行任何操作并在管理后台显示提示通知。
PHP: 8.0 或更高版本。
店铺币种：PLN、EUR、CZK、HUF、RON、BGN、GBP、USD、CHF、DKK、NOK、SEK、UAH 之一。该币种还必须在 PayU 中为您的销售点启用。对于其他币种，该付款方式在结账时会被隐藏。
网站公网访问：PayU 会向您的店铺发送付款通知，因此网站必须能从公网访问（不得处于 HTTP 认证或维护页面之后）。即使没有收到通知，当顾客从 PayU 返回时仍会检查订单。
PayU 账户：您需要销售点（POS）的四个密钥：POS ID、Second key (MD5)、OAuth client_id 和 OAuth client_secret。它们位于 PayU 商户后台的 Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys。沙箱密钥来自独立的 PayU 沙箱账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥适用于一个域名。
安装
1. 在 WordPress 中前往 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_payu_payment 文件夹上传至 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > PayU > Manage，或在“插件”页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入四个 Sandbox 密钥和四个 Live 密钥（参见“配置”）。无需在 PayU 中配置任何通知 URL。
6. 开启 Enable/Disable。保持 Test Mode 开启，直到完成测试付款，然后取消勾选以使用 Live 密钥接收真实付款。
配置
所有设置均位于同一页面：WooCommerce > Settings > Payments > PayU。字段上方会在沙箱模式开启时、当前模式的四个密钥之一缺失时以及 PayU 不接受店铺币种时显示警告提示。在后两种情况下，PayU 不会在结账时显示。
保存时，所有密钥中的空格和换行符都会被自动移除，因为从 PayU 面板复制时经常会附带这些字符。
常规
Enable/Disable: Enable PayU payment gateway 用于开启或关闭付款方式。默认：关闭。
Title: 显示给顾客的付款方式标题。默认：PayU。
Description: 显示给顾客的付款方式描述。默认：Pay securely via PayU。
API 凭据
在 PayU 商户面板中查找密钥：Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys。沙箱密钥来自独立的 PayU 沙箱账户。所选模式的四个密钥必须全部填写。
Test Mode: Enable sandbox (test) mode。使用 PayU 沙箱及下方的 Sandbox 密钥。不会扣除真实资金。在经典结账和结账区块上，顾客会看到 Sandbox mode — no real money is charged。关闭该选项即可使用 Live 密钥接收真实付款。默认：开启。
Live POS ID: 正式销售点的 POS ID (merchantPosId)。
Live Second Key (MD5): 用于验证 PayU 通知签名的密钥。
Live OAuth Client ID: 销售点的 OAuth client_id。
Live OAuth Client Secret: 销售点的 OAuth client_secret。
Sandbox POS ID: PayU 沙箱销售点的 POS ID。
Sandbox Second Key (MD5): 用于验证 PayU 沙箱通知签名的密钥。
Sandbox OAuth Client ID: 沙箱销售点的 OAuth client_id。
Sandbox OAuth Client Secret: 沙箱销售点的 OAuth client_secret。
每笔付款都会记住其所在环境。付款的通知、状态检查和退款始终使用该环境的密钥，因此在切换环境后旧付款仍可正常处理。使用沙箱密钥签名的通知绝不会被正式付款接受。
付款通知
本节显示通知 URL，格式类似于 https://your-site/wc-api/wc_pu_payment/。插件会在每次付款时将其发送给 PayU，因此无需在 PayU 面板中进行任何配置。请确保其可从公网访问（未被防火墙、维护模式或 HTTP 认证拦截）。
高级
Receive payments automatically: Automatically receive payments waiting for confirmation。这仅在 PayU 面板中为您的 POS 关闭了自动收款时有意义：此时付款将等待确认（WAITING_FOR_CONFIRMATION）。开启此选项时，插件会立即接收此类付款。关闭时，此类订单将被设为保留，您可通过订单操作 Receive PayU payment 和 Cancel PayU payment 来接收或取消付款。默认：开启。
Logging: Enable logging 将技术事件（订单号、PayU 订单 ID、状态、错误，不含密钥或个人数据）写入 WooCommerce > Status > Logs，来源为 wcp_payu_payment。默认：关闭。
Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted。订单及其付款数据绝不会被删除。停用插件会保留所有内容。默认：关闭。
结账
顾客选择付款方式（默认为 PayU）并下单。插件按订单币种的总额创建 PayU 订单，描述为 Order #、订单号和您的店铺名称，并附带订单商品、配送和费用以显示在 PayU 页面上。若 PayU 支持，PayU 页面的语言将采用店铺语言，否则为英语。顾客被引导至 PayU 付款页面，在页面上选择付款方式并完成付款。
每次付款尝试都会生成独立的 PayU 订单。当顾客再次付款时（在付款失败或取消之后，或者在 Pay for order 页面上），该订单之前未完成的 PayU 付款会在 PayU 处取消，因此旧的付款链接无法被支付两次。
仅凭返回您的店铺绝不会将订单标记为已付款。只有在 PayU 确认后订单才会标记为已付款：通过使用付款环境的 Second Key 签名的通知，或在顾客返回时在服务器端对 PayU 订单进行状态检查（在通知延迟时很有用）。PayU 订单必须是为该订单创建的，且金额和币种必须一致。插件处理以下 PayU 状态：
在“订单已接收”页面上，当订单仍处于待付款状态时，顾客会看到 We have not received the payment confirmation from PayU yet. If the payment was interrupted, you can try again:；若付款失败，则看到 The payment was not completed. You can try again:，每条提示都附带一个 Pay again 按钮。对于保留状态的订单，提示为 Your payment is being verified. We will send you an e-mail as soon as it is confirmed.
如果 PayU 无法发起付款，顾客会看到 Payment error. Please try again or choose another payment method. 技术原因（HTTP 状态码和 PayU 状态）将记录到日志和订单备注 PayU payment could not be started: 中。如果当前模式的密钥缺失，提示为 Payment gateway is not configured properly. Please contact the administrator.
该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它与 WooCommerce 高性能订单存储（HPOS）兼容。
顾客在 PayU 页面上选择付款方式，而不是在您的结账页面中。插件在您的店铺中没有银行卡表单，不支持保存银行卡或一键付款，不支持订阅，也不提供 PayU 分期或信贷组件。每个环境使用一个销售点（不支持按币种设置销售点）。
订单与退款
订单状态
Pending payment: 顾客已被引导至 PayU 且尚未付款。订单备注显示 PayU 订单 ID 和环境（sandbox 或 live）。
Processing: 付款已确认。订单备注显示 PayU 订单 ID、金额和环境。交易 ID 为已支付的 PayU 订单 ID。仅包含虚拟可下载商品的订单将变为已完成，符合 WooCommerce 的默认行为。
On hold: 支付的金额或币种与订单不符、已取消的订单完成了付款，或付款等待您的确认（自动收款已关闭或收款失败）。订单备注会说明具体情况及处理方法。
Failed: 最新的 PayU 付款已取消或被拒绝。顾客可以重新付款。
每条通知均在针对该订单的锁定保护下处理一次：重复通知不会重复添加备注、不会重复减少库存，也不会重复发送电子邮件。若针对已付款或已退款的订单又完成了一笔付款，备注会提示您在 PayU 面板中进行退款。对于已付款或已关闭的订单，处于等待确认状态的付款会被自动取消，确保资金不会被扣取两次。
等待确认的付款
对于含有等待确认付款的未付款订单，订单页面提供两项订单操作：Receive PayU payment (waiting for confirmation) 和 Cancel PayU payment (release the funds)。选择其中一项并点击更新按钮。该操作将连同您的用户名记录到订单备注中，并立即应用新的 PayU 状态。
退款
打开订单，点击 Refund，输入金额并点击 Refund via PayU（按钮上显示您的 Title）。支持全额和部分退款。退款请求是针对实际已支付的 PayU 订单发起的，并使用该付款所在环境的密钥，因此必须配置这些密钥。退款原因将作为退款说明发送。若 PayU 拒绝退款，WooCommerce 将显示 PayU 的错误，且不会记录任何退款。
PayU 的退款为异步处理。插件会立即添加一条包含 PayU 退款 ID 和状态的备注；最终状态随后会作为 PayU 通知送达并添加为备注。如果 PayU 取消退款，备注会说明资金未退还给顾客。
因金额或币种不一致而被设为保留的订单，将保留 PayU 订单 ID 作为其交易 ID，以便既可以从 WooCommerce 发起退款，也可以在 PayU 面板中退款。
许可证密钥
本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > PayU 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥适用于一个域名。从站点中移除密钥并不会释放其域名配额。请在您的 vibefox.net 账户中释放配额。
没有有效密钥时，结账时不会向顾客显示 PayU。若仍发起付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，且标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前配置并测试插件。提醒会出现在“插件”页面和 WooCommerce 各页面上。现有订单不受影响：已发起的付款仍可确认，退款功能也可正常使用。
许可证过期后，插件仍可继续工作，但更新和技术支持需要续订。系统会在后台自动重新检查状态。
故障排除
PayU 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式的四个密钥是否全部填写：沙箱模式下填写 Sandbox 密钥，正式模式下填写 Live 密钥。检查店铺币种（或 Pay for order 页面上的订单币种）是否为受支持的币种之一。设置页面会针对这些问题分别显示警告。
付款已完成，但订单仍为待付款状态：PayU 尚未送达通知，且返回页面上的状态检查未检测到已完成的付款。检查设置中显示的通知 URL 是否可从公网访问。开启 Logging 以查看接收到的数据。
通知返回 Invalid signature：通知未包含任何一个环境的 Second Key 签名。请检查 Live Second Key (MD5) 和 Sandbox Second Key (MD5)。返回 Invalid signature for this payment 表示通知所用的签名密钥来自与该付款不同的环境。
通知返回 Ignored：该 PayU 订单不属于本店铺通过 PayU 支付的订单（例如属于同一 POS 上的另一家店铺）。PayU 将停止重试。
付款未能创建：开启 Logging 并查看 WooCommerce > Status > Logs，来源为 wcp_payu_payment。日志会显示 HTTP 状态码和 PayU 状态。Could not authenticate with PayU (check the OAuth client ID / secret). 表示当前模式的 OAuth 密钥错误。
订单处于保留状态：请阅读订单备注。原因可能是金额或币种不符、取消订单后的付款或等待确认的付款。对于最后一种情况，请使用订单操作 Receive PayU payment 或 Cancel PayU payment。
退款失败：This order has no completed PayU payment. Cannot process refund. 表示该订单没有已付款的 PayU 订单。提示缺少 Sandbox 密钥或 Live 密钥的信息表示付款是在该环境中进行的，而相应的密钥未配置。请输入密钥并重试。
其他币种：开发者可通过 wc_pu_supported_currencies 过滤器修改币种列表，并通过 wc_pu_icon 过滤器修改结账图标。
许可证区块显示错误：请按照区块中的提示进行操作。例如，如果密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放配额，然后点击 Check now。如果站点地址发生变更，点击 Check now 即可为新域名激活密钥。如果无法连接许可证服务器，插件将按最后已知的状态继续运行。
卸载
停用插件会保留所有设置；仅清除缓存的 PayU 访问令牌。如需移除插件，请在 Plugins 页面先停用再删除。本插件的许可证密钥和许可证状态始终会被移除，缓存的令牌也会一并清除。仅当开启了 Delete data on uninstall 时，网关设置和本插件的日志才会被移除。否则它们将保留以供日后重新安装。现有订单会保留其付款备注、PayU 订单 ID 和交易 ID。
PayU 是其各自所有者的商标。本插件与 PayU 无关联，也未获得 PayU 认可。