VibeFox CCAvenue for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本，并启用 OpenSSL 扩展（用于加密请求和解密响应）。

CCAvenue 账户：您需要一个 CCAvenue 商户账户，并具备 Merchant ID、Access Code 和 Working Key。Access Code 和 Working Key 是针对某个网站域名颁发的，因此请为本店的域名生成它们。CCAvenue 在测试环境中使用相同的凭据；测试访问权限必须由 CCAvenue 为您的账户启用。本扩展使用 CCAvenue India 的端点。

货币：订单货币会原样发送给 CCAvenue。CCAvenue 账户默认接受 INR；其他货币需要在您的 CCAvenue 账户上启用多币种处理。

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

安装

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

OpenCart 3

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

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

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

4. 从您的 CCAvenue 控制面板中输入 Merchant ID、Access Code 和 Working Key，开启 Enable/Disable，然后点击 Save。

5. 测试时保持 Test mode 开启，之后再关闭以接受真实付款。无需在 CCAvenue 控制面板中进行任何设置：每笔付款都会发送返回地址。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 步骤 3 至 5 的方式输入许可证密钥和 CCAvenue 凭据。两个版本的设置页面及其字段相同。只有返回 URL 不同（参见返回 URL）。

新安装默认关闭支付方式，并开启测试模式。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox CCAvenue Payment > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当 CCAvenue 已启用但缺少 Merchant ID、Access Code 或 Working Key 时，页面会发出警告（此时支付方式会在结账时隐藏，直到三者都已填写）；当支付方式在测试模式下启用时，页面会显示 CCAvenue test mode is on: customers are sent to test.ccavenue.com and no real money is taken.；当商店默认货币不是 INR 时，页面还会提醒您启用多币种处理。如果没有修改扩展的权限，页面只显示设置，无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数，Total 必须为 0 或更大的数字，并且地理区域和订单状态必须存在；否则不会保存任何内容。

CCAvenue

Enable/Disable：Enable CCAvenue Payment Gateway 用于开启或关闭该支付方式。默认：关闭。

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

Description：在 Confirm Order 步骤中、确认按钮上方向顾客显示的文字。默认：Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue。

Sort Order：CCAvenue 在结账时支付方式中的排列位置。留空或输入整数。

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

Total：订单必须达到的结账总额（以商店默认货币计算），才会提供 CCAvenue。留空则对任何总额都提供 CCAvenue。

API 凭据

登录您的 CCAvenue 商户控制面板（M.A.R.S.），打开 Settings > API Keys。为本店的域名生成 Access Code 和 Working Key。保存时会删除凭据中的空格。

Merchant ID：您的 CCAvenue 数字 Merchant ID。如果其中包含数字以外的字符，保存时会显示 CCAvenue: the Merchant ID must contain digits only — the previous value was kept.，之前保存的值保持不变，其他设置仍会保存。

Access Code：本网站的 Access Code（Settings > API Keys）。

Working Key：本网站的 Working Key（加密密钥）。它用于加密付款请求，也是验证 CCAvenue 响应的唯一方式，因此请务必保密。已保存的 Working Key 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。若要删除，请勾选字段下方的 Clear saved Working Key，然后点击 Save。

Test mode：将顾客引导至 CCAvenue 测试环境（test.ccavenue.com）。CCAvenue 在测试和正式环境中使用相同的 Merchant ID、Access Code 和 Working Key；测试访问权限必须由 CCAvenue 为您的账户启用。在测试模式下，Confirm Order 步骤会显示 TEST MODE: no real transactions will be processed. 默认：开启。进行真实付款时请关闭。

返回 URL

CCAvenue 会将顾客返回到本节显示的地址。在 OpenCart 3 中该地址形如 https://your-store/index.php?route=extension/payment/wcp_ccavenue_payment/back，在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_ccavenue_payment/payment/wcp_ccavenue_payment.back，由您的 OpenCart 安装的商店前台地址生成。扩展会在每笔付款中发送此 URL（作为重定向和取消 URL），因此无需在 CCAvenue 中进行任何配置。该 URL 必须属于在 CCAvenue 注册的域名。

订单

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（即缺失订单）。只有在验证了 CCAvenue 的加密响应后，订单才会获得状态。付款失败或被取消时，订单保持无状态，顾客将返回结账页面，购物车会被保留。以下每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：付款成功（CCAvenue 状态为 Success，金额和货币已验证）。默认：处理中。

Awaiting Payment Status：Awaited：银行尚未确认付款。当 CCAvenue 针对同一 tracking ID 报告 Success 时，订单将获得 Order Status After Payment。默认：待付款。

On Hold (Review) Status：CCAvenue 报告的金额或货币与订单总额不一致，或者付款到达时订单已被取消。备注中会说明情况。默认：待付款，因为 OpenCart 没有保留状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Payment Status：待处理的付款随后被中止（同一 tracking ID 的 Aborted）。默认：已取消。

