VibeFox Cashfree for OpenCart — 帮助

要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

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

Cashfree 账户：您需要 Cashfree 账户的 App ID 和 Secret Key，测试（沙盒）环境和正式环境各需一套，并且需要在 Cashfree 商户后台（Merchant Dashboard）中配置一个 Webhook（见配置）。Secret Key 同时用于验证 Webhook，因此没有单独的 Webhook 密钥。订单货币必须已在您的 Cashfree 账户中启用。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_cashfree_payment-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_cashfree_payment.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在管理后台中进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_cashfree_payment-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录中。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Cashfree Payments，然后点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 里，然后点击 Activate（参见许可证密钥）。

4. 填写 Sandbox App ID 和 Sandbox Secret Key，在 Cashfree 商户后台添加 Webhook（见配置），开启 Enable/Disable，点击 Save 并测试一笔付款。

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

OpenCart 4

1. 在管理后台中进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_cashfree_payment.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Cashfree Payments，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 请按照 OpenCart 3 步骤 3 至 5 输入许可证密钥、Cashfree 密钥和 Webhook。两个版本的设置页面及其字段完全相同，只有 Webhook URL 不同（参见 Webhook）。

新安装的扩展默认关闭付款方式，并开启沙盒模式。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Cashfree Payments > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会说明只有在 Cashfree 确认付款后，订单才会获得状态。启用付款方式后，如果所选模式的 API 密钥缺失，页面会发出警告（此时该付款方式在结账时隐藏）；在沙盒模式开启时，页面会显示 Sandbox mode is on: customers see a test checkout and no real money is charged. 如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不能为空（最多 128 个字符），API Version 必须是列出的版本之一，Sort Order 必须是整数，Total 必须是 0 或更大的数字，并且地区区域和订单状态必须存在；否则不会保存任何内容。如果在没有所选模式密钥的情况下保存已启用的付款方式，设置会附带警告保存，提示在设置这些密钥之前，该付款方式在结账时将保持隐藏。

Cashfree Payments

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

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

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Sort Order：Cashfree 在结账时的付款方式中的位置。留空或输入整数。

Geo Zone：仅向所选地理区域内的付款地址提供 Cashfree。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的、以商店默认货币计算的结账金额，达到后才会提供 Cashfree。留空则对任何金额都提供 Cashfree。低于该货币 Cashfree 最低金额（1 个单位；三位小数货币为 0.01 或 0.1）的金额永远不会提供。

模式和 API 密钥

在 Cashfree 商户后台的 Developers > API Keys 中获取 App ID 和 Secret Key（页面中有链接）。测试密钥和正式密钥是不同的。

Sandbox Mode：使用 Cashfree 沙盒进行测试。不会收取真实款项，并且 Confirm Order 步骤和付款页面会显示 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。

已保存的 Secret Key 不会再次显示。该字段保持为空，并显示 已保存 — 留空即可保留。 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved value on save，然后点击 Save。

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

Webhook

Webhook 会告知您的商店某笔付款已完成、失败或已退款。在 Cashfree 商户后台中进入 Developers > Webhooks，添加本节 Webhook URL 中显示的 URL，并选择 Payment 和 Refund 事件。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_cashfree_payment/webhook，在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_cashfree_payment/payment/wcp_cashfree_payment.webhook，由您的 OpenCart 安装的前台商店地址生成。请完全按照设置中显示的内容复制该 URL。在使用 HTTPS 的商店中，扩展还会在每笔付款时将此 URL 传递给 Cashfree。如果您的商店未使用 HTTPS，本节会显示警告。

扩展会处理以下事件（它们也列在本节中）：

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

订单

OpenCart 在 Confirm Order 步骤中创建的订单没有状态（缺失订单）。只有在 Cashfree 确认付款之后，订单才会获得状态。付款失败或被放弃时，订单保持无状态，购物车会保留。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：付款确认且金额和货币匹配后设置的状态。默认：处理中。

On Hold (Review) Status：Cashfree 报告的已付金额或货币与订单总额不符。备注会显示预期金额和实收金额。默认：待处理，因为 OpenCart 没有搁置状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Refunded Status：在订单页面中全额退款付款后设置。默认：已退款。

高级

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

Order ID prefix：Cashfree 订单 ID 的格式为前缀 + OpenCart 订单 ID；同一订单的新尝试会在末尾加上编号（例如 123-2）。留空则使用本商店的自动前缀，该前缀显示在字段说明中（OC，即由商店地址派生的四个字母加一个连字符）。对于连接到同一 Cashfree 账户的每个商店，请使用不同的前缀。仅允许字母、数字、“_”和“-”，最多 20 个字符。其他字符会在保存时被移除并给出警告。

Debug log：错误始终会被记录。开启后，Cashfree API 调用和 Webhook 也会写入 OpenCart 日志文件夹（storage/logs）中的 cashfree_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会进行轮转。密钥和顾客数据永远不会被记录。默认：关闭。

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

