VibeFox Cashfree for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：6.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
HTTPS：Cashfree 只会向 https:// 地址发送 Webhook。若未使用 HTTPS，付款仍会在顾客返回店铺时得到确认，但正式上线前请务必启用 HTTPS。
Cashfree 账户：您需要 Cashfree 账户的 App ID 和 Secret Key，测试环境（sandbox）和正式环境各一套，并需要在 Cashfree 商户后台中添加 Webhook（参见「配置」）。Secret Key 同时用于验证 Webhook，因此没有单独的 Webhook 密钥。订单币种必须已在您的 Cashfree 账户中启用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_cashfree_payment 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Cashfree Payments > Manage，或在插件列表页点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 Sandbox App ID 和 Sandbox Secret Key，在 Cashfree 商户后台中添加 Webhook（参见「配置」），开启 Enable/Disable，然后测试一笔付款。
6. 准备上线时，输入正式环境的 App ID 和 Secret Key，并取消勾选 Sandbox Mode。
配置
所有设置位于同一页面：WooCommerce > Settings > Payments > Cashfree Payments。付款方式启用后，若所选模式的 API 密钥缺失，页面会发出警告（此时该付款方式在结账时隐藏）；测试环境模式开启时，页面会显示 Sandbox mode is on: customers see a test checkout and no real money is charged.。若保存已启用的网关时未填写所选模式的密钥，将显示错误信息，提示在设置密钥之前，该付款方式在结账时保持隐藏。
常规
Enable/Disable: Enable Cashfree Payments 用于开启或关闭该付款方式。默认：关闭。
Title: 顾客在结账时看到的付款方式名称。默认：Cashfree Payments。
Description: 结账时付款方式下方显示的文字。默认：Pay securely via Card, UPI, Net Banking, Wallet via Cashfree。
模式与 API 密钥
在 Cashfree 商户后台的 Developers > API Keys 中获取 App ID 和 Secret Key。测试环境与正式环境的密钥不同，请分别填入对应的区块。
Sandbox Mode: Enable Sandbox (test) mode 使用 Cashfree 测试环境进行测试。不会扣除真实款项，结账页面会显示 SANDBOX MODE - no real payments will be processed.。默认：开启。取消勾选即可接收正式付款。
测试环境凭据
Sandbox App ID: 您 Cashfree 测试环境的 App ID。
Sandbox Secret Key: 您 Cashfree 测试环境的 Secret Key。
正式环境凭据
App ID: 您 Cashfree 正式环境的 App ID。
Secret Key: 您 Cashfree 正式环境的 Secret Key。
订单会保留其创建时所在的环境。其 Webhook 使用该环境的密钥进行验证，退款也使用该环境的密钥发送，因此切换到正式环境后，请保留测试环境的密钥，直至测试环境订单全部结算完毕。
Webhook
Webhook 用于告知您的店铺某笔付款已完成、失败或已退款。在 Cashfree 商户后台中进入 Developers > Webhooks，添加本节显示的地址，并勾选 Payment 和 Refund 事件。地址形如 https://your-site/wc-api/cashfree_p/?action=webhook。在 HTTPS 站点上，插件还会在每笔订单中将该地址一并传递给 Cashfree。若您的站点未使用 HTTPS，本节会显示警告。
插件处理以下事件：
Cashfree 会使用您的 Secret Key 为每个 Webhook 签名。没有有效签名的 Webhook 会被拒绝。对于并非由本店铺创建的订单（例如同一 Cashfree 账户下的其他店铺）的已签名 Webhook，插件会予以确认但不做处理。若没有 Webhook，只有在顾客付款后返回店铺时，订单才会得到确认。若顾客付款后关闭了浏览器，只有 Webhook 能确认该订单。
高级
API Version: 使用的 Cashfree API 版本。
Order ID prefix: Cashfree 订单号由前缀加 WooCommerce 订单号组成；重复尝试时，末尾会加上编号。留空则使用本站点的自动前缀（显示在字段说明中）。同一 Cashfree 账户下连接的每家店铺请使用不同的前缀。仅限字母、数字、「_」和「-」，最多 20 个字符。保存时，其他字符会被删除，并显示提示。
Debug log: Log Cashfree API events for debugging。错误始终会被记录。开启后，API 调用和 Webhook 也会写入 WooCommerce > Status > Logs，来源为 wcp_cashfree_payment。日志绝不会记录密钥和顾客数据。默认：关闭。
Delete Data on Uninstall: Delete all plugin data when uninstalling。开启时，删除插件会移除 Cashfree 设置、插件日志以及订单上存储的 Cashfree 引用信息。订单本身会保留。默认：关闭。
结账
顾客选择付款方式（默认为 Cashfree Payments）并下单。插件会按订单币种为订单总额创建 Cashfree 订单，并打开 Pay for order 页面，该页面显示 Redirecting to Cashfree for payment...，并加载 Cashfree 结账页面。若页面未能自动打开，顾客可点击 Pay Now。在 Cashfree 结账页面中，顾客可使用您 Cashfree 账户中启用的任何方式付款，例如银行卡、UPI、网上银行或电子钱包。
付款后，顾客返回您的店铺。只有在 Cashfree 确认后，订单才会被标记为已付款：通过经签名的 Webhook，或在顾客返回时由服务器向 Cashfree 发出请求进行核对。若银行尚未确认付款，订单已接收页面会显示 Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again.
若付款失败，或顾客在未付款的情况下离开 Cashfree 页面，顾客会返回 Pay for order 页面，并显示 The Cashfree payment was not completed. Please try again or choose another payment method. 顾客再次尝试时，会复用仍处于打开状态的 Cashfree 付款。若订单总额已变更或会话即将过期，旧的 Cashfree 订单将被关闭并创建新订单，因此同一订单不会被付款两次。若订单已在 Cashfree 付款成功但未被记录，下一次尝试会记录该笔付款，而不会再次扣款。
若 Cashfree 无法发起付款，顾客会看到 We could not start the Cashfree payment. Please try again or choose another payment method. 技术原因会写入日志。订单总额低于 Cashfree 最低金额（该币种的 1 个单位；BHD、JOD、KWD、OMR 为 0.01，TND 为 0.1）时，无法使用 Cashfree 付款。
该付款方式支持经典结账、结账区块以及 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。面向顾客的文字已提供印地语翻译。
插件仅在 Cashfree 结账页面上处理一次性付款。不支持保存银行卡、订阅或定期付款，不支持单独的授权与扣款，不支持 Cashfree 优惠组件、通过 Cashfree 的货到付款（COD）或付款链接，也不支持货币换算：订单以订单币种扣款。
订单与退款
订单状态
Pending payment: 顾客已被转到 Cashfree 但尚未付款，或付款仍在银行处理中。顾客带着待处理的付款返回时，备注会说明插件正在等待 Cashfree 的 Webhook。
Processing: 付款已确认（仅包含虚拟可下载商品的订单会变为已完成，即 WooCommerce 默认行为）。订单备注会显示 Cashfree 交易 ID 和付款方式类别。订单的交易 ID 即为 Cashfree 付款 ID。订单取消后才到达的付款仍会被记录，因为款项已经收取。
On hold: Cashfree 报告的已付金额或币种与订单总额不符。订单备注会显示应付与实收金额以及交易 ID。请在 Cashfree 后台核对该笔付款，并手动完成订单或退款。
Failed: 付款在 Cashfree 处失败或被取消。备注会显示 Cashfree 的状态和原因。每次额外的失败尝试都会添加一条备注。
已付款的订单绝不会因后续的 Webhook 或返回而被改回。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Cashfree Payments（按钮显示付款方式名称）。支持全额和部分退款。退款会发送至已付款的 Cashfree 订单，并使用其付款时所在的环境（测试环境或正式环境）的密钥，因此必须已设置该环境的密钥。若 Cashfree 未接受退款，或将其报告为已取消或被拒绝，WooCommerce 会显示错误，且不会记录退款。已发起的退款会以订单备注的形式添加，包含退款 ID、金额和状态。最终状态将通过退款 Webhook 以另一条订单备注的形式送达。
退款状态 Webhook 仅以备注形式添加，不会自动记录为 WooCommerce 退款。
许可证密钥
本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Cashfree Payments 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Cashfree。若仍发起付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍可看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常使用。
许可证到期后，插件仍可继续使用，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时未显示 Cashfree：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否已填写密钥：测试环境模式下为 Sandbox App ID 和 Sandbox Secret Key，正式模式下为 App ID 和 Secret Key。若订单总额低于 Cashfree 最低金额，该付款方式同样会隐藏。缺少密钥时，设置页面会显示警告。
付款已完成，但订单仍为待付款：Webhook 未正常工作。请检查您的站点是否使用 HTTPS，Developers > Webhooks 中的 URL 是否与设置中显示的地址完全一致，以及是否已勾选 Payment 事件。另请确认设置中的 Secret Key 属于该订单付款时所在的环境。顾客付款后返回店铺时，以及下一次付款尝试时，订单也会得到确认。
Webhook 返回 Missing signature 或 Invalid signature：该调用未携带有效的 Cashfree 签名，或设置中的 Secret Key 与订单创建时所在的环境不符。Cashfree 会重试该 Webhook。
Webhook 返回 Ignored：该 Webhook 签名正确，但所属订单并非由本店铺创建，例如同一 Cashfree 账户下的其他店铺。请为每家店铺设置各自的 Order ID prefix。
Webhook 返回 Busy, retry later：该订单在同一时刻正被另一请求处理。Cashfree 会重试该 Webhook。
顾客看到 The Cashfree payment page could not be loaded：Cashfree 脚本未能在浏览器中加载，例如被拦截程序阻止。顾客可再次点击 Pay Now，或点击 Choose another payment method。
顾客看到 We could not start the Cashfree payment：请开启 Debug log，并查看 WooCommerce > Status > Logs 中来源为 wcp_cashfree_payment 的日志。常见原因是所选模式的密钥有误，或您的 Cashfree 账户未启用该币种。
顾客看到 The minimum amount for a Cashfree payment is …：订单总额低于该币种的 Cashfree 最低金额。
顾客看到 We could not verify the payment：返回链接与订单不匹配。若款项已被扣除，Webhook 仍会确认该订单。请在顾客再次付款前，先在 Cashfree 后台核对该笔付款。
付款后订单为保留状态：请阅读订单备注。已付金额或币种与订单不符。请完成订单或对该付款退款。
退款失败，提示与测试环境或正式环境相关：该订单是在该环境中付款的，但其 API 密钥未设置。请填入密钥后重试。
许可证区块显示错误：请按照区块中的提示操作。例如，若该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now，为新域名激活密钥。若无法连接许可证服务器，插件将继续使用最后已知的状态。
卸载
停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被移除。仅当开启了 Delete Data on Uninstall 时，网关设置、订单上存储的 Cashfree 数据以及日志才会被移除。否则它们将保留，以便日后重新安装时使用。现有订单保留其付款备注和交易 ID。
Cashfree 是其各自所有者的商标。本插件与 Cashfree 无关联，也未获得 Cashfree 认可。