VibeFox Razorpay for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

Razorpay 账户：测试模式需要您的 Razorpay 账户的 Key ID 和 Key Secret；账户激活后，正式模式同样需要。强烈建议使用您自选密钥创建 webhook（参见配置）。使用 INR 以外的货币付款时，需要在您的 Razorpay 账户中启用 International Payments。

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

安装

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

OpenCart 3

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

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

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

4. 输入您的 Test Key ID 和 Test Key Secret，在 Razorpay Dashboard 中设置 webhook，并输入其密钥（参见配置）。

5. 打开 Enable/Disable 并点击 Save。在 Test mode 开启的状态下进行一次测试付款。准备就绪后，输入 Live 密钥并关闭 Test mode。

OpenCart 4

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

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

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

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

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Razorpay Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。如果没有修改扩展的权限，页面仅显示设置而无法保存。

在设置上方，页面会说明只有在 Razorpay 验证付款后订单才会获得状态，并显示以下提示：当前模式的密钥缺失（此时结账页面不会显示 Razorpay）、测试模式下 Key ID 不以 rzp_test_ 开头或正式模式下不以 rzp_live_ 开头、测试模式已开启、webhook 密钥为空，或商店默认货币不是 INR 且需要在您的 Razorpay 账户中启用 International Payments。每次保存后提示都会更新。

保存时，Title 必须为 1 到 128 个字符（Enter a title for the payment method (1 to 128 characters).），Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，且地理区域和每个订单状态都必须存在。否则不会保存任何内容。与 Key ID 一起粘贴的空格会被自动删除。

Razorpay

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

Title：顾客在结账时看到的支付方式名称，也是订单中保存的支付方式名称。默认：UPI, Cards, NetBanking。必填，最多 128 个字符。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay。

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

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

Total：订单必须达到的结账金额（以商店默认货币计）才会提供 Razorpay：大于或等于 0 的数字。留空则对任何金额都提供 Razorpay。

API 密钥

在 Razorpay Dashboard 的 Account & Settings > API Keys 中获取您的密钥（页面中有相应链接）。将 Dashboard 切换到测试模式即可生成测试密钥（rzp_test_...）。正式密钥（rzp_live_...）在您的账户激活后可用。

Test mode：使用测试模式密钥，因此不会扣除任何真实款项。默认：开启。关闭后即可接受真实付款。订单的付款、扣款和退款始终使用订单付款时所处模式的密钥，因此之后切换模式不会影响已有订单。开启期间，顾客在 Confirm Order 步骤和付款页面会看到 Razorpay Test mode: no real money will be charged.

Test Key ID：Razorpay Dashboard 测试模式下的 Key ID。以 rzp_test_ 开头。

Test Key Secret：Razorpay Dashboard 测试模式下的 Key Secret。

Live Key ID：Razorpay Dashboard 正式模式下的 Key ID。以 rzp_live_ 开头。

Live Key Secret：Razorpay Dashboard 正式模式下的 Key Secret。

已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 仅在需要更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value on save，然后点击 Save。

付款

Payment Action：扣款的时机。默认：Authorize & Capture。

Webhook

即使顾客在付款后立即关闭浏览器，webhook 也能确认付款，并记录在 Razorpay Dashboard 中所做的退款。在 Razorpay Dashboard 中进入 Account & Settings > Webhooks，分别在测试模式和正式模式下各添加一个 webhook。使用本节 Webhook URL 中显示的 URL。OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_razorpay_payment/webhook，OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_razorpay_payment/payment/wcp_razorpay_payment.webhook，由您 OpenCart 安装的商店地址生成。请按设置中显示的内容完整复制。在 Razorpay 中输入您自选的密钥，并选择以下事件（本节也列出了这些事件）：

Webhook Secret：您在创建 webhook 时输入的密钥。测试和正式 webhook 应使用相同的密钥，因为扩展只有一个字段。没有有效签名的 webhook 会被拒绝。如果没有 webhook，只有在顾客从弹窗返回，或顾客之后为同一购物车重新发起付款时，付款才会被确认。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Razorpay 确认付款后，订单才会获得状态。付款失败或被放弃时，订单保持无状态，购物车会被保留。OpenCart 没有 Authorized 和 On hold 状态，因此您需要选择现有状态，订单备注会说明原因。下方每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：付款已扣款，且金额和货币一致。默认：处理中。

Authorized Status：Authorize Only：款项已预留，但尚未扣款。默认：待处理。

On Hold (Review) Status：人工审核：付款金额或货币与订单总额不符，有付款到达已取消的订单，或弹窗签名有效但无法通过 Razorpay API 验证付款。默认：待处理。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Status：扩展从不设置此状态。它只用于告诉扩展哪些订单已取消：之后为此类订单扣款的付款会将其置于审核状态，而不是重新打开；已授权的付款只会添加备注。默认：已取消。