Delete Data on Uninstall：开启后，卸载扩展会删除 Cashfree 设置和扩展日志。订单及其 Cashfree 交易和退款始终保留。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。Secret Key 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 Secret Key 将被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Cashfree Payments）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 您将被重定向到 Cashfree 结账页面，安全付款（银行卡、UPI、网银、电子钱包）。 OpenCart 会在此步骤创建订单，但仍没有状态。当顾客点击 Confirm Order 时，扩展会以订单货币为订单总额创建一个 Cashfree 订单，并打开一个 Cashfree payment 页面，显示 正在重定向到 Cashfree 进行付款... 并加载 Cashfree 结账页面。如果页面没有自动打开，顾客可以点击 Pay Now。在 Cashfree 结账页面中，顾客可以使用您 Cashfree 账户中启用的任何方式付款，例如银行卡、UPI、网银或电子钱包。顾客的电子邮件和电话号码会传递给 Cashfree。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。OpenCart 4 默认不要求电话号码：如果订单中没有电话号码，确认区块会显示一个可选的 Phone 字段（可选：用于 Cashfree（UPI、OTP）的付款人电话号码。）。格式错误时会显示 请输入有效的电话号码（10 位数字，或 + 加国家代码），或将该字段留空。 该号码会在下一次尝试时被记住。

付款后，顾客返回您的商店。只有在 Cashfree 确认之后，订单才会被标记为已付款：通过已签名的 Webhook，或顾客返回时由服务器向 Cashfree 发起的请求。随后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。即使在其他浏览器中，返回也能正常工作，例如顾客从 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 就会设置订单状态。在 OpenCart 4 中，Cashfree 将顾客送回时浏览器不会发送商店会话，因此扩展会先显示一个短暂页面，从您的商店重新打开同一返回地址：顾客会保留购物车和登录状态。

如果付款失败或顾客在未付款的情况下离开了 Cashfree 页面，顾客会返回结账页面，并显示 Cashfree 付款未完成。请重试或选择其他付款方式。 在 OpenCart 4 中，结账消息会显示在结账页面上方。订单保持无状态，购物车会保留。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则为结账保留一个订单并更新它，因此顾客会对同一订单再次付款。如果金额未变且剩余时间超过五分钟，则会复用同一订单仍处于打开状态的 Cashfree 付款；否则，旧的 Cashfree 订单会被关闭，并创建新的订单。同一购物车之前订单中仍处于打开状态的 Cashfree 付款也会被关闭，因此该购物车无法被重复付款。如果购物车已在 Cashfree 付款但未被记录，下一次尝试会确认该付款，而不会再次扣款。已由其他订单付款的购物车不会再次扣款：顾客会进入成功页面。如果同一购物车仍然被付款两次（例如两个浏览器标签页同时付款），第二个订单保持无状态，已付款的订单会获得一条备注，提示顾客可能被重复扣款，以便您在 Cashfree 后台将其退款。

OpenCart 4 会将订单保留在结账流程中，直到显示成功页面。如果该订单在此期间被关闭（例如已取消），并且 Cashfree 没有为其保留款项，顾客会被带回结账页面，并显示 Cashfree 付款未完成。请重试或选择其他付款方式。，下一次点击 Confirm Order 时将为购物车中的新订单付款。如果订单已有状态，且此后购物车发生了变化（其他商品或数量），顾客会被带回结账页面，并显示 您之前的订单已提交。请再次确认订单：当前购物车将通过新订单付款。

如果 Cashfree 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到 无法发起 Cashfree 付款。请重试或选择其他付款方式。 技术原因会被写入日志。低于 Cashfree 最低金额的订单总额（货币的 1 个单位；KWD 等三位小数货币为 0.01，TND 为 0.1）无法通过 Cashfree 付款，并且对该订单不会显示此付款方式。

即使商店处于维护模式，Webhook 也会正常工作：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会添加一个启动操作，使 Webhook 和顾客的返回请求得以通过。

该扩展仅在 Cashfree 结账页面中接受一次性付款。它没有保存的银行卡、订阅或定期付款，没有单独的授权和扣款，没有 Cashfree 优惠组件，不支持通过 Cashfree 的货到付款或付款链接，也不进行货币转换：订单以订单货币扣款。

订单和退款

订单状态

无状态（缺失订单）：顾客已被转到 Cashfree，但尚未付款，付款失败，或者银行中的付款仍在处理中。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Order Status After Payment（默认 处理中）：付款已确认。备注会显示 Cashfree 交易 ID 和付款方式分组（例如 upi 或 credit_card）。

On Hold (Review) Status（默认 待处理）：Cashfree 报告的已付金额或货币与订单总额不符。备注会显示预期金额、实收金额和交易 ID。请在 Cashfree 后台核对付款，然后完成订单或退还付款。

Refunded Status（默认 已退款）：付款已通过该扩展全额退款。

如果您在等待中的订单上手动设置了状态（例如已取消）之后，又收到了付款，该付款仍会被记录，订单也会变为已付款，因为款项已经收取；OpenCart 会通知顾客这一变化。已付款的订单绝不会因为之后的失败付款而改回去，对已付款订单的第二次付款也不会改变其状态。

备注是订单 History 中的记录，顾客看不到。

