VibeFox Cashfree for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

HTTPS：Cashfree 仅向 https:// 地址发送 Webhook。没有 HTTPS 时，顾客返回店铺后付款仍会得到确认，但正式上线前请启用 HTTPS。

Cashfree 账户：您需要 Cashfree 账户的 App ID 和 Secret Key，测试环境（沙盒）和正式环境各一套，还需要在 Cashfree Merchant Dashboard 中配置一个 Webhook（参见配置）。Secret Key 同时用于验证 Webhook，因此不存在单独的 Webhook 密钥。购物车币种必须已在您的 Cashfree 账户中启用。

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

安装

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

2. 上传完成后，点击 Configure，或稍后在模块列表中找到 VibeFox Cashfree Payments 并点击 Configure。

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

4. 输入 Sandbox App ID 和 Sandbox Secret Key，在 Cashfree Merchant Dashboard 中添加 Webhook（参见配置），开启 Enable/Disable，点击 Save，然后测试一笔付款。

5. 准备就绪后，输入正式环境的 App ID 和 Secret Key，关闭 Sandbox Mode，然后点击 Save。

安装时，模块会创建订单状态 Cashfree payment on hold。PrestaShop 会为所有币种、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中限制它们。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Cashfree Payments > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，页面会说明订单只会在 Cashfree 确认付款后才创建。启用付款方式后，如果所选模式的 API 密钥缺失，页面会发出警告（此时付款方式会在结账时隐藏），并且在沙盒模式开启时显示 Sandbox mode is on: customers see a test checkout and no real money is charged. 如果您保存了已启用的付款方式，但没有所选模式的密钥，警告会提示在密钥填写完成之前，该付款方式将在结账时保持隐藏。

Cashfree Payments

Enable/Disable：Enable Cashfree Payments 用于开启或关闭付款方式。默认：off。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Cashfree Payments。必填。

Description：结账时显示在付款方式下方的文字。默认：Pay securely via Card, UPI, Net Banking, Wallet via Cashfree。

Mode and API keys

请在 Cashfree Merchant Dashboard 的 Developers > API Keys 下获取 App ID 和 Secret Key。测试密钥和正式密钥不同。

Sandbox Mode：使用 Cashfree 沙盒环境进行测试。不会扣除真实款项，结账时付款方式下方会显示 SANDBOX MODE - no real payments will be processed. 默认：on。正式付款时请关闭。

Sandbox App ID：Cashfree 测试环境的 App ID。

Sandbox Secret Key：Cashfree 测试环境的 Secret Key。

App ID：Cashfree 正式环境的 App ID。

Secret Key：Cashfree 正式环境的 Secret Key。

已保存的 Secret Key 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved secrets：勾选某个 Secret Key，然后点击 Save 即可将其删除。字段留空则保留已保存的值。

付款会保留其创建时所在的环境。其 Webhook 会使用该环境的密钥进行验证，状态也会使用该环境的密钥进行查询，退款同样使用该环境的密钥发送。因此，在切换到正式环境后，请保留沙盒密钥，直到沙盒付款全部结算完毕。

Webhook

Webhook 会告知您的店铺某笔付款已完成、失败或已退款。在 Cashfree Merchant Dashboard 中进入 Developers > Webhooks，添加本节 Webhook URL 中显示的地址，并勾选 Payment 和 Refund 事件。使用友好 URL 时，地址形如：https://your-shop/module/wcp_cashfree_payment/webhook。请完全按照设置中显示的内容复制该地址。在 HTTPS 店铺上，模块每次付款时也会将此地址传给 Cashfree。如果您的店铺未使用 HTTPS，本节会显示警告。

模块会处理以下事件（本节也列出了这些事件）：

Cashfree 会使用您的 Secret Key 为每个 Webhook 签名。没有有效签名的 Webhook 会被拒绝。Webhook 必须使用付款所在环境的 Secret Key 签名，因此沙盒密钥绝不会确认正式付款。对于并非由本店铺发起的付款（例如同一 Cashfree 账户下的其他店铺）的已签名 Webhook，会被确认接收并忽略。如果没有 Webhook，只有在顾客付款后返回店铺时才会创建订单。如果顾客在付款后关闭了浏览器，那么只有 Webhook（或同一购物车的下一次付款尝试）才能创建订单。

