VibeFox PayU LATAM for WooCommerce — 帮助

系统要求

WordPress: 5.8 或更高版本。

WooCommerce: 7.0 或更高版本，已安装并启用。没有 WooCommerce 时插件会拒绝启用；若之后停用 WooCommerce，插件将不执行任何操作，并在管理后台显示提示。

PHP: 8.0 或更高版本。

Currency: 订单必须使用 ARS、BRL、CLP、COP、MXN、PEN 或 USD，即 PayU Latam 在阿根廷、巴西、智利、哥伦比亚、墨西哥、巴拿马和秘鲁处理的币种。使用其他币种时，结账页面会隐藏此付款方式。

PayU Latam account: 您需要 PayU 商户的三个值：商户 ID、销售所在国家的账户 ID 和 API 密钥。它们位于 PayU 模块（PayU 商户面板）的 Settings > Technical configuration（商户 ID、API 密钥）和 Accounts（账户 ID）中。PayU 在开发者文档的 "Test your solution" 页面公开提供测试凭据和测试卡。无需 API Login 或其他 API 凭据，因为付款在 PayU 托管页面上进行。

Internet access to your site: PayU 从其服务器向店铺发送付款结果，因此网站必须可通过互联网访问（不能是本地网站，也不能有密码保护或维护页面阻挡）。

VibeFox license key: 在 vibefox.net 购买。一个密钥用于一个域名。

安装

1. 在 WordPress 中前往 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_payu_latam_payment 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > PayU LATAM > Manage，或在插件页面的插件名称下点击 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 输入测试凭据和正式凭据（参见“配置”）。无需在 PayU 中配置确认 URL。

6. 开启 Enable/Disable 并保存。在完成测试付款之前，请保持 Sandbox 开启；之后取消勾选，即可使用正式凭据接收真实付款。

配置

所有设置都在同一页面：WooCommerce > Settings > Payments > PayU LATAM。在测试模式开启时（Sandbox mode. 付款会发送到 PayU 测试环境，不会扣取真实资金。）、当前环境缺少商户 ID、账户 ID 或 API 密钥时，以及 PayU LATAM 不处理店铺币种时，页面会在字段上方显示警告。在后两种情况下，结账页面不会显示 PayU LATAM。在付款方式列表中，PayU LATAM 会显示为需要设置，直至当前环境的三个凭据均已填写。凭据首尾的空格会被忽略。

常规

Enable/Disable: Enable PayU LATAM 用于启用或停用此付款方式。默认值：off。

Title: 结账时向顾客显示的付款方式标题。默认值：PayU LATAM。

Description: 结账时向顾客显示的付款方式说明。默认值：Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

环境

Sandbox: Enable the PayU sandbox (test mode)。付款会使用下方的测试凭据发送到 PayU 测试环境，不会扣取真实资金。停用时，会使用正式凭据和 PayU 正式结账页面。默认值：on。

正式凭据

在 PayU 模块中查找：Settings > Technical configuration（商户 ID、API 密钥）和 Accounts（销售所在国家的账户 ID）。此部分提供了前往 PayU 商户面板的链接。

Merchant ID: 您的 PayU 商户的数字标识符。

Account ID: PayU 账户的标识符。每个国家对应一个账户。

API Key: 用于签署付款和验证 PayU 通知的密钥。

测试凭据

PayU 为其测试环境公开提供测试凭据和测试卡。此部分提供了前往 PayU 文档 "Test your solution" 页面的链接。

Sandbox merchant ID: PayU 测试环境的商户 ID。

Sandbox account ID: PayU 测试环境的账户 ID。

Sandbox API key: PayU 测试环境的 API 密钥。

每次付款尝试都会记录其环境。测试付款的确认使用测试 API 密钥和商户 ID 验证，正式付款的确认则使用正式值，因此切换后待处理付款仍能正常处理。从仅有一组凭据的 1.0 版本升级时，如果之前开启了测试环境，旧值会复制到测试字段。升级后请检查设置。

确认 URL