VibeFox Cashfree Payments 选项卡

在 Sales > Orders 中打开一个通过 Cashfree 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Cashfree Payments 选项卡会显示 Transaction ID（沙盒付款会带有 Sandbox 标签）、Cashfree order、付款的 Status、Paid / refunded 金额、退款表单、每笔退款状态的退款历史，以及该订单的 Cashfree notes。该选项卡仅向有权访问此扩展的用户显示。

退款

在该选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Cashfree。确认提示 Refund this amount through Cashfree? This cannot be undone. 支持全额退款和部分退款。您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。退款以 Cashfree 扣款的金额和货币进行，因此在金额不一致的情况下，您可以退款至顾客实际支付的金额，而非订单总额。退款会发送到已付款的 Cashfree 订单，并使用付款时所在环境（沙盒或正式）的密钥，因此必须设置该环境的密钥。如果 Cashfree 不接受退款，或将其报告为已取消或被拒绝，选项卡会显示错误，且不会记录任何退款。已发起的退款会连同其退款 ID、金额和状态一起添加到退款历史和备注中。全额退款会将订单设置为 Refunded Status，但不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。退款在 Cashfree 确认付款后即可使用。

最终退款状态会通过退款 Webhook 到达，并添加到备注中。Sales > Returns 中的商品退货不会通过 Cashfree 退回款项。

许可证密钥

该扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Cashfree Payments 是 Extensions > Extensions > Payments > VibeFox Cashfree Payments > Edit 中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除该密钥）。其下方有 Product: opencart-payment-cashfree 一行，以及打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随管理后台语言显示（包含英语和俄语）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或者 License expired on 加上日期。商店地址更改后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 Cashfree。如果仍然启动了付款，顾客会看到 此付款方式不可用。请选择其他付款方式。 在同一浏览器中登录管理后台的管理员用户，仍然可以在商店中看到该付款方式，并标有 （未授权 — 仅管理员可见），因此您可以在购买密钥之前设置和测试该扩展。在 OpenCart 4 中没有此预览：商店无法看到管理后台的登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开过一次 Edit 页面后，管理后台的 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已经开始的付款仍会被确认，退款也正常工作。

许可证过期后，扩展仍会继续工作，但更新和支持需要续订。打开管理后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

Cashfree 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式是否已配置密钥：沙盒模式下为 Sandbox App ID 和 Sandbox Secret Key，正式模式下为 App ID 和 Secret Key。缺少密钥时，设置页面会显示警告。订单总额低于 Cashfree 最低金额时，也会隐藏该付款方式。另外请检查付款地址是否位于所选 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Webhook 没有生效。请检查您的商店是否使用 HTTPS，Developers > Webhooks 中的 URL 是否与 Webhook URL 中显示的完全一致，以及是否选择了付款事件。检查设置中的 Secret Key 是否属于付款所在的环境。Cashfree 后台会显示您的商店对每个 Webhook 的响应。顾客付款后返回商店时，以及同一购物车的下一次付款尝试时，订单也会获得状态。

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

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

Webhook 返回 Busy, retry later：订单在同一时刻正被另一个请求确认，或者无法设置订单状态。Cashfree 会重试该 Webhook。请开启 Debug log 查看原因。

顾客看到「无法加载 Cashfree 付款页面。请重试。」：Cashfree 脚本无法在浏览器中加载，例如因为被拦截程序阻止。顾客可以再次点击 Pay Now，或选择 Choose another payment method。

顾客看到「无法发起 Cashfree 付款」：请查看扩展页面上的 Log 字段。典型原因是所选模式的密钥错误，或 Cashfree 账户中未启用该货币。

顾客在 Confirm Order 之后看到「此付款方式不可用。」：结账会话已与订单不匹配，或者付款方式已被关闭。顾客需重新加载结账页面。

顾客看到「未找到付款会话。请重试。」：付款页面链接不属于本商店的付款，或 Cashfree 会话已结束。顾客需重新确认订单。

顾客看到「无法验证付款」：返回链接与付款不匹配。如果已扣款，Webhook 仍会确认订单。在顾客再次付款之前，请先在 Cashfree 后台检查该付款。

付款后订单处于审核状态：请阅读 VibeFox Cashfree Payments 选项卡中的备注（见订单状态），然后完成订单或退还付款。

选项卡中没有退款表单：选项卡会说明原因：付款尚未确认、已全额退款、您的用户组没有修改该扩展的权限，或者该付款所在环境的 API 密钥未设置。

退款失败并显示与沙盒或正式模式有关的信息：付款是在该环境中完成的，但其 API 密钥未设置。请输入这些密钥后重试。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Cashfree Payments 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。在 OpenCart 4 中，扩展的事件以及在维护模式下允许 Webhook 通过的启动操作也会被移除。如果 Delete Data on Uninstall 已开启，则其他 Cashfree 设置（标题、描述、模式、密钥、API 版本、订单 ID 前缀、日志记录）和日志都会被删除。如果已关闭，它们将被保留，以便之后重新安装时使用。Cashfree 交易和退款始终会保留，因此之前付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Cashfree Payments 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

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