VibeFox Authorize.Net for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

HTTPS：您的结账页面必须使用 HTTPS。Accept.js 无法在普通 HTTP 页面上运行。

Authorize.Net 账户：您需要 Authorize.Net 账户的 API Login ID、Transaction Key 和 Public Client Key；如果使用 Webhook，还需要 Signature Key。正式账户（account.authorize.net）与沙盒账户（sandbox.authorize.net）的凭据各不相同。Authorize.Net 账户面向美国、加拿大、英国、欧洲、澳大利亚和新西兰的商户开放。

货币：订单货币必须是 USD、CAD、CHF、DKK、EUR、GBP、NOK、PLN、SEK、AUD 或 NZD，并且您的 Authorize.Net 账户必须以该货币结算。对于其他货币，结账时会隐藏此付款方式。

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

安装

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

OpenCart 3

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

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

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

4. 输入沙盒和正式账户的凭据（参见配置）。可选择设置 Webhook。

5. 开启 Enable/Disable，选择 Transaction type，然后点击 Save。在沙盒模式下使用卡号 4111 1111 1111 1111、任意未来的有效期和任意 CVV 测试一笔付款，然后关闭 Sandbox mode。

OpenCart 4

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

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

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

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

新安装时，付款方式默认关闭，沙盒模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Authorize.Net Gateway > Edit。各设置区块列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会在以下情况给出提示：店铺未使用 HTTPS（Accept.js 仅在 HTTPS 页面上运行）；商店默认货币不受 Authorize.Net 支持；当前模式缺少 API Login ID、Transaction Key 或 Public Client Key（此时结账时会隐藏付款方式）；当前模式缺少 Signature Key（此时 Webhook 被禁用）。沙盒模式开启时，页面会显示 Sandbox mode is on: test transactions, no real charges. 如果没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 必须为 1 到 128 个字符，Transaction type 必须是两个选项之一，Sort Order 必须是整数，Total 必须是大于或等于 0 的数字，并且所选地区（Geo Zone）和订单状态必须存在。如果任一字段有误，则不会保存任何内容，页面会指出该字段。

Authorize.Net

Enable/Disable：Enable Authorize.Net 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Credit Card。必填，最多 128 个字符。

Description：顾客在 Confirm Order 步骤中、银行卡表单上方看到的文字。默认：Pay securely with your credit card via Authorize.Net.

Sort Order：银行卡付款在结账页面各付款方式中的位置。留空或输入整数。

Geo Zone：仅为所选地区内的付款地址显示银行卡表单。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。

Total：订单在结账时必须达到的金额（以商店默认货币计）才会提供该付款方式。留空则对任意金额都提供。

API credentials

在 Authorize.Net Merchant Interface 中打开 Account > Settings > Security Settings。在 API Credentials & Keys 下复制 API Login ID，并创建 Transaction Key 和 Signature Key。在 Manage Public Client Key 下复制 Public Client Key。沙盒和正式环境使用不同的凭据。该区块会显示两种模式的字段，因此您可以同时保存两套凭据。

Sandbox mode：使用 Authorize.Net 沙盒（测试交易，不产生真实扣款）。它会切换 API 端点、Accept.js 以及新付款所使用的凭据组。默认：开启。关闭它即可接收真实付款。开启时，顾客会在银行卡表单上方看到 Sandbox mode: 以及测试卡号 4111 1111 1111 1111。

Sandbox API Login ID 和 Live API Login ID：沙盒或正式账户的 API Login ID。

Sandbox Transaction Key 和 Live Transaction Key：该账户的 Transaction Key。

Sandbox Public Client Key 和 Live Public Client Key：Accept.js 在浏览器中使用的公钥。

Sandbox Signature Key 和 Live Signature Key：仅 Webhook 需要。用于验证每条通知的 X-ANET-Signature 请求头。

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

Payment

Transaction type：银行卡的扣款方式。授权（authorization）在 30 天后过期。

Webhooks (recommended)

