VibeFox Authorize.Net for PrestaShop — 帮助
要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在较旧的 PHP 版本上安装。
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 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Authorize.Net Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 输入沙盒和正式账户的凭据（参见配置）。如有需要，设置 webhook。
5. 开启 Enable/Disable，选择 Transaction type，然后点击 Save。使用卡号 4111 1111 1111 1111、任意未来的有效期和任意 CVV，在沙盒模式下测试一笔付款，然后关闭 Sandbox mode。
安装时，模块会创建两个订单状态：Authorize.Net payment authorized 和 Authorize.Net payment on hold。PrestaShop 会为所有币种、国家和客户组提供新的支付模块。您可以在 Payment > Preferences 中进行限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Authorize.Net Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，页面会提示以下情况：店铺未启用 SSL（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.
Authorize.Net
Enable/Disable：Enable Authorize.Net 用于开启或关闭该支付方式。默认：关闭。
Title：顾客在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。默认：Credit Card。必填。
Description：结账时显示在支付方式下方的文字。默认：Pay securely with your credit card via Authorize.Net.
API 凭据
在 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，以及新付款所用的凭据组。默认：开启。若要接收真实付款，请将其关闭。开启期间，顾客会在支付方式下方看到提示，其中包含测试卡 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 saved secrets：勾选某个密钥并点击 Save 即可将其删除。字段为空则保留已保存的值。
付款
Transaction type：银行卡的扣款方式。授权会在 30 天后过期。
Webhook（推荐）
如果不使用 webhook，被 Fraud Detection Suite 暂留的订单，或在 Authorize.Net 后台被扣款或撤销的订单，都需要手动更新。在 Merchant Interface 中进入 Account > Settings > Business Settings > Webhooks，然后分别在沙盒账户和正式账户中点击 Add Endpoint。请使用本节 Endpoint URL 中显示的 URL。启用友好 URL 时，它类似于 https://your-shop/module/wcp_authorizenet_gateway/webhook，可能带有语言代码，例如 /en/。请完全按照设置中显示的样子复制 URL。选择以下事件（本节也列出了这些事件）：
在 Sandbox Signature Key 或 Live Signature Key 中分别输入各账户的 Signature Key。没有有效签名的 webhook 会被拒绝。通知必须使用付款所用模式的密钥签名；另一模式的通知不会产生任何变化。对于每条通知，模块在修改订单前，还会向 Authorize.Net 查询交易的当前状态和金额，因此重复的通知不会产生任何变化。
高级
Debug log：将 API 请求和响应写入模块文件夹中的 logs/wc_ang_debug.log.php。该文件无法通过网页打开。密钥、银行卡令牌和个人数据会被隐去。默认：关闭。即使此选项关闭，错误（例如被拒绝或失败的付款、API 错误和失败的退款）也始终会被记录。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载模块时会删除设置和日志。Authorize.Net 交易、退款以及模块的订单状态始终保留，因此重新安装后，之前已付款的订单仍可扣款和退款。默认：关闭。
结账
在付款步骤中，顾客选择支付方式（默认为 Credit Card），并在其下方的表单中输入银行卡号、有效期（MM/YY）和安全码（CVV）。Accept.js 仅在结账页面加载。顾客下单时，Accept.js 会在浏览器中将银行卡数据换成一次性令牌。银行卡字段没有表单名称，因此银行卡号和 CVV 绝不会发送到您的服务器。
模块通过 Authorize.Net API，按购物车币种对购物车总额的令牌进行扣款。账单地址、电子邮件和 IP 地址会随交易一同发送，用于地址验证和欺诈过滤。由于付款前尚不存在订单，购物车编号会作为发票编号发送。只有在 Authorize.Net 确认付款后，订单才会被标记为已付款：如果交易获批，订单会立即创建，顾客会看到标准的订单确认页面，并显示 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.
如果银行卡被拒绝，顾客会停留在付款步骤，并看到 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.
重复点击、第二个标签页或重复提交，绝不会对同一购物车扣款两次。如果第一次尝试仍在进行中又发起第二次尝试，会显示 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，依据已批准的付款创建订单，而不会再次扣除银行卡。
如果付款过程中购物车发生变化，实际扣款金额就与购物车不再一致。此时订单会进入 Authorize.Net payment on hold 并附带备注，付款会按实际扣除的金额记录。
即使店铺处于维护模式，webhook 仍然可以工作，并且不会受到店铺国家限制的影响。
本模块不支持保存银行卡或顾客资料、订阅或定期付款、eCheck/ACH、Apple Pay、Google Pay、PayPal 或 3-D Secure，不支持授权的部分扣款，也不支持自动货币转换。
订单与退款
订单状态
No order：银行卡被拒或付款失败。只存在购物车。
Payment accepted：银行卡已扣款（Authorize and capture），或授权已被扣款。付款会以 Authorize.Net Trans ID 作为交易 ID 记录，备注中会显示金额、Trans ID、授权码、卡类型以及卡号后四位。
Authorize.Net payment authorized：资金仅被授权（Authorize only）。在发货前进行扣款。
Authorize.Net payment on hold：Fraud Detection Suite 暂留了交易以供审核，扣款金额与订单总额不符，或 webhook 报告的扣款金额与订单金额不符。备注会说明原因。请在 Authorize.Net 后台批准或拒绝被暂留的交易；使用 webhook 时，订单会自动更新。
Canceled：webhook 报告交易在订单付款前已被拒绝、撤销或过期；或者您撤销了一笔未扣款的授权。如果已付款订单的交易在 Authorize.Net 后台被撤销，其状态不会改变，并会添加一条警告备注。
Refunded：付款已通过模块全额退款或撤销。
如果购物车已有订单，又有第二笔交易获批，订单不会改变。备注会提醒您在 Authorize.Net 后台检查该重复交易，并将其撤销或退款。
Authorize.Net 付款区块
订单页面会显示一个 Authorize.Net payment 区块，其中包括 Trans ID、交易类型、交易状态、银行卡和授权码、已扣金额、订单总额和已退金额；沙盒付款会显示 Sandbox 标记，此外还有退款历史和订单的 Authorize.Net notes。扣款和退款只需要编辑订单的权限，不需要访问模块页面的权限。
扣款
对于处于 Authorize.Net payment authorized 的订单，请点击区块中的 Capture payment，并确认 Capture the authorized amount through Authorize.Net? 系统会扣除已授权的金额，以 Trans ID 记录付款，订单变为 Payment accepted。如果扣款失败，将显示错误，并添加到备注中。您也可以在 Authorize.Net 后台扣款；使用 webhook 时，订单会自动更新。
退款
在区块中输入金额（会自动填入尚未退款的金额），可选填写原因，点击 Refund via Authorize.Net，并确认 Refund this amount through Authorize.Net? This cannot be undone. 全额退款时，如果交易尚未结算，会先撤销该交易；如果是未扣款的授权，则会撤销该授权。已结算的交易（通常在 24 小时后）可以全额或部分退款。结算前无法进行部分退款：请全额退款以撤销交易，或在结算后再试。退款按 Authorize.Net 实际扣款的金额和币种进行，因此在金额出现差异后，您最多只能退还顾客实际支付的金额，而不是订单总额。如果 Authorize.Net 不接受退款，区块会显示错误，并且不会记录退款。成功的退款或撤销会添加到退款历史和备注中。全额退款会将订单设为 Refunded（仅撤销授权时设为 Canceled）。部分退款不会改变状态。交易被暂留审核期间，不提供退款。
订单的扣款、退款和 webhook 校验使用订单付款时所用模式的凭据，因此在切换 Sandbox mode 后，另一模式的订单仍可扣款和退款。在这些订单处理完毕之前，请将该模式的凭据保留在对应字段中。
本模块不会开具退款单据。订单页面上 PrestaShop 的标准退款按钮不会通过 Authorize.Net 退回款项。在 Authorize.Net 后台进行的退款不会通知店铺：请手动更新订单。
许可证密钥
本模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Authorize.Net Gateway 位于 Modules > Module Manager > VibeFox Authorize.Net Gateway > Configure 页面的最上方，在设置上方。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏方式显示密钥，并显示状态（例如许可证的有效截止日期和您的域名），以及按钮 Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: presta-payment-authorizenet 一行，以及打开 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 账户中释放该名额。
没有有效的许可证密钥时，结账时不会向顾客显示 Authorize.Net 银行卡付款。即使如此仍发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 店铺前台无法得知您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会被确认，扣款和退款也仍然有效。
许可证到期后，模块继续运行，但更新和支持需要续期。在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Authorize.Net：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否具有 API Login ID、Transaction Key 和 Public Client Key。如果缺少其中任何一项，设置页面会显示警告。请检查购物车币种是否受支持，并在 Payment > Preferences 中确认模块允许该购物车币种、顾客所在国家和顾客所属的客户组。
付款已完成，但订单仍处于 Authorize.Net payment on hold 或 authorized 状态：交易类型为 Authorize only（请在订单区块中扣款），或者 Authorize.Net 已将交易暂留以供审核。请在 Authorize.Net 后台批准或拒绝该交易。要让此类订单自动更新，请设置 webhook：检查使用的模式账户中是否存在该端点，其 URL 是否与 Endpoint URL 中显示的完全一致，四个事件是否都已选中，以及该账户的 Signature Key 是否已输入。
Webhook answers webhooks are not configured：两种模式都没有输入 Signature Key。
Webhook answers invalid signature：Signature Key 属于另一账户，或者在 Authorize.Net 中更改过密钥。请重新创建或复制 Signature Key，并粘贴到对应模式的字段中。
Webhook answers mode mismatch：通知使用其中一种模式的密钥签名，但付款是在另一种模式下完成的。请检查沙盒和正式环境的 Signature Key 是否被对调。
Webhook answers verification failed, retry later：店铺无法从 Authorize.Net API 读取交易，或者付款所属模式的凭据缺失。Authorize.Net 会重试投递。
Webhook answers 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 没有返回令牌。顾客应重新输入银行卡信息并再次尝试。
顾客看到一般性错误：请查看模块页面上的 Log 字段；错误总会写入其中。账户不支持的币种会被 Authorize.Net 拒绝。
由于交易尚未结算，部分退款失败：请全额退款以撤销交易，或在结算后重试（通常在 24 小时内）。
扣款或退款失败，并提示与模式相关的消息：付款是在沙盒或正式模式下完成的，而该模式的 API Login ID 和 Transaction Key 尚未设置。请输入后再试。
卸载
进入 Modules > Module Manager，打开 VibeFox Authorize.Net Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Authorize.Net 交易和退款，以及订单状态 Authorize.Net payment authorized 和 Authorize.Net payment on hold，始终会保留，因此重新安装后，之前已付款的订单仍可扣款和退款。现有订单会保留其付款备注和交易 ID。
Authorize.Net 是其各自所有者的商标。本模块与 Authorize.Net 无关联，也未获得 Authorize.Net 的认可。