VibeFox PayU for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在较旧的 PHP 版本上安装。
币种：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. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox PayU Payment 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 输入四个 Sandbox 密钥和四个 Live 密钥（参见配置）。无需在 PayU 中配置任何通知 URL。
5. 开启 Enable/Disable 并点击 Save。在完成一次测试付款之前保持 Test Mode 开启，然后将其关闭，以使用 Live 密钥接收真实付款。
安装时，模块会创建两个订单状态：Awaiting PayU payment confirmation 和 PayU payment on hold。PrestaShop 会为所有币种、国家和客户组启用新的付款模块。您可以在 Payment > Preferences 中加以限制。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox PayU Payment > Configure。每个部分都有各自的 Save 按钮，会保存整个页面。在沙箱（测试）模式开启时（沙箱（测试）模式已开启：付款将进入 PayU 沙箱，不会扣除真实款项。请勿发货在测试模式下付款的订单。）、当前模式的四个密钥之一缺失时，以及 PayU 不接受店铺默认币种时，页面会在字段上方显示警告。在后两种情况下，结账时不会显示 PayU。
保存时，所有密钥中的空格和换行都会被删除，因为从 PayU 后台复制时常会带入这些字符。空的 Title 不会被保存：页面会显示 请输入付款方式的标题。
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：使用 PayU 沙箱和下方的 Sandbox 密钥。不会扣除真实款项。开启时，顾客会在付款选项下方看到 沙箱模式：不会收取真实付款。关闭后即可使用 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。
已保存的 Second Key 和 client secret 不会再次显示。字段保持为空，并显示 已保存 — 留空即保留原值。仅在需要更改时输入新值。POS ID 和 client ID 按已保存的内容显示。
Clear saved secrets：勾选某个密钥并点击 Save 即可将其删除。空字段会保留已保存的值。
每笔付款都会记住其环境。付款的通知、状态检查和退款始终使用该环境的密钥，因此切换模式后，旧付款仍可正常处理。使用沙箱密钥签名的通知绝不会被用于实际付款，反之亦然。
付款通知
Notification URL：显示 PayU 发送通知的地址。使用友好 URL 时，地址形如 https://your-shop/module/wcp_payu_payment/webhook，可能包含语言代码。模块会在每笔付款时将其发送给 PayU，因此无需在 PayU 后台进行任何设置。请确保该地址可从互联网访问（未被防火墙或 HTTP 身份验证阻止）。即使店铺处于维护模式，通知仍可正常工作，并且不受店铺国家限制的影响。
高级
Receive payments automatically：自动接收等待确认的付款。仅当您在 PayU 后台为销售点关闭了自动收款时才有意义：此时付款会等待确认（WAITING_FOR_CONFIRMATION）。开启此选项后，模块会立即接收此类付款，并在 PayU 报告付款已完成时创建订单。关闭时，或接收失败时，订单会以 Awaiting PayU payment confirmation 状态创建，您需通过订单中 PayU 区块的按钮接收或取消付款。默认：开启。
Logging：将技术事件（购物车和订单编号、PayU 订单 ID、状态、错误；不含密钥或个人数据）写入模块目录中的 logs/wc_pu_debug.log.php。该文件无法通过网页打开。错误始终会被记录；其他事件仅在此选项开启时记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：卸载模块时删除模块设置和日志。订单及其付款数据（PayU 交易、退款、订单状态）永远不会被删除。默认：关闭。
结账
在付款步骤中，顾客选择付款选项（默认为 PayU），并看到说明以及提示 您将被重定向至 PayU 以完成付款（BLIK、银行转账、银行卡及其他方式）。确认后，模块会以购物车币种为购物车总额创建 PayU 订单，描述为 Cart #、购物车编号和您的店铺名称，并附上商品、配送和礼品包装，以便在 PayU 页面显示。顾客的电子邮件、姓名和电话会传递给 PayU。当 PayU 支持时，PayU 页面语言跟随店铺语言；否则使用英语。顾客被重定向至 PayU 页面，在那里选择付款方式并付款。此时尚未创建订单。
每次付款尝试都会获得独立的 PayU 订单。顾客再次尝试时，购物车之前未完成的 PayU 付款会在 PayU 处被取消，因此旧付款链接无法被支付两次。如果之前的付款已经完成，则会创建订单，而不是新的付款。
仅仅返回您的店铺永远不会使订单付款。只有在 PayU 确认后，订单才会标记为已付款：通过使用付款环境的 Second Key 签名的通知，或在顾客返回时通过服务器端对 PayU 订单的状态检查（每个购物车至多每 10 秒一次）。PayU 订单必须是为此购物车创建的，且金额和币种必须一致。模块处理以下 PayU 状态：
付款确认后，顾客会看到标准的订单确认页面。对于等待确认或处于保留状态的订单，页面会额外显示 您的付款正在核实中。确认后我们会立即向您发送电子邮件。若此类订单的付款之后被取消，页面会显示 您的 PayU 付款未完成。请就此订单与我们联系。
若顾客返回时 PayU 尚未确认付款，Payment confirmation 页面会显示 我们尚未收到 PayU 的付款确认。若付款被中断，您可以重试：（或者，当 PayU 报告错误时，显示 付款未完成。您可以重试：），并提供 Pay again 和 Check again 按钮。通知一到达，订单即会创建。若付款已取消，顾客会返回结账页面，并显示 付款未完成。您可以重试，或选择其他付款方式。购物车会被保留。
若 PayU 无法开始付款，顾客会停留在结账页面，并显示 付款错误。请重试或选择其他付款方式。技术原因会写入日志。若当前模式的密钥缺失，显示的消息为 付款网关配置不正确。请联系管理员。
若购物车中的优惠券在付款与确认之间失效，它将从订单中移除。订单随后会进入 PayU payment on hold 状态，并附带注明该优惠券的备注，因为顾客是以折扣价付款的。
顾客是在 PayU 页面而非您的结账页面中选择付款方式的。模块在您的店铺中没有银行卡表单，不支持保存银行卡或一键付款，不支持订阅，也没有 PayU 分期或信贷组件。每个环境只使用一个销售点。
订单与退款
订单状态
尚无订单：顾客已被发送至 PayU 但尚未付款，或 PayU 尚未确认付款。仅存在购物车。
Payment accepted：付款已确认。付款以 PayU 订单 ID 作为交易 ID 记录，备注中显示 PayU 订单 ID、金额和环境（沙箱或 live）。
Awaiting PayU payment confirmation：付款已授权，等待您处理（自动收款关闭或收款失败）。尚未记录任何付款。
PayU payment on hold：已付金额或币种与购物车不符（订单不会被标记为已付款）、优惠券被移除、等待确认的付款金额不同，或为已取消的订单完成了付款（付款会被记录）。备注会说明具体是哪一种情况。请检查订单并处理，或退还该付款。
Payment error：等待确认的订单的付款已被取消或拒绝。
Refunded：该付款已通过模块全额退款。
每条通知只处理一次：重复的通知不会添加备注，也不会再次修改订单。如果对已付款或已退款的订单又完成了另一笔付款，备注会提醒您在 PayU 后台退款。对已付款或已关闭的订单，等待确认的付款会被自动取消，以免重复扣款。
PayU 付款区块
订单页面会显示一个 PayU payment 区块，包含 PayU 订单 ID、extOrderId、PayU 状态、已付和已退金额、沙箱付款的 Sandbox 标记、退款历史，以及订单的 PayU notes。区块中的操作需要编辑订单的权限；无需访问模块页面。
等待确认的付款
对于有等待确认付款的订单，区块会显示 Receive PayU payment (waiting for confirmation) 和 Cancel PayU payment (release the funds)。确认提示后，该操作会使用付款环境的密钥发送至 PayU，并以您的姓名添加到备注中，新的 PayU 状态会立即生效：收款成功会将订单设为 Payment accepted，取消则设为 Payment error。
退款
在 PayU payment 区块中输入金额（会自动填入尚未退还的金额），可选填原因，然后点击 Refund via PayU。确认提示 通过 PayU 退还此金额？此操作无法撤销。支持全额和部分退款。退款会针对实际付款的 PayU 订单发送，并使用该付款环境的密钥，因此必须设置好这些密钥。退款以 PayU 实际扣款的金额和币种进行；因此在金额或币种不一致后，您最多可退还顾客实际支付的金额，而不是订单总额。原因会作为退款描述发送。如果 PayU 拒绝退款，区块会显示 PayU 的错误，且不会记录任何退款。全额退款会将订单设为 Refunded。部分退款不会更改状态。
PayU 的退款是异步的。模块会立即添加一条包含 PayU 退款 ID 和状态的备注；最终状态稍后以 PayU 通知的形式到达，并添加到备注和退款历史中。若 PayU 取消了退款，备注会说明款项未退还给顾客，且该金额可以再次退款。
模块不会生成退款凭证。订单页面上的标准 PrestaShop 退款按钮不会通过 PayU 退回款项。
许可证密钥
模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox PayU Payment 是 Modules > Module Manager > VibeFox PayU Payment > Configure 页面中位于设置上方的第一个区块。在 License key 中输入密钥，然后点击 Activate。此后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除该密钥）。其下方有一行 Product: presta-payment-payu，以及一个链接 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。若仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法识别您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会通过通知得到确认，退款也能正常进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续期。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 PayU：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的四个密钥是否均已填写：沙箱模式下填写 Sandbox 密钥，实际模式下填写 Live 密钥。检查购物车币种是否属于受支持的币种之一。在 Payment > Preferences 中，检查模块是否允许用于购物车币种、顾客所在国家和顾客所属客户组。当密钥缺失或店铺币种不受支持时，设置页面会显示警告。
付款已完成，但未创建订单：PayU 尚未送达通知，返回页面的状态检查也未看到已完成的付款。请检查设置中显示的通知 URL 是否可从互联网访问。开启 Logging 以查看收到的内容。顾客也可以在 Payment confirmation 页面上点击 Check again。
通知返回 Invalid signature：该通知未使用任一环境的 Second Key 签名。请检查 Live Second Key (MD5) 和 Sandbox Second Key (MD5)。回应 Invalid signature for this payment 表示通知使用的是与该付款环境不同的密钥签名。
通知返回 Ignored: unknown PayU order：该 PayU 订单并非由本店铺创建，例如同一 POS 上的另一家店铺。PayU 将停止重试。
通知返回 Busy, retry later：该购物车正被另一请求同时确认，或订单无法创建（例如模块已禁用）。PayU 会重复发送通知。请开启 Logging 以查看原因。
通知 URL 在浏览器中显示 POST expected：这是正常的。该 URL 只接受来自 PayU 的通知。
顾客在选择 PayU 时看到 Payment error：请开启 Logging，并查看模块页面上的 Log 字段。日志会显示 HTTP 代码和 PayU 状态。无法通过 PayU 认证（请检查 OAuth client ID / secret）。表示当前模式的 OAuth 密钥有误。
订单处于 PayU payment on hold：请阅读 PayU payment 区块中的备注（参见订单状态），然后处理订单或退还付款。
订单处于 Awaiting PayU payment confirmation：您的销售点已关闭自动收款，付款正等待您处理。请使用 PayU 区块中的 Receive PayU payment 或 Cancel PayU payment。
退款失败：该订单没有已完成的 PayU 付款。无法处理退款。表示 PayU 尚未为该订单完成付款。若提示缺少 Sandbox 或 Live 密钥，则说明付款是在该环境中进行的，但未设置其密钥。请填写密钥后重试。
卸载
进入 Modules > Module Manager，打开 VibeFox PayU Payment 旁边的菜单，选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。缓存的 PayU 访问令牌始终会被删除。如果开启了 Delete data on uninstall，模块设置和日志会被删除。如果关闭，所有设置都会保留，以便之后重新安装。PayU 交易和退款以及订单状态 Awaiting PayU payment confirmation 和 PayU payment on hold 始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
PayU 是其各自所有者的商标。本模块与 PayU 无关联，也未获得 PayU 的认可或背书。