如果不使用 Webhook，被 Fraud Detection Suite 拦截的订单，或在 Authorize.Net 面板中被扣款或作废的订单，都需要手动更新。在 Merchant Interface 中进入 Account > Settings > Business Settings > Webhooks，然后分别在沙盒账户和正式账户中点击 Add Endpoint。使用本节 Endpoint URL 中显示的 URL。在 OpenCart 3 中它的格式类似 https://your-store/index.php?route=extension/payment/wcp_authorizenet_gateway/webhook，在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_authorizenet_gateway/payment/wcp_authorizenet_gateway.webhook，由您的 OpenCart 安装的店铺地址生成。请完全按照设置中显示的内容复制 URL。选择以下事件（本节也列出了它们）：

在 Sandbox Signature Key 或 Live Signature Key 中输入每个账户的 Signature Key。没有有效签名的 Webhook 会被拒绝。通知必须使用付款时所用模式的密钥签名；另一模式的通知不会产生任何更改。对于每条通知，扩展在更改订单之前还会向 Authorize.Net 查询交易的当前状态和金额，因此重复的通知不会产生任何更改。即使店铺处于维护模式，Webhook 也能正常工作，因为 OpenCart 会放行付款扩展的请求。

Orders

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（缺失订单）。只有在 Authorize.Net 对银行卡作出响应后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：银行卡已扣款（Authorize and capture，或之后的扣款）。默认：Processing。

Authorized Status：Authorize only：资金已预留，但尚未扣款。订单选项卡中的 Capture payment 仅在此状态下提供。默认：Pending。

On Hold (Review) Status：被 Fraud Detection Suite 转入审核，或已扣款或已捕获的金额与订单不符。备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Canceled Status：在 Authorize.Net 中因未付款而被拒绝、作废或过期（Webhook），或者订单选项卡中的授权已被作废。默认：Canceled。

Refunded Status：在订单选项卡中全额退款（或作废已付款的交易）后设置。默认：Refunded。

Advanced

Debug log：将 API 请求和响应写入 OpenCart 日志文件夹（storage/logs）中的 wc_ang_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会被移动到 wc_ang_debug.old.log.php。密钥、银行卡令牌和个人数据会被屏蔽。默认：关闭。即使关闭此选项，错误（例如被拒绝或失败的付款、API 错误以及失败的退款）也会始终被记录。

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

Delete data on uninstall：开启后，卸载扩展会删除设置和日志。Authorize.Net 的交易和退款始终保留，因此在重新安装后，之前已付款的订单仍可扣款和退款。默认：关闭。

Import / Export

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit Card）。在 Confirm Order 步骤中，顾客会看到您的描述，并在确认按钮上方的表单中输入银行卡号、有效期（MM/YY）和卡片安全码（CVV）。OpenCart 在此步骤创建订单，但订单仍没有状态。只有显示该表单时，Accept.js 才会从 Authorize.Net 加载。顾客点击 Confirm Order 后，Accept.js 会在浏览器中将银行卡数据换成一次性令牌。银行卡字段没有表单名称，因此银行卡号和 CVV 永远不会发送到您的服务器。

扩展通过 Authorize.Net API 按订单货币的订单总额扣除该令牌。账单地址、电子邮件和 IP 地址会随交易一起发送，用于地址验证和欺诈过滤；订单号则作为发票号发送。只有在 Authorize.Net 确认之后，订单才会被标记为已付款：如果交易获得批准，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，购物车被清空，顾客会看到 OpenCart 的订单成功页面，并显示 Your card payment has been received. 使用 Authorize only 时，页面显示 Your card payment has been authorized. The amount will be charged when your order is processed. 如果 Fraud Detection Suite 拦截了该交易，则显示 Your payment is being reviewed. We will update your order as soon as the review is complete.

如果银行卡被拒绝，顾客会停留在 Confirm Order 步骤，并在表单下方看到 Payment failed: 以及原因，例如银行卡被拒、安全码错误或银行卡已过期。订单仍没有状态，购物车会被保留，顾客可以输入其他银行卡。配置错误和 API 错误不会显示给顾客：他们只会看到通用提示，详细信息则写入日志。如果店铺无法连接 Authorize.Net，顾客会看到 Payment error: unable to connect to the payment gateway. Please try again. 如果银行卡字段为空，表单会提示 Please enter the card number, expiry date and card code.

