VibeFox Tpay for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法激活。
PHP：8.0 或更高版本。需要 OpenSSL 扩展，并且需要能够通过 HTTPS 向 secure.tpay.com 发出外部请求，以便进行通知的 JWS 签名检查。
店铺货币：仅支持波兰兹罗提（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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_tpay_payment 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Tpay > Manage，或在插件列表页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入沙盒密钥和正式密钥（参见「配置」）。除安全代码外，Tpay 后台无需进行任何设置：通知地址会随每笔交易一起发送。
6. 开启 Enable/Disable，在沙盒模式下测试一笔付款，然后取消勾选 Sandbox mode 以接受真实付款。
配置
所有设置都在同一页面中：WooCommerce > Settings > Payments > Tpay。在字段上方，当沙盒模式开启时，页面会显示 Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged.。当前模式的密钥不完整时（此时结账页面不会显示 Tpay）、店铺货币不是 PLN 时，以及在启用 JWS 检查的情况下缺少 PHP OpenSSL 扩展时（付款将无法被确认），页面都会发出警告。在付款方式列表中，在输入当前模式的密钥之前，Tpay 会被标记为需要设置。保存时会自动删除粘贴到 Merchant ID 或 Client ID 中的空格。
常规
Enable/Disable：Enable Tpay payments 用于启用或禁用该付款方式。默认：关闭。
Title：结账时向顾客显示的付款方式标题。默认：Tpay。
Description：结账时向顾客显示的付款方式描述。默认：Pay with BLIK, online bank transfer or card on the secure Tpay page.
Sandbox mode：Use the Tpay sandbox (test payments, no real money)。沙盒模式使用沙盒密钥和 Tpay 沙盒 API。关闭该选项后，将使用正式密钥接受真实付款。退款始终发送到订单付款时所在的环境。默认：开启。
正式密钥
获取位置：在 Tpay 商户后台的 Integration，API 下（Open API 密钥：Client ID 和 Secret）；Merchant ID 为您的 Tpay 账户 ID；安全代码位于 Settings，Notifications 下。
Merchant ID：您的 Tpay 账户 ID（数字）。Tpay 会在每条通知中发送该 ID。
Client ID：Open API Client ID。
Client secret：Open API Client secret。
Security code：用于验证 Tpay 通知的 MD5 校验和。
沙盒密钥
沙盒是一个独立的 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：沙盒账户的通知安全代码。
付款通知
Tpay 会将付款确认发送到本部分显示的地址。该地址格式如下：https://your-site/wc-api/wc_tp_payment/。该地址会随每笔交易自动发送，除安全代码外，Tpay 后台无需进行任何设置。只有在收到校验和与签名均有效且金额匹配的通知后，订单才会被标记为已付款。在您的店铺接受通知之前，Tpay 会重复发送。
JWS 签名：Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended)。需要 PHP OpenSSL 扩展，并且需要能够向 secure.tpay.com 发出 HTTPS 外部请求。MD5 校验和始终会被验证。默认：开启。
高级
Debug log：Log payment events。仅记录技术事件（不包含密钥和顾客数据），记录位置为 WooCommerce > Status > Logs，来源 wcp_tpay_payment。默认：关闭。
Delete data on uninstall：Remove the plugin settings and logs when the plugin is deleted。停用插件不会删除任何内容。订单及其 Tpay 付款数据始终会被保留。默认：关闭。
1.0 版本的设置会自动迁移：在测试模式开启时使用的密钥将成为沙盒密钥。
结账
顾客选择付款方式（默认为 Tpay）并下单。在沙盒模式下，结账页面会显示 Sandbox mode — no real money is charged.。插件会以 PLN 为订单总额创建一笔 Tpay 交易，描述为 Order # 加上订单号，并传递顾客的姓名、电子邮件、地址和电话，然后将顾客重定向到 Tpay 付款页面。该页面会根据网站语言显示为波兰语、英语或乌克兰语（其他语言显示为英语）。顾客在该页面上选择 BLIK、银行转账、银行卡或您 Tpay 账户中启用的其他方式并完成付款。
只有在 Tpay 确认后，订单才会被标记为已付款。Tpay 会向您的店铺发送通知；插件会使用安全代码检查 MD5 校验和、Merchant ID，以及（若已开启）JWS 签名，然后检查金额：金额必须等于本次付款尝试所请求的金额和订单总额，且实付金额不能更低。没有有效校验和或签名的通知会被拒绝。
付款后，顾客会返回订单接收页面。仅仅返回不会将订单标记为已付款。如果通知尚未到达，页面会向 Tpay API 查询交易状态（最多每 10 秒一次），并应用相同的检查。在付款未被确认期间，页面会显示 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:，并附带 Pay again 链接。Tpay 报告付款失败后，页面会显示 Tpay reports that the payment did not go through. You can try again:，并附带同一链接。如果付款在 Tpay 页面上失败，Tpay 会将顾客带回同一订单的 Pay for order 页面。
每次付款尝试都有各自的参考编号。顾客重新付款时，该订单之前未付款的 Tpay 交易会在 Tpay 处被取消；通过较早链接已完成的付款仍会被接受。当未付款订单被取消时（例如由于 WooCommerce 库存保留超时），也会发生同样的取消操作。
如果 Tpay 无法启动付款，顾客会看到 The Tpay payment could not be started. Please try again or choose another payment method.，原因会记录到日志中。
该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅支持 PLN。店铺中没有银行或 BLIK 代码选择（顾客在 Tpay 页面上选择），没有已保存的银行卡，没有订阅，没有店铺内的 Apple Pay 或 Google Pay 按钮，也没有分期付款计算器。
订单与退款
订单状态
Pending payment：已创建 Tpay 交易，但付款尚未确认。订单备注会显示 Tpay 交易和环境。
Processing：Tpay 已确认付款。这是付款后的 WooCommerce 标准状态（仅包含虚拟可下载商品的订单会变为已完成）。备注会说明付款是通过通知还是状态查询确认的，并显示任何超额付款。交易 ID 即 Tpay 交易标题（TR-...）。
On hold：已收到付款，但其金额与请求金额或订单总额不符，仅支付了部分金额，或订单已被取消。订单备注会对此进行说明。请在 Tpay 后台检查该付款，然后完成或退款该订单。
Failed：Tpay 报告付款失败。只有待付款订单会被标记为失败。顾客可以重新付款。
如果 Tpay 为已付款或已退款的订单报告另一笔付款，订单不会改变；备注会提示您在必要时在 Tpay 后台退还多收的付款。Tpay 报告的拒付（chargeback）会添加一条备注。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Tpay（按钮上会显示您的 Title）。对于通过 Tpay 收到付款的订单，支持全额和部分退款；对于未付款的订单，不会显示该按钮。退款会发送到订单付款时所在的环境（沙盒或正式环境），因此必须已设置该环境的密钥。只有在 Tpay 确认后，退款才算完成；被 Tpay 拒绝或未确认的退款会显示为错误，并且不会记录在 WooCommerce 中。成功的退款会连同您输入的原因一起添加到订单备注中（该原因不会发送给 Tpay）。
在 Tpay 商户后台进行的退款不会自动添加到 WooCommerce。
许可证密钥
本插件需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Tpay 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从本站点移除密钥。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效的密钥时，顾客在结账时看不到 Tpay。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍会看到该付款方式，并标注为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件列表页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可以正常进行。
许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时没有显示 Tpay：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式的四个密钥是否都已输入（Merchant ID、Client ID、Client secret、Security code）。请检查店铺货币（或 Pay for order 页面上的订单货币）是否为 PLN。设置页面会针对上述每个问题显示警告。
付款已完成，但订单仍为 Pending payment：Tpay 无法送达通知，或通知被拒绝。请开启 Debug log，并查看 WooCommerce > Status > Logs 中来源为 wcp_tpay_payment 的日志。常见原因包括：当前模式的安全代码或 Merchant ID 错误、通知地址被阻止（维护模式、防火墙、HTTP 身份验证），或服务器缺少 OpenSSL 或无法发出 HTTPS 外部请求以进行 JWS 检查。顾客返回时，订单接收页面也会检查状态。
Notification answered FALSE - invalid checksum：设置中的 Merchant ID 或安全代码与该付款所属的 Tpay 账户（沙盒或正式环境）不匹配。
Notification answered FALSE - invalid JWS signature：无法验证签名，例如缺少 OpenSSL，或无法下载 Tpay 证书。请修复服务器，或在必要时关闭 JWS signature；MD5 校验和仍会被检查。
订单处于 On hold：请阅读订单备注。实付金额与订单不符，或付款是针对已取消订单到达的。请在 Tpay 后台检查该付款，然后完成或退款该订单。
顾客看到了 The Tpay payment could not be started：当前模式的密钥有误，或 Tpay 拒绝了请求。日志会显示 Tpay 的错误信息。
退款失败：如果提示缺少密钥，请输入订单付款时所在环境的密钥。如果 Tpay 未确认退款，请先在 Tpay 商户后台检查该交易，再重试。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件将继续使用最后一次已知的状态运行。
卸载
停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面中将其删除。本插件的许可证密钥和许可证状态始终会被删除，缓存的 Tpay 访问令牌和证书也会被删除。只有在 Delete data on uninstall 已开启的情况下，网关设置和日志才会被删除；否则它们会保留，以便日后重新安装时使用。现有订单会保留其付款备注、Tpay 交易数据和交易 ID。
Tpay 是其各自所有者的商标。本插件与 Tpay 无关联，也未获得 Tpay 的认可。