Advanced

API Version：要使用的 Cashfree API 版本。

Order ID prefix：Cashfree 订单 ID 由前缀 + PrestaShop 购物车 ID 组成；同一购物车的新尝试会在末尾获得一个编号（例如 123-2）。如果要使用本店铺的自动前缀（显示在字段说明中），请留空。连接到同一 Cashfree 账户的每家店铺都应使用不同的前缀。仅允许字母、数字、“_”和“-”，最多 20 个字符。保存时，其他字符会被删除并给出警告。

Debug log：错误始终会被记录。开启后，Cashfree API 调用和 Webhook 还会写入模块文件夹中的 logs/cashfree_p_debug.log.php。该文件无法通过网页访问。密钥和顾客数据绝不会被记录。默认：off。

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

Delete Data on Uninstall：开启后，卸载模块会删除 Cashfree 设置和模块日志。订单、其 Cashfree 交易和退款以及 Cashfree payment on hold 订单状态始终会保留，因此现有订单仍可正常使用。默认：off。

结账

在付款步骤中，顾客选择付款方式（默认为 Cashfree Payments）并确认。模块会按购物车币种为购物车总额创建 Cashfree 订单，并打开一个付款页面，显示 Redirecting to Cashfree for payment... 并加载 Cashfree 付款页面。如果页面没有自动打开，顾客可以点击 Pay Now。在 Cashfree 付款页面上，顾客可以使用您 Cashfree 账户中启用的任何方式付款，例如银行卡、UPI、网上银行或电子钱包。顾客的电子邮件和账单电话会传给 Cashfree。此时尚未创建任何订单。

付款后，顾客返回您的店铺。只有在 Cashfree 确认付款后，订单才会被标记为已付款：通过已签名的 Webhook，或在顾客返回时由服务器向 Cashfree 发出请求来确认。随后订单会被创建，顾客会看到标准的订单确认页面。即使在另一个浏览器中返回，也同样有效，例如顾客从 UPI 应用中返回时。如果银行尚未确认付款，Payment confirmation 页面会显示 Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. 以及 Check again 按钮；银行一旦确认付款，Webhook 就会创建订单。

如果付款失败，或顾客离开 Cashfree 页面而未付款，顾客会返回结账页面，并看到 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 付款，并且该购物车不会显示此付款方式。

即使店铺处于维护模式，Webhook 仍然有效，也不受店铺国家限制的影响。

本模块仅在 Cashfree 付款页面上接受一次性付款。不支持保存银行卡、订阅或定期付款，不支持单独的授权与扣款，不支持 Cashfree 优惠组件、通过 Cashfree 的货到付款（COD）或付款链接，也不支持货币换算：购物车将以购物车币种扣款。

订单与退款

Order statuses

No order yet：顾客已被引导至 Cashfree，但尚未付款；付款失败；或付款仍在银行处理中。此时只存在购物车。

Payment accepted：付款已确认。付款会以 Cashfree 付款 ID 作为交易 ID 记录，备注中会显示交易 ID 和付款方式分组（例如 upi 或 credit_card）。

Cashfree payment on hold：Cashfree 报告的已付金额或币种与购物车总额不一致（例如，付款开始后，购物车在另一个标签页中被修改）。备注会显示预期金额、实收金额和交易 ID。请在 Cashfree Dashboard 中核对付款，然后完成订单或退款。

Refunded：付款已通过模块全额退款。

如果付款在订单取消后才到账，仍会被记录，订单会重新变为已付款，因为款项已经扣除。已付款的订单绝不会因为之后失败的付款而被改回未付款状态。

Cashfree payment block

订单页面会显示一个 Cashfree payment 区块，包括交易 ID、Cashfree 订单、付款状态、已付和已退金额、沙盒付款的 Sandbox 标记、退款记录，以及订单的 Cashfree notes。

Refunds