Refunded Status：付款全额退款后设置，可在订单选项卡中或 Razorpay Dashboard 中操作。默认：已退款。

高级

Enable Logging：日志写入 OpenCart 日志文件夹（storage/logs）中的 razorpay_p_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录；此选项会添加调试详情。密钥、签名和顾客联系资料绝不会被记录。默认：关闭。

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

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

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择支付方式（默认为 UPI, Cards, NetBanking）。在 Confirm Order 步骤中，顾客会看到您的描述以及说明 After "Confirm Order" the Razorpay Checkout window opens to pay securely (UPI, cards, NetBanking, wallets). OpenCart 在此步骤创建订单，仍然没有状态。顾客点击 Confirm Order 后，扩展会为订单的确切金额和货币创建一个 Razorpay 订单，并打开您商店的 Razorpay payment 页面。Razorpay Checkout 弹窗会在该页面自动打开，并已预先填入顾客的姓名、电子邮件和电话。在 OpenCart 4 中，顾客通过支付方式区块中的 Choose 按钮，在 Payment method options 窗口中选择支付方式，然后点击结账页面底部的 Confirm Order。该付款在 Razorpay 中显示为 Order # 加订单号。如果弹窗被关闭，顾客可以点击 Pay Now 重新打开，或点击 Choose another payment method 返回结账页面。购物车会被保留。

付款成功后，顾客会看到 Please wait while we process your payment... 扩展会检查 Razorpay 签名，从 Razorpay API 获取付款信息，并将金额和货币与订单进行比对。只有在 Razorpay 确认后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单电子邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。如果签名有效但当时无法获取付款信息，订单会获得 On Hold (Review) Status，之后由 webhook 确认。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单。OpenCart 4 会为结账保留一个订单并更新它，因此关闭弹窗或选择 Choose another payment method 后，顾客支付的仍是同一个订单。在开始新的付款之前，扩展会检查同一购物车中未完成的 Razorpay 订单：如果其中有一个已经付款（例如顾客关闭了浏览器且没有 webhook），则会直接应用该付款，而不再要求第二次付款，其他订单也不再提供。如果顾客再次为同一订单付款，并且金额、货币和模式均未改变，则复用其 Razorpay 订单；否则将创建新的订单。如果购物车已由另一个订单付款，顾客将直接进入成功页面。

顾客可能看到的消息：

在 OpenCart 4 中，如果结账中的订单已被商店关闭，或已对不同的购物车内容付款（例如购物车此后有变化，包括数量改变），顾客会被带回结账页面，并显示 Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order.，下一次点击 Confirm Order 时将为新订单付款。在 OpenCart 4 中，像这条消息一样将顾客带回结账页面的提示，例如 Payment session not found. Please try again. 和 We could not verify your payment.，会显示在结账页面上方。

即使商店处于维护模式，webhook 也能正常工作：OpenCart 3 允许支付扩展的请求通过，而在 OpenCart 4 中，该扩展会为 webhook 和弹窗结果添加一个启动操作。

该扩展仅支持一次性付款。不支持订阅或定期付款、已保存的卡片、Razorpay Magic Checkout、Payment Links 或 Route（分账付款），也不支持优惠或分期付款小部件。

订单与退款

订单状态

无状态（缺失订单）：顾客未付款、付款尝试失败，或 Razorpay 尚未确认付款。在 Sales > Orders 中，只有将 Order Status 筛选器设置为 Missing Orders 时才会显示此类订单。

Order Status After Payment（默认处理中）：付款已扣款并确认。备注会显示 Razorpay 付款 ID（pay_...）、金额以及确认方式（callback、webhook、同步或管理员）。

Authorized Status（默认待处理）：付款仅获得授权（Authorize Only）。扣款后即可完成订单。

On Hold (Review) Status（默认待处理）：在以下情况下设置，每种情况都带有备注：付款金额或货币与订单不符，付款是为已取消的订单扣款的，或当时无法通过 Razorpay API 验证付款。请检查订单，然后处理订单或为付款退款。

Cancelled Status：之后为已取消订单到达的付款不会自动重新打开该订单：已授权的付款不会被扣款，只会获得备注；已扣款的付款会使订单进入审核。即使您之后取消了订单，已付款订单对应付款的重复通知也不会产生任何变化。

Refunded Status（默认已退款）：付款已全额退款。

如果已付款的订单又收到额外付款，订单不会被更改。如果这不是您的本意，备注会提示您在 Razorpay Dashboard 中为其退款。已付款购物车中较早订单的迟到付款会使该较早订单保持无状态，而已付款的订单会收到备注。针对已付款订单的迟到 payment.failed 仅会添加备注。