重复点击、第二个标签页或重复提交都不会让同一订单被扣款两次。在 OpenCart 3 中，每次显示 Confirm Order 步骤时都会创建一个新订单，因此同一购物车可能有多个订单（在 OpenCart 4 中，较早的订单或第二个浏览器标签页同样可能持有同一购物车）：其中一个付款后，同一购物车的其他订单不会再被扣款。顾客会看到 This cart has already been paid with order #…. Please check your order history — do not pay again. 如果第一次尝试仍在进行中，第二次尝试会显示 Your payment is already being processed. Please wait a moment and check your order history before trying again. 如果付款已获批准但无法设置订单状态，顾客会看到 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. 之后，订单会在下一次尝试时或通过 Webhook 从已批准的付款中获得状态，无需再次扣除银行卡费用。

在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式。此时银行卡表单会出现在结账页面底部的订单确认区块中，位于 Confirm Order 上方。付款地址在 OpenCart 4 中是可选的：未填写时，配送地址会作为账单地址发送至 Authorize.Net。OpenCart 4 会为结账保留一个订单并对其进行更新，因此银行卡被拒后，顾客支付的是同一个订单。如果该订单其间已被关闭（例如您取消了它），或已付款而购物车中现在有了新的购买，Confirm Order 会将顾客带回结账页面，下一次点击 Confirm Order 将支付一个新订单。订单已关闭时，顾客会在结账页面上方看到 Your previous order is closed (cancelled or refunded by the store). Please confirm the order again: the cart will be paid with a new order.；订单已付款且购物车是此前的购物车时，则显示 Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order.。购物车的任何变动（包括新的数量）都会被视为需要单独付款的新购物车。

如果扣款金额与订单总额不符，订单会进入 On Hold (Review) Status，并附带备注，付款按实际扣款金额记录。

该扩展不支持保存银行卡或顾客档案、订阅或定期付款、eCheck/ACH、Apple Pay、Google Pay、PayPal 或 3-D Secure，不支持授权的部分扣款，也不支持自动货币转换。

订单与退款

Order statuses

No status (missing order)：银行卡被拒绝或付款失败。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时才会显示此类订单。

Order Status After Payment (default Processing)：银行卡已扣款（Authorize and capture），或授权已被扣款。备注会显示金额、Trans ID、授权码、银行卡类型和后四位数字。

Authorized Status (default Pending)：资金仅获得授权（Authorize only）。在发货前进行扣款。

On Hold (Review) Status (default Pending)：Fraud Detection Suite 将交易转入审核，已扣款金额与订单总额不符，或 Webhook 报告的扣款金额与订单金额不符。备注会对此进行说明。请在 Authorize.Net 面板中批准或拒绝被拦截的交易；使用 Webhook 时，订单会自动更新。

Canceled Status (default Canceled)：Webhook 报告交易在订单付款前已被拒绝、作废或过期，或者您作废了一笔未扣款的授权。如果已付款订单的交易在 Authorize.Net 面板中被作废，其状态不会改变，并会添加一条警告备注。

Refunded Status (default Refunded)：付款已通过该扩展全额退款或作废。

在 OpenCart 4 中，未付款的结账订单可能会获得 Voided 状态，该状态由 OpenCart 4 在顾客返回 Confirm Order 步骤时设置。扩展将此类订单视为无状态订单：之后的付款或 Webhook 仍会设置其状态。

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

VibeFox Authorize.Net Gateway tab

在 Sales > Orders 中打开一笔通过 Authorize.Net 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Authorize.Net Gateway 选项卡会显示 Trans ID（沙盒付款会附带 Sandbox 标签）、Transaction type、交易的 Status、Card 和授权码、Charged / order / refunded 金额、扣款按钮、退款表单、退款记录以及该订单的 Authorize.Net notes。该选项卡仅显示给有权访问该扩展的用户。扣款和退款需要修改扩展的权限（在 System > Users > User Groups 中设置）。

Capture

对于处于 Authorized Status 的订单，在选项卡中点击 Capture payment，并确认 Capture the authorized amount through Authorize.Net? 授权金额会被扣除，订单获得 Order Status After Payment。如果扣款失败，会显示错误并添加到备注中。您也可以在 Authorize.Net 面板中扣款；使用 Webhook 时，订单会自动更新。

Refunds

