VibeFox PayU LATAM for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

币种：购物车必须使用 ARS、BRL、CLP、COP、MXN、PEN 或 USD，这些是 PayU Latam 在阿根廷、巴西、智利、哥伦比亚、墨西哥、巴拿马和秘鲁处理的币种。使用其他币种时，结账时不会显示该付款方式。

PayU Latam 账户：您需要 PayU 商户账户中的三个值：商户 ID、您销售所在国家的账户 ID，以及 API 密钥。它们位于 PayU 模块（PayU 商户后台）中：Settings > Technical configuration（merchant ID、API key）和 Accounts（account ID）。测试时，PayU 会在其开发者文档的 "Test your solution" 页面上公布公开的测试凭据和测试卡。由于付款在 PayU 托管的页面上完成，且模块从不调用 PayU API，因此不需要 API Login 和其他 API 凭据。

商店的互联网访问：PayU 从其服务器将付款结果发送到您的商店，因此商店必须能通过互联网访问（不能是本地站点，也不能受密码保护）。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。

安装

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

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox PayU LATAM Payment 并点击 Configure。

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

4. 输入测试凭据和正式凭据（见配置）。无需在 PayU 中设置任何确认 URL。

5. 启用 Enable/Disable 并点击 Save。在完成一次测试付款之前保持 Sandbox 开启，然后将其关闭，以便使用正式凭据接收真实付款。

安装时，模块会创建两个订单状态：Awaiting PayU LATAM payment 和 PayU LATAM payment on hold。PrestaShop 会为所有币种、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中加以限制。之后启用的国家也必须在那里为该模块勾选。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox PayU LATAM Payment > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，页面会显示：开启测试模式时的 Sandbox mode. Payments go to the PayU sandbox and no real money is charged.；当前环境的商户 ID、账户 ID 或 API 密钥缺失时的错误提示；以及 PayU LATAM 不处理商店默认币种时的警告。凭据缺失时，结账页面不会显示 PayU LATAM。凭据开头或结尾的空格会被忽略。页面不会保存空的 Title，并会显示 Enter a title for the payment method.

PayU LATAM

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

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：付款会使用下方的测试凭据发送到 PayU 测试环境，不会收取任何真实款项。关闭时，使用正式凭据和 PayU 正式付款页面。默认：开启。开启时，顾客会在付款方式下方看到 Sandbox mode: no real money is charged.

正式凭据

请在 PayU 模块中查找：Settings > Technical configuration（merchant ID、API key）和 Accounts（您销售所在国家的 account 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 密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved secrets：勾选 API Key 或 Sandbox API key，然后点击 Save 以删除已保存的密钥。字段为空时保留已保存的值。

每次付款尝试都会记录其环境。测试付款的确认使用测试环境的 API 密钥和商户 ID 进行验证，正式付款的确认则使用正式环境的值，因此切换后待处理付款仍能正常运作。切换后确认的测试付款会在订单备注中标记为 [sandbox]。

确认 URL

此部分显示 PayU 报告每个付款结果时所使用的 URL。启用友好 URL 时，它看起来像 https://your-shop/module/wcp_payu_latam_payment/confirmation，可能还带有语言代码，例如 /en/。模块会在每次付款时将其发送给 PayU，因此无需在 PayU 中进行任何配置。该 URL 必须可通过互联网访问。商店处于维护模式时它仍可工作，也不会受到商店国家限制的阻挡。确认信息由 PayU 使用您的 API 密钥签名。签名无效、商户 ID 不同或付款参考号并非本商店发出的确认都会被拒绝。模块会处理以下 PayU 交易状态：

其他状态只会作为备注添加。没有确认，就不会创建订单。

高级

Debug log：将付款请求和 PayU 通知记录到模块文件夹中的 logs/payu_lp_debug.log.php。该文件无法通过网页打开。不会记录密钥和个人数据。即使此开关关闭，错误和被拒绝的通知也始终会被记录。默认：关闭。

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

Delete data：卸载模块时删除设置和日志。订单的 PayU 数据（付款尝试）和订单状态会保留。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 PayU LATAM）并确认。您商店的页面会显示 You are being redirected to PayU LATAM to complete the payment...，并自动向 PayU WebCheckout 页面发送一个已签名的表单。如果没有发生这种情况，顾客可以点击 Pay with PayU LATAM，或点击 Back to checkout 返回。此时尚不存在订单。

表单包含购物车的总金额和币种、购物车的税额和税基（对于不含税的购物车，两者均为 0，以免 PayU 添加默认增值税），描述为 Cart #，内容包括购物车编号和您的商店名称，以及顾客的电子邮件、姓名、电话和账单地址。PayU 页面会根据购物车的语言以西班牙语、葡萄牙语或英语打开。在 PayU 页面上，顾客可以使用您 PayU 账户中启用的任意方式付款。

