VibeFox CCAvenue for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，并启用 OpenSSL 扩展（用于加密请求和解密响应）。在较旧的 PHP 版本上或未启用 OpenSSL 时，模块会拒绝安装。
CCAvenue 账户：您需要一个 CCAvenue 商户账户，并拥有 Merchant ID、Access Code 和 Working Key。Access Code 和 Working Key 是针对网站域名签发的，因此请为本商店的域名生成它们。CCAvenue 在测试环境中使用相同的凭据；测试权限必须由 CCAvenue 为您的账户开通。本模块使用 CCAvenue 印度的接口地址。
币种：购物车币种会原样发送给 CCAvenue。CCAvenue 账户默认接受 INR；其他币种需要在您的 CCAvenue 账户中开通多币种处理。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox CCAvenue Payment，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。
4. 从您的 CCAvenue 后台输入 Merchant ID、Access Code 和 Working Key，并开启 Enable/Disable。
5. 测试期间保持 Test mode 开启，测试完成后关闭它以接收真实付款。
安装时，模块会创建两个订单状态：Awaiting CCAvenue payment 和 CCAvenue payment on hold。PrestaShop 会为所有币种、国家和客户群组启用新的付款模块。您可以在 Payment > Preferences 中对其进行限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox CCAvenue Payment > Configure。每个部分都有自己的 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 时，还会提醒您启用多币种处理。
CCAvenue
Enable/Disable：Enable CCAvenue Payment Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：CCAvenue。
Description：结账时显示在付款方式下方的文字。默认：Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.
API 凭据
登录您的 CCAvenue 商户后台（M.A.R.S.），打开 Settings > API Keys。为本商店的域名生成 Access Code 和 Working Key。保存时会自动删除凭据中的空格。
Merchant ID：您的 CCAvenue 数字商户 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，即可删除已保存的 Working Key。字段为空时将保留已保存的值。
Test mode：将顾客引导至 CCAvenue 测试环境（test.ccavenue.com）。CCAvenue 在测试和正式环境中使用相同的 Merchant ID、Access Code 和 Working Key；测试权限必须由 CCAvenue 为您的账户开通。在测试模式下，结账时付款方式下方会显示 TEST MODE: no real transactions will be processed. 默认：开启。接收真实付款时请关闭。
Return URL
CCAvenue 会将顾客带回本节所示的地址。使用友好 URL 时，它的形式类似 https://your-shop/module/wcp_ccavenue_payment/return，可能还带有语言代码，例如 /en/。模块会在每笔付款中发送此 URL（作为跳转和取消 URL），因此无需在 CCAvenue 中进行任何设置。它必须属于在 CCAvenue 注册的域名。
高级
Debug log：将 CCAvenue 事件写入模块文件夹中的 logs/ccavenue_p_debug.log.php。该文件无法通过网页打开。日志只记录订单参考号、追踪 ID 和状态；密钥、银行卡数据、电子邮件和地址均不会记录。默认：关闭。关闭时不会写入任何内容，包括错误信息。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载模块会删除模块设置、日志和 CCAvenue 订单参考号。订单和模块的订单状态会保留。默认：关闭。
结账
在付款步骤，顾客选择付款方式（默认为 CCAvenue）并确认。页面会显示 Thank you for your order. You are being redirected to CCAvenue to complete the payment.，并将顾客转到 CCAvenue 付款页面。未启用 JavaScript 时，顾客可点击 Pay via CCAvenue 或 Back to checkout。此时尚未创建订单。
每次尝试都会获得一个新的 CCAvenue 订单参考号，由购物车编号和时间组成。购物车总额和币种、账单信息、配送地址（与账单地址不同时）以及该次尝试的秘密令牌都会在加密请求中发送。姓名和地址会按 CCAvenue 接受的字符和长度进行处理；国家和省/州以名称形式发送，电话仅以数字形式发送。顾客在 CCAvenue 页面上选择银行卡、网上银行、UPI、电子钱包或 EMI。
付款完成后，CCAvenue 会携带加密响应将顾客带回。只有在 CCAvenue 确认后，订单才会被标记为已付款：响应必须能用您的 Working Key 解密，属于本商店的某次尝试，并且金额和币种与所发送的内容以及购物车总额一致。随后创建订单，顾客会看到标准的订单确认页面，并显示 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 shop. 如果待处理订单之后在未付款的情况下被取消或失败，确认页面会显示 Your CCAvenue payment was not completed. Please contact us about this order.
如果付款失败，顾客会返回结账页面，并显示 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. 在这些情况下不会创建订单，购物车会被保留，顾客可以重新付款。如果购物车已经有订单，新的尝试会直接进入该订单的确认页面，而不是再次付款。
结果仅取自顾客从 CCAvenue 的返回：没有服务器对服务器的通知，也不进行状态查询。如果顾客在返回前关闭浏览器，则不会创建订单；请在 CCAvenue 后台核实付款。本模块不支持从 PrestaShop 退款、保存银行卡、订阅或定期付款，不支持站内银行卡表单，也不支持 CCAvenue UAE 或其他地区性平台。
订单
订单状态
No order yet：顾客已被转到 CCAvenue 但尚未返回，或者付款失败或被取消。此时只存在购物车。如果顾客一直没有返回，请在 CCAvenue 后台核实付款。
Payment accepted：付款已确认。付款会以 CCAvenue 追踪 ID 作为交易 ID 记录，备注中会显示银行参考号、追踪 ID 和付款方式。
Awaiting CCAvenue payment：CCAvenue 将付款报告为 Awaited（银行尚未确认）。在款项仍可能被扣收期间，订单绝不会被标记为失败。发货前请在 CCAvenue 后台核实。之后使用相同追踪 ID 返回的响应仍会被处理：Success 会设为 Payment accepted，Failure 会设为 Payment error，Aborted 会设为 Canceled。
CCAvenue payment on hold：CCAvenue 确认了一笔金额或币种与购物车或所发送内容不一致的付款（例如，付款开始后购物车在另一个标签页中被修改），或者顾客在订单已取消后付款。备注中会显示收到的金额和预期金额。当币种一致时，CCAvenue 报告的金额会作为订单付款记录。请在 CCAvenue 后台核实付款，然后发货或退款。
迟到的失败结果绝不会改变已付款的订单。如果对于已付款的订单又收到另一笔成功付款（例如来自两个浏览器标签页），订单不会被修改。备注会提示您在 CCAvenue 后台退还重复付款。
CCAvenue 付款区块
订单页面会显示 CCAvenue payment 区块，其中包括 CCAvenue 订单 ID、追踪 ID、状态、银行参考号、付款方式和银行卡名称、发送和收到的金额、日期及 CCAvenue 消息；测试付款还会显示 Test mode 标记。CCAvenue 备注是订单的私密消息，仅在后台可见。
退款
不支持从 PrestaShop 退款。请在 CCAvenue 后台退还付款，然后在 PrestaShop 中手动记录退款。
许可证密钥
本模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox CCAvenue Payment 许可证区块位于 Modules > Module Manager > VibeFox CCAvenue Payment > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证的有效截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有 Product: presta-payment-ccavenue 这一行，以及打开您的 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。区块中的文字遵循后台语言（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在店铺地址更改之后，或在您的账户中释放了一个域名名额之后，请点击 Check now。如果无法连接许可证服务器，模块将继续以最后一次已知的状态运行。
一个密钥仅适用于一个域名：主店铺的域名，包括多店铺设置。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 CCAvenue。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 前台商店并不知道您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。提醒会出现在 Modules > Module Manager 的 Alerts 选项卡中。现有订单不受影响：顾客从 CCAvenue 返回时，已发起的付款仍会被确认。
许可证过期后，模块仍会继续运行，但更新和支持需要续订。在后台工作期间会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置计划任务。卸载或重置模块时，始终会移除许可证密钥和许可证状态。
故障排除
结账时不显示 CCAvenue：请检查许可证是否有效、Enable/Disable 是否已开启，以及三项凭据是否全部已填写：Merchant ID、Access Code 和 Working Key。缺少其中任何一项时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车币种、顾客所在国家和顾客所属群组。
付款已完成，但未创建订单：顾客没有从 CCAvenue 返回您的商店，例如因为关闭了浏览器。本模块没有服务器对服务器的通知。请在 CCAvenue 后台核实付款，并手动创建或更新订单。
每笔付款都以 We could not confirm the payment result 结束：响应无法解密。Working Key 错误、属于其他域名，或复制时带有多余字符。请为本商店的域名重新生成密钥并重新粘贴。开启 Debug log，并查看模块页面上的 Log 字段。
CCAvenue 在付款页面之前显示错误：请检查 Access Code 和 Working Key 是否为本域名生成，Return URL 是否属于在 CCAvenue 注册的域名，以及在测试模式下 CCAvenue 是否已为您的账户开通测试权限。对于 INR 以外的币种，您的 CCAvenue 账户必须已开通多币种处理。
顾客看到 This payment method is temporarily unavailable：缺少某项凭据，或购物车总额为零。Debug log 会显示原因。
顾客看到 This payment method is not available：模块已关闭，或在 Payment > Preferences 中不允许用于该购物车币种、国家或客户群组。
顾客看到 Payment gateway error: encryption failed：请求无法加密。请检查是否已安装 PHP 的 OpenSSL 扩展。
保存时 Merchant ID 没有变化：该值包含数字以外的字符。请只输入 Merchant ID 中的数字。
订单状态为 CCAvenue payment on hold 或 Awaiting CCAvenue payment：请阅读订单备注（见订单状态）。请在 CCAvenue 后台核实付款，然后发货或退款。
对于开发者，本模块提供钩子 actionCcavenueRequestParams（在加密之前更改发送给 CCAvenue 的数据，例如 merchant_param2 至 merchant_param5；值不得包含 &；不要更改 amount、currency、order_id 或 merchant_param1）。
卸载
进入 Modules > Module Manager，打开 VibeFox CCAvenue Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被移除。确认对话框会提醒您：除非启用了 Delete data on uninstall，否则设置和 CCAvenue 参考信息都会被保留。如果启用，则会删除模块设置、日志和 CCAvenue 订单参考号。如果未启用，则全部保留，以便日后重新安装。订单状态 Awaiting CCAvenue payment 和 CCAvenue payment on hold 始终保留。现有订单会保留其付款备注和交易 ID。
CCAvenue 是其各自所有者的商标。本模块与 CCAvenue 无关联，也未获得 CCAvenue 的认可。