在选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，点击 Refund via Authorize.Net，并确认 Refund this amount through Authorize.Net? This cannot be undone. 全额退款时，如果交易尚未结算，则先作废该交易；如果是未扣款的授权，则作废该授权。已结算的交易（通常在 24 小时后）可以全额或部分退款。结算前无法部分退款：请全额退款以作废交易，或在结算后再试。退款以 Authorize.Net 实际扣除的金额和货币进行，因此在金额出现差异后，您最多只能退还顾客实际支付的金额，而不是订单总额。如果 Authorize.Net 不接受退款，选项卡会显示错误，且不会记录任何退款。成功的退款或作废会添加到退款记录和备注中。全额退款会将订单设为 Refunded Status（如果只作废了授权，则设为 Canceled Status），且不会通知顾客，也不会将商品退回库存，与手动更改状态的效果相同。部分退款不会更改状态。交易被拦截审核期间，不提供退款。

订单的扣款、退款和 Webhook 检查使用该订单付款时所在模式的凭据，因此即使您切换了 Sandbox mode，另一模式的订单仍可扣款和退款。在这些订单处理完成之前，请将该模式的凭据保留在对应字段中。

Sales > Returns 中的商品退货不会通过 Authorize.Net 退款。在 Authorize.Net 面板中进行的退款不会通知店铺：请手动更新订单。

许可证密钥

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

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

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

故障排除

银行卡付款没有出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否具有 API Login ID、Transaction Key 和 Public Client Key。如果缺少其中任何一项，设置页面会显示警告。另请检查顾客的货币是否受支持、付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍停留在已授权或审核状态：交易类型为 Authorize only（请在订单选项卡中扣款），或 Authorize.Net 已将交易转入审核。请在 Authorize.Net 面板中批准或拒绝该交易。要让此类订单自动更新，请设置 Webhook：检查所用模式的账户中是否存在该端点，其 URL 是否与 Endpoint URL 中显示的完全一致，四个事件是否均已选中，并且该账户的 Signature Key 是否已输入。

Webhook 响应：webhooks are not configured：两种模式都未输入 Signature Key。

Webhook 响应：invalid signature：Signature Key 属于另一个账户，或者 Authorize.Net 中的密钥已被更改。请重新创建或复制 Signature Key，并将其粘贴到对应模式的字段中。

Webhook 响应：mode mismatch：通知使用一种模式的密钥签名，但付款是在另一种模式下完成的。请检查沙盒和正式环境的 Signature Key 是否被调换。

Webhook 响应：verification failed, retry later：店铺无法通过 Authorize.Net API 读取该交易，或缺少付款所用模式的凭据。Authorize.Net 会重试投递。

Webhook 响应：busy, retry later：订单正被另一个请求同时更新，或处理失败。Authorize.Net 会重试投递。请查看 Log 字段了解原因。

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

银行卡表单显示 The secure card form (Accept.js) could not be loaded：结账页面必须使用 HTTPS，并且当前模式的 Public Client Key 和 API Login ID 必须正确。

Payment error: the card could not be tokenized：Accept.js 未返回令牌。顾客应重新输入银行卡信息并再次尝试。

顾客看到 This payment method is not available：结账会话与订单不再匹配，付款方式在此期间被关闭，凭据缺失，或订单总额为零。顾客点击 Please reload the checkout page 即可重新加载结账页面。

顾客看到一般错误：请查看扩展页面上的 Log 字段；错误总会记录在那里。账户不支持的货币会被 Authorize.Net 拒绝。

部分退款失败，因为交易尚未结算：请全额退款以作废该交易，或在结算后（通常在 24 小时内）重试。

退款或扣款因模式相关信息而失败：付款是在沙盒或正式模式下完成的，而该模式的 API Login ID 和 Transaction Key 未设置。请输入后重试。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Authorize.Net Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其全部事件，即在结账页面上方显示消息的事件，以及在维护模式下放行 Webhook 的启动操作）。如果 Delete data on uninstall 已开启，其余设置（标题、描述、沙盒模式、凭据、交易类型、日志记录）和日志也会被删除。如果已关闭，则会保留，供以后重新安装时使用。Authorize.Net 的交易和退款始终保留，因此在重新安装后，之前已付款的订单仍可扣款和退款。现有订单会保留其付款备注。

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

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