此部分显示 PayU 报告每次付款结果的 URL，格式类似于 https://your-site/wc-api/payu_lp/。插件在每次付款时将其发送给 PayU，因此无需在 PayU 中配置。该页面必须可通过互联网访问。PayU 使用您的 API 密钥签署确认。没有有效签名、商户 ID 不同，或付款参考号并非本店为该订单签发的确认都会被拒绝。插件处理以下 PayU 交易状态：

4 (approved): 付款已完成。金额和币种匹配时，订单会标记为已付款。

6 (declined), 5 (expired), 104 (error): 付款失败。与最近一次尝试对应的未付款订单会标记为失败。

7 and other pending states: 付款正在等待中，例如顾客尚未完成的现金或银行付款。订单会设为保留。

其他状态只会添加为订单备注。没有确认，订单绝不会标记为已付款：它会保持等待付款状态。

高级

Debug log: Log payment requests and PayU notifications 将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_payu_latam_payment，不包含密钥或个人数据。错误和被拒绝的通知始终会记录。默认值：off。

Delete data: Delete the settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。订单中保存的 PayU 数据会保留。默认值：off。

结账

顾客选择付款方式（默认为 PayU LATAM）并下单。在测试模式下，结账区块会向顾客显示 Sandbox mode: no real payment is made. 订单保持等待付款状态，顾客前往店铺的付款页面，页面显示 Thank you for your order. You are being redirected to PayU LATAM to complete the payment… 页面会自动向 PayU WebCheckout 页面发送签名表单。如果没有自动发送，顾客可点击 Pay with PayU LATAM，或点击 Cancel order 取消订单。

表单包含订单总额和币种、订单税额和计税基础（无税订单中两者均为 0，以防 PayU 添加默认增值税）、包含订单号和店铺名称的 Order # 说明，以及顾客的电子邮箱、姓名、电话和账单地址。PayU 页面会根据店铺语言以西班牙语、葡萄牙语或英语打开。顾客在 PayU 页面使用您的 PayU 账户中启用的任意方式付款。

每次访问付款页面都会以独立参考号（订单号和时间戳）发起一次新的付款尝试。系统保留订单最近 30 次尝试：即使顾客在旧的 PayU 标签页中付款，付款仍会被接受。

只有在 PayU 通过签名确认核实付款后，订单才会标记为已付款。顾客从 PayU 返回绝不会将订单标记为已付款。顾客返回时：

收到带签名的拒绝、过期或错误结果后：订单立即标记为失败，WooCommerce 会显示其标准付款失败页面，提供再次付款选项。

没有 PayU 交易（顾客离开了 PayU 页面）：顾客会前往 Pay for order 页面，并看到消息 Your PayU LATAM payment was not completed. You can try again or choose another payment method.

其他情况：顾客会看到订单已收到页面。订单处于等待付款状态时，页面显示 We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. 对于保留状态的订单，页面显示 Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment.

如果缺少当前环境的凭据，顾客会看到 PayU LATAM is not available right now. Please choose another payment method. 如果订单币种不受支持，消息为 PayU LATAM does not accept payments in，后接币种。已付款的订单不会再次付款：付款页面会显示 This order has already been paid.

此付款方式适用于经典结账、结账区块和 Pay for order 页面，并兼容 WooCommerce High-Performance Order Storage（HPOS）。

插件不提供店铺内付款表单、从 WooCommerce 发起的退款、保存银行卡、订阅或分期设置（PayU 在其页面显示分期）。它不会通过 PayU API 查询付款状态：只有签名确认会更新订单。

订单

订单状态

Pending payment: 顾客已被转至 PayU 但尚未付款，或 PayU 尚未发送确认。

Processing: PayU 已确认付款，金额和币种匹配。订单备注显示 PayU 交易、金额、付款方式，并为测试付款显示 [sandbox]。订单交易 ID 即为 PayU 交易 ID。仅含虚拟可下载商品的订单会变为已完成，遵循 WooCommerce 的默认行为。

On hold: PayU 报告付款待处理（现金或银行付款），已付金额或币种与订单总额不符，或已取消订单的付款获批。订单备注会说明具体原因：请在 PayU 模块中核对付款，然后处理订单、恢复订单或退款。