Failed Payment Status：待处理的付款随后失败（同一 tracking ID 的 Failure、Invalid 或 Timeout）。较早尝试的失败不会改变订单。默认：失败。

高级

Debug log：将 CCAvenue 事件写入 OpenCart 日志文件夹（storage/logs）中的 ccavenue_p_debug.log.php。该文件无法通过网页打开。仅记录订单编号、tracking ID 和状态；密钥、卡数据、电子邮件和地址不会被记录。默认：关闭。关闭时不会写入任何内容，包括错误。

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

Delete data on uninstall：开启后，卸载扩展会删除扩展设置和日志。订单和 CCAvenue 付款参考会保留，因此重新安装后，旧付款的延迟返回仍会被处理。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择支付方式（默认为 CCAvenue）。在 Confirm Order 步骤中，顾客会看到您的描述。OpenCart 在此步骤创建订单，此时仍没有状态。当顾客点击 Confirm Order 时，该步骤会显示 Thank you for your order. You are being redirected to CCAvenue to complete the payment.，并将顾客带到 CCAvenue 付款页面。浏览器跳转期间，会显示 Pay via CCAvenue 按钮。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

每次尝试都会生成新的 CCAvenue 订单参考，由 OpenCart 订单号和时间组成。订单总额和货币、账单信息、配送地址（当订单需要发货且配送地址与账单地址不同时）以及该次尝试的一个机密令牌都会包含在加密请求中。姓名和地址会被整理为 CCAvenue 可接受的字符和长度；国家和省/州以名称形式发送，电话仅以数字形式发送。顾客在 CCAvenue 页面上选择银行卡、Net Banking、UPI、钱包或 EMI。OpenCart 4 默认不要求付款地址；此时账单信息取自配送地址。

付款后，CCAvenue 会携带加密响应将顾客带回。只有在 CCAvenue 确认后，订单才会被标记为已付款：响应必须能用您的 Working Key 解密，属于本店的某次尝试，并且金额和货币与发送的内容及订单总额一致。随后，订单会按照 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存；顾客会看到 OpenCart 订单成功页面，其中显示 Your CCAvenue payment has been received. 对于 Awaited 付款，页面显示 Your CCAvenue payment is awaiting confirmation from your bank. The order will be processed as soon as the payment is confirmed. 如果金额或货币不一致，页面显示 Your payment was received and is being reviewed by the store. 在 OpenCart 4 中，顾客被 CCAvenue 送回时浏览器不会发送商店会话，因此应用响应后，扩展会显示一个简短页面，从您的商店重新打开返回地址：顾客保留购物车和登录状态。

如果付款失败，顾客会返回结账页面，并显示 Payment was not completed. Please try again or choose a different payment method. 如果顾客在 CCAvenue 页面上取消，消息为 Payment was cancelled. You may try again. 如果无法验证响应，消息为 We could not confirm the payment result. If your account was charged, please contact us before paying again. 在 OpenCart 4 中，这些消息显示在结账页面上方。在这些情况下，订单保持无状态，购物车会被保留，因此顾客可以再次付款。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 则为结账保留一个订单并更新它。每次尝试都有自己的 CCAvenue 订单参考。CCAvenue 无法取消已开始的付款，因此较早尝试的延迟成功付款仍会应用到其自己的订单上。同一购物车只支付一次：已被其他订单支付的购物车不会再次发送到 CCAvenue（顾客会进入成功页面）。如果同一购物车仍被支付了两次（例如在两个浏览器标签页中），第二个订单保持无状态，已付款的订单会收到一条备注，提示顾客可能被扣款两次，以便您在 CCAvenue 控制面板中退款。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在此期间已被关闭，Confirm Order 会将顾客带回结账页面，下一次 Confirm Order 会为购物车支付一个新订单。当待定付款被中止时，消息为 Payment was cancelled. You may try again.；付款失败时为 Payment was not completed. Please try again or choose a different payment method.；当您关闭了已有付款的订单时为 This order can no longer be paid (it was closed by the store). Please confirm your order again.。如果订单已有状态，且此后购物车发生了变化（其他商品或数量），消息为 Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order.

结果仅来自顾客从 CCAvenue 的返回：没有服务器到服务器的通知，也没有状态查询。如果顾客在返回前关闭了浏览器，订单将保持无状态；请在 CCAvenue 控制面板中核实付款。本扩展不支持从 OpenCart 退款、保存银行卡、订阅或定期付款、站内银行卡表单，也不支持 CCAvenue UAE 或其他地区性平台。

订单

订单状态

无状态（缺失订单）：顾客已被发送到 CCAvenue 但尚未返回，或付款失败或被取消。在 Sales > Orders 中，这些订单仅在 Order Status 筛选器设置为 Missing Orders 时显示。如果顾客没有返回，请在 CCAvenue 控制面板中核实付款。