每次访问付款页面都会以其自己的参考号（PS、购物车编号和时间戳）开始一次新的付款尝试。较早的尝试会被记住：如果顾客在较早打开的 PayU 标签页中付款，付款仍会被接受。

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

如果当前环境的凭据缺失，顾客会看到 PayU LATAM is not available right now. Please choose another payment method. 对于不受支持的购物车币种，信息为 PayU LATAM does not accept payments in，后接币种。已有订单的购物车不会再次付款：顾客会被带到其订单确认页面。

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

订单

订单状态

尚无订单：顾客已被送往 PayU 但未付款，付款被拒绝，或 PayU 尚未发送确认。只存在购物车。

Payment accepted：PayU 已确认付款，且金额和币种相符。付款会以 PayU 交易 ID 记录，备注会显示交易、金额、付款方式，测试付款还会显示 [sandbox]。

Awaiting PayU LATAM payment：PayU 将付款报告为待处理（现金或银行付款）。当 PayU 确认付款后，订单会转为 Payment accepted。

PayU LATAM payment on hold：已付金额或币种与购物车总额不符，或某笔付款是针对已取消的订单获得批准的。如果付款使用的是订单币种，则会记录该付款。备注会说明具体情况：请在 PayU 模块中核实付款，然后处理订单、恢复订单或退款。

Payment error：最近一次尝试的待处理付款之后被拒绝、过期或以错误结束。备注会显示 PayU 消息。此购物车无法再次付款：顾客需要下新订单。较早尝试的拒绝，或已有已批准付款的订单的拒绝，仅会作为备注添加。

每条通知都在购物车锁保护下仅处理一次：重复的 PayU 通知不会创建第二个订单，也不会重复添加备注。已付款的订单绝不会重新打开或降级。如果一个已付款订单又收到另一笔已批准的付款，备注会说明此情况：如果顾客付了两次，请在 PayU 模块中退还重复的款项。

PayU LATAM 付款区块

订单页面会显示 PayU LATAM payment 区块，包括参考号、交易 ID、PayU 参考号、状态和 PayU 状态、请求金额、PayU 报告的金额、付款方式、PayU 消息、测试付款的 SANDBOX 标记、购物车所有付款尝试的列表，以及订单的 PayU LATAM notes。

退款

退款不在 PrestaShop 中进行。请在 PayU 模块中退还交易，然后在 PrestaShop 中手动记录退款。

许可证密钥

本模块使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox PayU LATAM Payment 许可证区块位于模块 Modules > Module Manager > VibeFox PayU LATAM Payment > Configure 页面最上方，位于设置上方。将密钥输入 License key，然后点击 Activate。此后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店中移除密钥）。其下方是 Product: presta-payment-payu-latam 行以及 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 账户中释放名额。

没有有效密钥时，结账页面不会向顾客显示 PayU LATAM。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法识别您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会显示提醒。现有订单不受影响：已发起的付款仍会通过 PayU 确认和顾客返回得到确认。

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

故障排除

结账时未显示 PayU LATAM：请检查许可证是否有效、Enable/Disable 是否开启，以及当前环境的商户 ID、账户 ID 和 API 密钥是否已填写：开启 Sandbox 时填写测试凭据，关闭时填写正式凭据。检查购物车币种是否为 ARS、BRL、CLP、COP、MXN、PEN 或 USD。在 Payment > Preferences 中检查该模块是否允许用于购物车币种、顾客所在国家和顾客群组。

付款已完成，但未创建订单：PayU 确认未到达您的商店，或被拒绝。请检查设置中显示的确认 URL 能否通过互联网访问（不能是本地站点、被防火墙拦截或有密码保护）。查看模块页面上的 Log 字段，了解被拒绝的确认。任何错误响应之后，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 会重试确认。

确认返回 Retry：同一时刻有另一个请求正在处理该购物车，或无法创建订单（例如模块已禁用）。没有任何更改，PayU 会再次发送确认。请查看 Log 了解原因。

确认返回 Unknown reference：该付款参考号不是由本商店发出的。

确认 URL 在浏览器中显示 Method not allowed：这是正常的。该 URL 只接受来自 PayU 的请求。

顾客看到 This payment method is not available：在 Payment > Preferences 中，该模块不允许用于顾客的国家、币种或群组，或者 Enable/Disable 处于关闭状态。

订单为 PayU LATAM payment on hold：请阅读 PayU LATAM payment 区块中的备注。已付金额或币种与购物车不同，或者付款是在订单取消之后到达的。请在 PayU 模块中检查该交易。

卸载

进入 Modules > Module Manager，打开 VibeFox PayU LATAM Payment 旁边的菜单，然后选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete data 已开启，则会删除设置和日志。如果已关闭，则所有设置都会保留，以便日后重新安装。付款尝试以及 Awaiting PayU LATAM payment 和 PayU LATAM payment on hold 订单状态始终会保留，因此即使重新安装后，较早尝试的迟到 PayU 确认仍会被识别。现有订单会保留其付款备注、PayU 参考号和交易 ID。

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