Failed: 最近一次付款尝试被拒绝、已过期或出现错误。备注显示 PayU 消息。顾客可以再次付款。旧尝试被拒绝，或已有获批付款的订单收到拒绝结果时，只会添加备注。

每条通知在订单锁保护下仅处理一次：重复的 PayU 通知不会重复添加备注、减少库存或发送邮件。如果另一个请求更新订单的时间过长，确认会收到错误响应，PayU 稍后会再次发送。已付款、已完成或已退款的订单绝不会重新打开。如果已付款订单收到另一笔获批付款，备注会指出这一情况：若顾客付款两次，请在 PayU 模块中退还重复付款。

退款

退款不能从 WooCommerce 发起。请在 PayU 模块中退还交易款项，必要时在 WooCommerce 中手动记录退款。

许可证密钥

插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > PayU LATAM 顶部。将密钥粘贴到 License key 并点击 Activate。区块显示状态，例如许可证有效截止日期和您的域名。使用 Check now 再次检查状态、Change key 输入其他密钥、Remove key 从此网站移除密钥。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

一个密钥用于一个域名。从网站移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，结账页面不会向顾客显示 PayU LATAM。如果仍然发起付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到此付款方式，并带有 (unlicensed — visible to admins only) 标记，以便您在购买密钥前配置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍可得到确认。

许可证到期后，插件会继续运行，但更新和支持需要续订。状态会在后台自动再次检查。

故障排除

结账时没有显示 PayU LATAM：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前环境的商户 ID、账户 ID 和 API 密钥是否已填写：Sandbox 开启时使用测试凭据，关闭时使用正式凭据。请检查店铺币种（或订单付款页面的订单币种）是否为 ARS、BRL、CLP、COP、MXN、PEN 或 USD。设置页面会针对每个问题显示警告。

付款成功，但订单仍为 Pending payment：PayU 确认未到达您的店铺或已被拒绝。请检查设置中显示的确认 URL 是否可通过互联网访问（不能是本地网站，也不能有维护模式、防火墙或密码保护阻挡）。在 WooCommerce > Status > Logs 中查看来源 wcp_payu_latam_payment 的被拒绝确认。任何错误响应后，PayU 都会再次发送确认。

确认收到 Invalid signature 响应：确认并非使用付款所属环境的 API 密钥签署。正式付款请检查 API Key，测试付款请检查 Sandbox API key。

确认收到 Merchant mismatch 响应：确认中的商户 ID 与付款所属环境的 Merchant ID 或 Sandbox merchant ID 不同。请输入处理付款的 PayU 账户的商户 ID。

确认收到 Gateway not configured 响应：缺少付款所属环境的 API 密钥或商户 ID，例如在测试付款待处理时移除了测试凭据。请重新填写，PayU 会重试确认。

确认收到 Busy, retry later 响应：另一个请求当时正在同时更新订单。没有进行任何更改，PayU 会再次发送确认。

确认收到 Unknown reference 响应：付款参考号不属于本店的 PayU LATAM 订单，例如订单已改用其他付款方式或已被删除。

订单处于 On hold 状态：请阅读订单备注。付款仍在 PayU 待处理（现金或银行付款）、已付金额或币种与订单不同，或付款在订单取消后才到达。请在 PayU 模块中核对交易。

其他币种或表单字段：开发者可通过 payu_lp_supported_currencies 过滤器更改币种列表，通过 payu_lp_icon 过滤器更改结账图标，通过 payu_lp_payment_fields 过滤器更改 WebCheckout 表单字段。

许可证区块显示错误：请按区块消息操作。例如，如果密钥已用于其他域名，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。网站地址变更后，请点击 Check now 为新域名激活密钥。如果无法访问许可证服务器，插件会按最后已知状态继续运行。

卸载

停用插件会保留所有数据。要移除插件，请在 Plugins 页面停用并删除。此插件的许可证密钥和许可证状态始终会被移除。只有在 Delete data 已开启的情况下，才会移除此插件的网关设置和日志，否则会保留以供之后重新安装。现有订单保留其付款备注、PayU 参考号和交易 ID。

PayU 是其相应所有者的商标。本插件与 PayU 无关联，也未获得 PayU 认可。