在 Cashfree payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Cashfree。确认提示 Refund this amount through Cashfree? This cannot be undone. 支持全额和部分退款。您需要拥有编辑订单的权限；不需要访问模块页面的权限。退款以 Cashfree 实际扣款的金额和币种进行，因此在金额不一致的情况下，您可以退还的最高金额是顾客实际支付的金额，而不是订单总额。退款会发送到已付款的 Cashfree 订单，并使用该付款所在环境（沙盒或正式）的密钥，因此必须已填写该环境的密钥。如果 Cashfree 不接受退款，或将其报告为已取消或被拒绝，该区块会显示错误，并且不会记录任何退款。已发起的退款会连同其退款 ID、金额和状态一起添加到退款记录和备注中。全额退款会将订单设为 Refunded；部分退款不会更改状态。Cashfree 确认付款后，退款功能才可用。

最终的退款状态通过退款 Webhook 送达，并会添加到备注中。模块不会生成信用单。订单页面上 PrestaShop 的标准退款按钮不会通过 Cashfree 退回款项。

许可证密钥

本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Cashfree Payments 许可证区块位于 Modules > Module Manager > VibeFox Cashfree Payments > Configure 页面的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效截止日期和您的域名），以及按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: presta-payment-cashfree 一行和 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 账户中释放该名额。

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

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

故障排除

Cashfree 未出现在结账页面：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否已配置密钥：沙盒模式下需要 Sandbox App ID 和 Sandbox Secret Key，正式模式下需要 App ID 和 Secret Key。缺少密钥时，设置页面会显示警告。购物车总额低于 Cashfree 最低金额时，付款方式也会被隐藏。在 Payment > Preferences 中，请检查该模块是否允许购物车币种、顾客所在国家和顾客群组。

付款已完成，但没有创建订单：Webhook 不工作。请检查您的店铺是否使用 HTTPS，Developers > Webhooks 中的地址是否与 Webhook URL 中显示的地址完全一致，以及是否已选择 Payment 事件。请检查设置中的 Secret Key 是否属于付款所在的环境。Cashfree Dashboard 会显示您的店铺对每个 Webhook 的响应。顾客付款后返回店铺时，以及同一购物车的下一次付款尝试时，也会创建订单。

Webhook 返回 Missing signature 或 Invalid signature：该请求没有有效的 Cashfree 签名，或者设置中的 Secret Key 与付款所在环境不匹配。请检查沙盒密钥和正式密钥是否被调换。

Webhook 返回 Ignored：Webhook 签名正确，但它属于并非由本店铺发起的付款，例如同一 Cashfree 账户下的另一家店铺。请为每家店铺设置各自的 Order ID prefix。

Webhook 返回 Busy, retry later：订单正在被另一个请求同时创建，或者订单无法创建（例如模块已禁用）。Cashfree 会重试该 Webhook。请开启 Debug log 以查看原因。

顾客看到 The Cashfree payment page could not be loaded：Cashfree 脚本无法在浏览器中加载，例如被拦截程序阻止。顾客可以再次点击 Pay Now，或点击 Choose another payment method。

顾客看到 We could not start the Cashfree payment：请查看模块页面上的 Log 字段。常见原因包括所选模式的密钥错误，或者币种未在您的 Cashfree 账户中启用。

顾客看到 We could not verify the payment：返回链接与购物车不匹配。如果已扣款，Webhook 仍会创建订单。请在顾客再次付款之前，在 Cashfree Dashboard 中核对该付款。

付款后订单显示为 Cashfree payment on hold：请阅读 Cashfree payment 区块中的备注（参见 Order statuses），然后完成订单或退款。

退款失败，并显示与沙盒或正式模式相关的消息：付款是在该环境中完成的，但其 API 密钥尚未填写。请填写密钥后重试。

卸载

进入 Modules > Module Manager，打开 VibeFox Cashfree Payments 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，Cashfree 设置和日志将被删除。如果已关闭，则保留所有设置，以便日后重新安装。Cashfree 交易和退款以及 Cashfree payment on hold 订单状态始终会保留，因此即使重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。

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