备注是订单 History 中顾客看不到的条目。

VibeFox Razorpay Payment 选项卡

在 Sales > Orders 中打开一个通过 Razorpay 付款的订单。在订单页面底部，History 和 Additional 旁边的 VibeFox Razorpay Payment 选项卡会显示 Payment ID（测试付款会带有 Test mode 标签）、Razorpay order、付款的 Status、Paid / refunded（Razorpay 扣款金额和已退款金额）、扣款按钮、退款表单、退款历史以及订单的 Razorpay notes。该选项卡对有权访问此扩展的用户显示。扣款和退款需要修改扩展的权限（在 System > Users > User Groups 中设置）。

扣款（Authorize Only）

在 Authorized Status 状态下打开订单，在选项卡中点击 Capture Razorpay payment，并确认 Capture the authorized Razorpay payment? 付款将以授权时的模式扣款，订单将设为 Order Status After Payment，且不通知顾客、不修改库存，与手动更改状态相同。如果 Razorpay 拒绝，选项卡和备注会显示 Razorpay capture failed: 及原因。在 Razorpay Dashboard 中完成的扣款会通过 webhook 完成订单。

退款

在选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Razorpay。确认提示 Refund this amount through Razorpay? This cannot be undone. 支持全额和部分退款。退款以 Razorpay 扣款的金额和货币进行，因此在金额不一致之后，您最多可以退还顾客实际支付的金额，而不是订单总额。如果输入的金额更大，将显示 Invalid refund amount: at most 及该金额。退款会使用付款时所在模式的密钥发送。如果 Razorpay 不接受退款，选项卡会显示 Razorpay refund failed: 及原因，且不会记录任何退款。成功的退款会与 Razorpay 退款 ID、金额和状态一起添加到退款历史和备注中。全额退款会将订单设为 Refunded Status，且不通知顾客，也不会将商品退回库存。部分退款不会更改状态。退款只能在付款扣款后进行。

在 Sales > Returns 中的商品退货不会通过 Razorpay 退款。

在 Razorpay Dashboard 中所做的退款会通过 webhook 送达，并在退款历史（标记为 Razorpay Dashboard）和备注中只记录一次。订单全额退款后，其状态将变为 Refunded Status。在 Dashboard 中以其他货币进行的退款，或金额超过可退金额的退款，不会自动记录；备注会提示您手动记录。

许可证密钥

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

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

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

故障排除

Razorpay 未在结账页面显示：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式是否具备两个密钥：测试模式下为 Test Key ID 和 Test Key Secret，正式模式下为 Live Key ID 和 Live Key Secret。缺少时设置页面会显示提示。另外还要检查付款地址是否在所选的 Geo Zone 中，以及订单金额是否达到设置中的 Total。

付款已成功，但订单仍无状态：webhook 未正常工作。请在 Razorpay Dashboard 中检查您所用模式（Test 或 Live）下是否存在该 webhook，其 URL 是否与 Webhook URL 中显示的完全一致，以及五个事件是否均已选中。检查 Webhook Secret 是否与 Razorpay 中的密钥相同。顾客从弹窗返回，或为同一购物车重新发起付款时，订单也会获得状态。

Webhook 返回 Webhook secret not configured：Webhook Secret 为空。请输入 Razorpay webhook 的密钥。Razorpay 之后会再次发送该事件。

Webhook 返回 Invalid signature 或 Missing signature：设置中的密钥与 Razorpay webhook 的密钥不同。请在两处输入相同的密钥，分别对应测试和正式 webhook。

Webhook 返回 Retry later：扩展无法通过 Razorpay API 确认扣款，无法设置订单状态，或购物车当时正被另一个请求更新。Razorpay 会自动再次发送该事件。原因见 Log。

Webhook URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 Razorpay 的请求。

订单处于审核状态：请阅读 VibeFox Razorpay Payment 选项卡中的备注。金额或货币与订单不符，付款是为已取消的订单到达的，或当时无法通过 Razorpay API 验证，正在等待 webhook。

顾客付款时出现错误：请查看扩展页面上的 Log 字段。即使 Enable Logging 关闭，错误也会被记录。密钥错误会显示支付方式当前不可用的消息。Razorpay 的其他原因会显示在 Razorpay could not accept this payment: 之后。

弹窗未打开：Razorpay Checkout 脚本被内容拦截器或网络连接拦截。顾客会看到一条消息，并可以重新加载页面。

选项卡中没有扣款或退款表单：选项卡会说明原因：付款尚未扣款、已全额退款、您的用户组没有修改扩展的权限，或付款所在模式的密钥未设置（The payment was made in Test mode, but the Test Key ID / Key Secret are not configured. 或正式模式的相同提示）。请输入该模式的密钥后重试。

卸载

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

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

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