VibeFox Tpay for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。通知的 JWS 签名检查需要 OpenSSL 扩展，以及到 secure.tpay.com 的出站 HTTPS 连接。
商店货币：仅支持波兰兹罗提（PLN）。Tpay 以 PLN 结算，其 Open API 没有货币字段，因此当购物车使用其他货币时，会隐藏该付款方式。
商店的互联网访问：Tpay 会将付款通知发送到您的商店，因此通知地址必须可以从互联网访问（不能被防火墙或 HTTP 身份验证拦截）。
Tpay 账户：您需要从 Tpay 商户面板获取以下信息：Merchant ID（您的 Tpay 账户 ID）、Open API 密钥 Client ID 和 Client secret（Integration, API），以及安全代码（Settings, Notifications）。沙盒密钥来自单独的 Tpay 沙盒账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者以后在模块列表中找到 VibeFox Tpay Payment 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（见“许可证密钥”）。
4. 输入沙盒密钥和正式环境密钥（参见 Configuration）。除安全代码外，无需在 Tpay 面板中进行任何设置：通知地址会随每笔交易一起发送。
5. 开启 Enable/Disable 并点击 Save。先在沙盒模式下测试付款，然后关闭 Sandbox mode 以接受真实付款。
安装时，模块会创建订单状态 Tpay payment on hold。PrestaShop 会为所有货币、国家和客户组提供新的付款模块。您可以在 Payment > Preferences 中进行限制；模块必须仍然允许 PLN。
Configuration
所有设置都在模块页面中：Modules > Module Manager > VibeFox Tpay Payment > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，沙盒模式开启时页面会显示 Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged.。当当前模式的密钥不完整时（此时结账时不显示 Tpay）、商店默认货币不是 PLN 时，以及在启用 JWS 检查的情况下缺少 PHP 的 OpenSSL 扩展时（此时付款将无法确认），页面都会发出警告。粘贴到 Merchant ID 或 Client ID 中的空格会在保存时被删除。
Tpay
Enable/Disable：Enable Tpay payments 用于开启或关闭该付款方式。默认：关闭。
Title：结账时向顾客显示的付款方式标题。它也是订单中保存的付款方式名称。默认：Tpay。必填。
Description：结账时向顾客显示的付款方式描述。默认：Pay with BLIK, online bank transfer or card on the secure Tpay page.
Sandbox mode：使用 Tpay 沙盒（测试付款，不收取真实资金），搭配沙盒密钥和 openapi.sandbox.tpay.com。关闭后，将使用正式环境密钥接受真实付款。退款始终发送到订单付款时所在的环境。默认：开启。
Production keys
在哪里找到：在 Tpay 商户面板的 Integration, API 下（Open API 密钥：Client ID 和 Secret）；Merchant ID 是您的 Tpay 账户 ID；安全代码位于 Settings, Notifications 中。
Merchant ID：您的 Tpay 账户 ID（数字）。Tpay 会在每条通知中发送它。
Client ID：Open API Client ID。
Client secret：Open API Client secret。
Security code：用于验证 Tpay 通知的 MD5 校验和。
Sandbox keys
沙盒是一个独立的 Tpay 测试账户，拥有自己的密钥（参见 Tpay API 文档）。仅在 Sandbox mode 开启时使用。
Sandbox Merchant ID：沙盒账户的 Merchant ID。
Sandbox Client ID：沙盒账户的 Open API Client ID。
Sandbox Client secret：沙盒账户的 Open API Client secret。
Sandbox Security code：沙盒账户的通知安全代码。
已保存的机密信息（两个环境的 Client secret 和 Security code）不会再次显示。字段保持为空，并显示 Saved - leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved secrets：勾选某个机密信息并点击 Save 即可将其删除。空字段会保留已保存的值。
Payment notifications
Notification URL：Tpay 会将付款确认发送到此处显示的地址。使用友好 URL 时，其格式类似 https://your-shop/module/wcp_tpay_payment/notify，可能包含语言代码，例如 /en/。该地址会随每笔交易自动发送；除安全代码外，无需在 Tpay 面板中进行设置。只有在收到校验和与签名均有效、且金额匹配的通知之后（或顾客返回时经过匹配的状态查询之后），才会创建订单。Tpay 会持续重发通知，直到您的商店接受为止。
JWS signature：还会使用 Tpay 证书验证通知中的 X-JWS-Signature（推荐）。需要 PHP 的 OpenSSL 扩展以及到 secure.tpay.com 的出站 HTTPS 连接。证书会缓存一天。MD5 校验和始终会被验证。默认：开启。
Advanced
Debug log：记录付款事件：仅包含技术事件（不含密钥，不含顾客数据），写入模块文件夹中的 logs/wc_tp_debug.log.php。该文件无法通过网页打开。默认：关闭。关闭时不会写入任何内容，包括错误，因此在查找问题原因之前请先开启。
Log：显示日志的大小和最新条目。点击 Clear log 可将其清空。
Delete data on uninstall：开启后，卸载模块将删除模块设置和日志。订单及其 Tpay 付款数据始终会保留。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Tpay）。沙盒模式下，付款选项会显示 Sandbox mode - no real money is charged. 确认后，模块会以 PLN 为单位，按购物车总额创建一笔 Tpay 交易，描述为 Cart # 加购物车编号，并传递顾客的姓名、电子邮件、账单地址和电话，然后将顾客带到 Tpay 付款页面。该页面会根据商店语言以波兰语、英语或乌克兰语显示（其他语言显示英语）。顾客在页面上选择 BLIK、银行转账、银行卡或您 Tpay 账户中启用的其他方式并付款。此时尚未创建订单。
只有在 Tpay 确认后，订单才会被标记为已付款。Tpay 会向您的商店发送通知；模块会使用付款发起环境的密钥，验证 MD5 校验和（使用安全代码）、Merchant ID，以及（若已开启）JWS 签名，然后检查金额：金额必须等于本次付款尝试所请求的金额及购物车总额，且已付金额不得更低。没有有效校验和或签名的通知会被拒绝。之后订单被创建，顾客会看到标准的订单确认页面。
付款后，顾客会返回您的商店。仅仅返回并不会将任何内容标记为已付款。如果通知尚未到达，模块会向 Tpay API 查询交易状态（最多每 10 秒一次），并应用相同的检查。在付款得到确认之前，Payment confirmation 页面会显示 Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again:，并提供 Refresh 按钮和 Pay again 按钮（后者返回结账页面）。通知一到达就会创建订单。
如果 Tpay 报告付款失败，顾客会回到结账页面，并显示 Tpay reports that the payment did not go through. Please try again or choose another payment method. 如果付款在 Tpay 页面上失败，Tpay 会将顾客送回结账页面。两种情况下购物车都会保留。如果订单被置为保留状态，确认页面会显示 Your payment is being verified. We will contact you as soon as it is confirmed.
每次付款尝试都有各自的参考编号。顾客再次付款时，购物车之前未付款的 Tpay 交易会在 Tpay 处被取消；通过较早链接已完成的付款仍会被接受。如果购物车已有订单，顾客会被带到该订单的确认页面，而不是重新付款。
如果 Tpay 无法开始付款，顾客会停留在结账页面，并显示 The Tpay payment could not be started. Please try again or choose another payment method.，原因会写入日志（需开启 Debug log）。
即使商店处于维护模式，通知地址仍可正常工作，且不受商店国家限制的影响。
本模块仅支持 PLN。商店中没有银行或 BLIK 代码的选择（顾客在 Tpay 页面上选择），没有已保存的银行卡，没有订阅，商店内没有 Apple Pay 或 Google Pay 按钮，也没有分期付款计算器。
订单与退款
订单状态
No order yet：顾客已被带到 Tpay 但尚未付款，或 Tpay 尚未确认付款。此时只存在购物车。付款失败同样不会创建订单。
Payment accepted：Tpay 已确认付款。付款会以 Tpay 交易标题（TR-...）作为交易 ID 进行记录。备注会说明付款是通过通知还是状态查询确认的、所在环境，以及是否有超额付款。
Tpay payment on hold：已收到付款，但其金额与请求金额或购物车总额不符（例如，付款开始后购物车被修改），仅支付了一部分，或者付款是在订单被取消之后才到达的。备注会对此加以说明。请在 Tpay 面板中核实付款，然后处理订单或退款。如果顾客随后通过新的尝试支付了正确金额，订单会变为 Payment accepted。
Refunded：付款已通过模块全额退款。
如果 Tpay 报告某个已付款或已退款订单的另一笔付款，订单不会被修改；备注会提醒您，如有需要，请在 Tpay 面板中退还多余的付款。Tpay 报告的拒付（chargeback）会添加一条备注。
Tpay 付款区块
订单页面会显示 Tpay payment 区块，其中包括 Tpay 交易标题和 ID、付款参考编号（CRC）、环境（沙盒付款会显示 Sandbox 标记）、付款状态及确认方式、已付金额、订单总额和已退金额、退款记录、购物车的所有 Payment attempts，以及订单的 Payment notes。
退款
在 Tpay payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Tpay。确认提示 Refund this amount through Tpay? This cannot be undone.。通过 Tpay 收到付款的订单（包括处于保留状态的订单）支持全额和部分退款。您需要具有编辑订单的权限；不需要访问 Modules 页面。您最多可以退款至付款所对应的 Tpay 交易所收取的金额，且不超过订单总额：在部分付款或购物车被修改后，区块会显示 Refundable (paid through Tpay)。退款会发送到订单付款时所在的环境（沙盒或正式环境），因此必须已设置该环境的密钥。只有当 Tpay 确认退款后，退款才算完成；被 Tpay 拒绝或未确认的退款会以错误形式显示，且不会被记录。退款成功后，会连同您输入的原因一起添加到退款记录和备注中（原因不会发送给 Tpay）。全额退还可退金额会将订单设为 Refunded。部分退款不会更改状态。
模块不会创建贷项凭证（credit slip）。订单页面上的标准 PrestaShop 退款按钮不会通过 Tpay 退还资金。在 Tpay 商户面板中进行的退款不会自动添加到 PrestaShop 中。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Tpay Payment 位于 Modules > Module Manager > VibeFox Tpay Payment > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本商店移除密钥。其下方有一行 Product: presta-payment-tpay 和链接 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Tpay。如果仍然开始了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已开始的付款仍会被确认，退款也正常可用。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Tpay：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的四个密钥是否都已输入（Merchant ID、Client ID、Client secret、Security code）。检查购物车货币是否为 PLN，以及模块是否在 Payment > Preferences 中对 PLN、顾客所在国家和顾客所属客户组获得允许。设置页面会对缺失的密钥以及非 PLN 的商店货币显示警告。
付款已完成，但未创建订单：Tpay 无法送达通知，或通知被拒绝。请开启 Debug log，并查看模块页面上的 Log 字段。常见原因包括：安全代码或 Merchant ID 与付款所属环境不符，通知地址被阻止（防火墙、HTTP 身份验证），或服务器缺少 OpenSSL 或无法进行 JWS 检查所需的出站 HTTPS。顾客付款后返回商店时，订单也会被创建。
Notification answered FALSE - invalid checksum：设置中的 Merchant ID 或安全代码与该付款所属的 Tpay 账户（沙盒或正式环境）不匹配。
Notification answered FALSE - invalid JWS signature：无法验证签名，例如缺少 OpenSSL，或无法下载 Tpay 证书。请修复服务器，或在必要时关闭 JWS signature；MD5 校验和仍会被检查。
Notification answered FALSE - busy, retry later or FALSE - order could not be created：购物车在同一时刻正被另一个请求处理，或者订单无法创建（例如模块已被禁用）。Tpay 会自动重发通知。请开启 Debug log 查看原因。
通知 URL 显示 FALSE - POST only in the browser：这是正常现象。该 URL 只接受来自 Tpay 的通知。
订单处于 Tpay payment on hold 状态：请阅读 Tpay payment 区块中的备注（参见订单状态），在 Tpay 面板中核实付款，然后处理订单或退还付款。
顾客看到了 The Tpay payment could not be started：当前模式的密钥有误，或 Tpay 拒绝了请求。请开启 Debug log；日志会显示 Tpay 的错误。
顾客看到了 We could not match this payment to an order：返回链接不属于该顾客的购物车。如果顾客已被扣款，通知仍会创建订单；请检查 Tpay 面板。
退款失败：如果提示缺少密钥，请输入订单付款所在环境的密钥。如果提示金额过高，最多只能退还所显示的金额。如果 Tpay 未确认退款，请在重试之前，在 Tpay 商户面板中检查该交易。
卸载
进入 Modules > Module Manager，打开 VibeFox Tpay Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。缓存的 Tpay 访问令牌和证书始终会被删除。如果 Delete data on uninstall 已开启，模块设置和日志也会被删除。如果关闭，设置会保留，以便日后重新安装时使用。Tpay 交易和退款以及 Tpay payment on hold 订单状态始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Tpay 是其各自所有者的商标。本模块与 Tpay 无关联，也未获得 Tpay 的认可。