Order Status After Payment (default Processing)：付款已确认。备注会显示银行参考号、tracking ID 和付款方式。

Awaiting Payment Status (default Pending)：CCAvenue 将付款报告为 Awaited（银行尚未确认）。只要资金仍可能被扣取，订单就绝不会被标记为失败，备注会要求您在处理订单前在 CCAvenue 控制面板中核实付款。针对同一 tracking ID 的后续响应仍会生效：Success 设置 Order Status After Payment，Failure 设置 Failed Payment Status，Aborted 设置 Cancelled Payment Status。OpenCart 会将这些变化通知顾客。

On Hold (Review) Status (default Pending)：CCAvenue 确认了一笔金额或货币与订单总额或所发送内容不一致的付款，或者顾客在订单被取消或失败后付款。备注会显示收到的金额和预期金额。请在 CCAvenue 控制面板中核实付款，然后处理订单或退款。

延迟的失败绝不会更改已付款的订单，您手动完成的订单也不会被更改。如果同一已付款订单又收到另一笔成功付款（例如来自两个浏览器标签页），订单不会被更改。备注会要求您在 CCAvenue 控制面板中退还重复付款。

备注是订单 History 中的条目，顾客无法看到。

VibeFox CCAvenue Payment tab

在 Sales > Orders 中打开一笔通过 CCAvenue 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox CCAvenue Payment 标签页会显示 CCAvenue order ID（测试付款会带有 Test mode 标签）、Tracking ID、Status、Bank reference、Payment mode 和卡名、Amount sent 和 Amount received、Date、CCAvenue 的 Message，以及该订单的 CCAvenue notes。该标签页仅显示给有权访问本扩展的用户。

退款

不支持从 OpenCart 退款。请在 CCAvenue 控制面板中退还付款，然后在 OpenCart 中手动记录退款，例如更改订单状态。

许可证密钥

本扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox CCAvenue Payment 是 Extensions > Extensions > Payments > VibeFox CCAvenue Payment > Edit 中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: opencart-payment-ccavenue 一行，以及打开您 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 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 CCAvenue。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍能在商店中看到该支付方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中没有此预览功能：商店看不到后台登录状态，因此没有有效密钥时，所有人都看不到该支付方式。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响：已发起的付款在顾客从 CCAvenue 返回时仍会被确认。

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

故障排除

CCAvenue does not appear at checkout：请检查许可证是否有效、Enable/Disable 是否开启，以及三项凭据是否都已填写：Merchant ID、Access Code 和 Working Key。缺少任何一项时，设置页面都会显示警告。另请检查付款地址是否位于所选的 Geo Zone 中，以及订单金额是否达到设置中的 Total。

The payment went through, but the order stays without a status：顾客没有从 CCAvenue 返回您的商店，例如因为关闭了浏览器。扩展没有服务器到服务器的通知。请在 CCAvenue 控制面板中核实付款，并手动更新订单。

Every payment ends with We could not confirm the payment result：响应无法解密。Working Key 错误、属于其他域名，或复制时带有多余字符。请为本商店的域名生成密钥并重新粘贴。开启 Debug log，并查看扩展页面上的 Log 字段。

CCAvenue shows an error before the payment page：请检查 Access Code 和 Working Key 是否为此域名生成，返回 URL 是否属于在 CCAvenue 注册的域名，以及在测试模式下 CCAvenue 是否已为您的账户启用测试访问。对于非 INR 的货币，必须在您的 CCAvenue 账户上启用多币种处理。

The customer sees This payment method is temporarily unavailable：缺少某项凭据，或订单总额为零。Debug log 会显示原因。

The customer sees This payment method is not available. Please reload the checkout page.：结账会话与订单不再匹配，或支付方式在此期间已被关闭。顾客重新加载结账页面即可。

The customer sees Payment gateway error: encryption failed：无法加密请求。请检查是否已安装 PHP 的 OpenSSL 扩展。

The Merchant ID does not change on save：该值包含数字以外的字符。请仅输入 Merchant ID 中的数字。

Order is in the review or awaiting status：阅读 VibeFox CCAvenue Payment 标签页中的备注（参见订单状态）。请在 CCAvenue 控制面板中核实付款，然后处理订单或退款。

面向开发人员：在请求加密之前，扩展会触发 OpenCart 事件 ccavenue_p_request_params，并附带请求参数和订单（例如用于设置 merchant_param2 至 merchant_param5；请勿更改 amount、currency、order_id 或 merchant_param1）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox CCAvenue Payment 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还会删除其事件以及在维护模式下允许顾客返回通过的启动操作）。如果 Delete data on uninstall 已开启，其余扩展设置（标题、描述、凭据、测试模式、日志记录）和日志将被删除；如果关闭，则保留这些设置，以便日后重新安装时使用。CCAvenue 付款参考始终会保留。现有订单会保留其付款备注。

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

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