VibeFox Adyen for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

Adyen 账户：您需要 Adyen 商户账户名称、您所用每个环境（测试和正式）的 API 密钥和 HMAC 密钥，以及正式付款所需的正式 URL 前缀。API 密钥属于具有 Checkout webservice 和 Merchant PAL webservice 角色的 API 凭据。HMAC 密钥是为 Standard webhook 生成的（参见 Configuration）。测试 Customer Area 为 ca-test.adyen.com，正式 Customer Area 为 ca-live.adyen.com。测试和正式密钥是分开的。无需客户端密钥，因为付款页面由 Adyen 托管。

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

安装

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

OpenCart 3

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

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

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

4. 输入您的商户账户、测试 API 密钥和测试 HMAC 密钥，之后再输入正式 API 密钥、正式 HMAC 密钥和正式 URL 前缀。

5. 在 Adyen Customer Area（测试和正式）中，添加一个 Standard webhook，URL 使用设置中 Webhook 部分显示的地址（参见 配置）。

6. 开启 Enable/Disable，然后点击 Save。在 Test mode 开启的情况下测试一笔付款，然后关闭它。

OpenCart 4

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

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

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

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

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

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Adyen Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。当前模式的设置不完整时，页面会显示 Adyen is hidden at checkout until the test settings are complete（或正式设置），并列出缺少的内容：Merchant account、API 密钥、HMAC 密钥，以及在正式模式下的 Live URL prefix。测试模式开启时，页面会显示 Test mode is on: payment links and refunds go to the Adyen test environment, no real money. 如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 必须为 1 到 128 个字符，Sort Order 必须为整数，Total 必须为 0 或更大的数字，并且地理区域和订单状态必须存在；否则不会保存任何内容，页面会指出具体字段。非十六进制的 HMAC 密钥，或包含字母、数字和连字符以外字符的正式 URL 前缀不会被保存：警告会指出该字段，保留之前的值，其他设置仍会保存。

Adyen

Enable/Disable：Enable Adyen payment gateway 用于开启或关闭该付款方式。默认：关闭。

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

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely via Adyen。

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

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

Total：订单需要达到的结账金额（以店铺默认货币计算），达到后才会提供 Adyen。留空则对任何金额都提供 Adyen。

Adyen 账户

API 密钥在 Adyen Customer Area 的 Developers > API credentials 中创建（该部分提供了测试和正式 Customer Area 的链接）。两组密钥都要填写；Test mode 开关决定使用哪一组。

Test mode：使用 Adyen 测试环境（不产生真实资金）。开启后，付款链接和退款会使用测试 API 密钥发送到 checkout-test.adyen.com。默认：开启。关闭后可接受真实付款。开启期间，顾客在 Confirm Order 步骤会看到 Test mode: no real payment is taken.

Merchant account：您的 Adyen 商户账户名称（不是公司账户），例如 MyShopECOM。它通常与测试和正式 Customer Area 中的名称相同。

测试凭据

在 Test mode 开启时使用。

Test API key：来自测试 Customer Area：Developers > API credentials > 您的凭据 > API key。

Test HMAC key：来自测试 Customer Area：Developers > Webhooks > 您的 Standard webhook > HMAC key（十六进制）。必填：没有有效签名的 webhook 会被拒绝。

正式凭据

在 Test mode 关闭时使用。

Live API key：来自正式 Customer Area：Developers > API credentials > 您的凭据 > API key。

Live HMAC key：来自正式 Customer Area：Developers > Webhooks > 您的 Standard webhook > HMAC key（十六进制）。

Live URL prefix：来自正式 Customer Area：Developers > API URLs，例如 https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com 中的 1797a841fbb37ca7-AdyenDemo。您可以粘贴整个 URL；保存时会从中提取前缀。

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

Webhook

订单仅通过 Adyen 的 webhook 才会被标记为已付款。在 Customer Area（测试和正式）中进入 Developers > Webhooks，并添加一个 Standard webhook，URL 使用本部分 Webhook URL 中显示的地址。在 OpenCart 3 中它形如 https://your-store/index.php?route=extension/payment/wcp_adyen_gateway/webhook，在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_adyen_gateway/payment/wcp_adyen_gateway.webhook。它根据您 OpenCart 安装的前台地址生成。请完全按设置中显示的样子复制 URL，因为 Adyen 不会跟随重定向。选择 JSON 方法，开启 Generate HMAC key，并将密钥复制到 Test HMAC key 或 Live HMAC key 中。

每条通知所属的环境决定使用哪个 HMAC 密钥，并且通知只会应用于在同一环境和同一商户账户下创建的付款链接。测试通知绝不会确认正式付款。没有有效签名的 webhook 会以 HTTP 401 被拒绝，Adyen 之后会重试。如果没有 webhook，订单不会获得任何状态。

该扩展会处理以下事件（本部分也列出了这些事件）：

其他事件会添加到订单备注中。对于没有状态的订单，除 AUTHORISATION 之外的通知都会被忽略。不属于本店铺订单的通知（例如 Customer Area 中的测试按钮）会被接受并忽略。即使店铺处于维护模式，webhook 也能正常工作，因为 OpenCart 允许付款扩展的请求通过。在 OpenCart 4 中，扩展还会为此添加一个 startup action。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（缺失订单）。只有当 Adyen 通过已签名的 AUTHORISATION webhook 确认付款，且金额和币种与订单一致时，订单才会获得状态。顾客返回页面绝不会改变订单。下面每个字段都列出了您的 OpenCart 订单状态。

Order status after payment：成功的已签名 AUTHORISATION webhook 所设置的状态。默认：处理中。

On hold (review) status：金额或币种不一致、已付款订单的扣款失败，或订单状态已被更改（例如已取消）之后才收到的付款。备注会说明原因。默认：待付款，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Cancelled status：Adyen 取消该订单的付款时设置（CANCELLATION）。默认：已取消。

Refunded status：通过订单页面全额退款后设置。如果 Adyen 随后报告该退款失败，订单会转为审核状态并附带备注。默认：已退款。

高级

Debug log：将 API 调用和 webhook 事件写入 OpenCart 日志文件夹（storage/logs）中的 adyg_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会被移动为 adyg_debug.old.log.php。即使开关关闭，错误也始终会被记录。日志绝不会包含 API 或 HMAC 密钥，也不包含顾客的个人数据。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展时会删除网关设置和日志。Adyen 的付款记录（PSP 参考号、webhook 事件、退款）始终保留，因此旧订单仍可退款。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 Adyen）。在 Confirm Order 步骤，顾客会看到您的描述以及备注 You will be redirected to Adyen to complete the payment securely. OpenCart 在此步骤创建订单，但仍没有状态。顾客点击 Confirm Order 后，扩展会以订单币种为订单总额创建一个 Adyen 付款链接，并将顾客转到 Adyen 付款页面。在那里，顾客可以使用您 Adyen 账户中启用的任何方式付款。顾客的邮箱、姓名和账单国家（或店铺所在国家）以及店铺语言会传递给 Adyen，付款会显示为 Order # 加订单号。

付款后，顾客会返回您的店铺。返回本身并不会支付订单：只有当 Adyen 通过已签名的 AUTHORISATION webhook 确认付款，且金额和币种与订单一致时，订单才会被标记为已付款。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。如果 webhook 已经到达，顾客会看到 OpenCart 订单成功页面，并显示 Your payment with Adyen has been received.（对于处于审核状态的订单，则显示 Your payment with Adyen has been received and is being reviewed by the store.）。如果 Adyen 在此之前已取消付款，页面会显示 Your Adyen payment was not completed. Please contact us about this order. 如果 webhook 尚未到达，对于未完成付款的顾客，会显示 Payment confirmation 页面，内容为 Your payment is being confirmed by Adyen. Your order will be confirmed as soon as Adyen confirms the payment, and you will receive an e-mail.，并带有 Check again 和 Back to checkout 按钮。

如果付款被拒绝，订单保持无状态，顾客可以通过同一链接再次付款，或返回结账页面。每次新的尝试（OpenCart 3 在每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则会更新结账中的订单）都会使该订单和购物车之前的付款链接失效，因此它们也无法再被支付。如果订单已经有状态，顾客会被转到成功页面，而不会再发起新的付款。

在 OpenCart 4 中，顾客在付款方式区块中点击 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。在 OpenCart 4 中，付款地址是可选的：未填写时，顾客的姓名会作为付款人姓名传递，收货地址的国家（或店铺所在国家）作为国家传递。OpenCart 4 会为结账保留一个订单并对其进行更新：Back to checkout 以及再次点击 Confirm Order，会为同一订单创建新的付款链接，并使之前的付款链接失效。如果该订单在此期间未付款即已被关闭（例如 Adyen 取消了付款，或您取消了该订单），顾客会被带回结账页面，并在结账页面上方看到 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，下一次点击 Confirm Order 时将为一个新订单付款。如果结账中的订单已经为另一个购物车付过款，顾客会被带回结账页面并为新订单付款。购物车发生变化（包括数量变化）即视为需要单独付款的新购物车。

如果无法创建付款链接，顾客会停留在 Confirm Order 步骤，并看到 Payment could not be initiated. Please try again or choose another payment method. 原因会写入日志。如果设置不完整，提示为 Payment gateway is not configured properly. Please contact the store administrator.

该扩展不支持订阅或定期付款、保存的银行卡、店铺自身页面上的银行卡输入字段（Drop-in 或 Components）、OpenCart 中的扣款或取消按钮，也不支持 webhook 的基本身份验证。

订单和退款

订单状态

No status (missing order)：顾客已被转到 Adyen，但未付款、付款被拒绝，或 Adyen 尚未确认付款。在 Sales > Orders 中，此类订单只会在 Order Status 筛选器设为 Missing Orders 时显示。

Order status after payment (default Processing)：付款已授权。备注会显示金额、PSP 参考号和付款方式。

On hold (review) status (default Pending)：Adyen 确认的金额或币种与订单总额不同，扣款失败，全额退款失败，或者付款在订单状态已被更改（例如已取消）之后才到达。备注会解释原因。请在 Customer Area 中检查付款，然后处理订单或退还付款。对于因不一致而处于审核状态的订单，如果付款正确，则会将其标记为已付款。

Cancelled status (default Canceled)：该订单的付款已在 Adyen 中取消。

Refunded status (default Refunded)：付款已通过扩展全额退款。发送退款时设置此状态；如果 Adyen 之后报告该退款失败，订单会转为审核状态。

如果已付款的订单又收到第二笔成功的付款（例如来自旧的付款链接），订单不会被更改。备注会要求您在 Customer Area 中检查是否存在重复扣款，并在必要时在那里退款。购物车的情况也一样：一旦购物车中的某个订单已付款，就不会为该购物车的其他订单创建新的付款链接；如果仍有付款到达该订单，也不会为其分配状态，已付款的订单会收到备注。

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

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

VibeFox Adyen Gateway 选项卡

在 Sales > Orders 中打开一个通过 Adyen 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Adyen Gateway 选项卡会显示 PSP reference（测试付款带有 Test mode 标签）、Payment link、Merchant account、付款 Status、Paid / refunded 金额、退款表单、退款历史以及该订单的 Adyen notes。该选项卡对有权访问此扩展的用户显示。

退款

在 VibeFox Adyen Gateway 选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Adyen。确认提示 Refund this amount through Adyen? This cannot be undone. 支持全额和部分退款。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款会按 Adyen 授权的金额和币种进行；因此在金额或币种不一致之后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会发送到付款时所用的环境和商户账户，因此必须设置该环境的 API 密钥。同一订单一次只会执行一笔退款。如果 Adyen 不接受请求，选项卡会显示错误，并且不会记录任何退款。Adyen 授权付款后即可进行退款。

Adyen 以异步方式处理退款：请求会以 received 状态添加到退款历史和备注中，最终结果通过 REFUND 或 REFUND_FAILED webhook 返回。失败的退款不再计入已退款。当已发送的退款达到已付金额时，订单会设置为 Refunded status，不会通知顾客，也不会把商品放回库存，与手动更改状态相同。部分退款不会改变状态。如果在 Adyen 中使用手动扣款，则只有已扣款的付款可以退款。

Sales > Returns 中的商品退货不会通过 Adyen 退回款项。在 Adyen Customer Area 中进行的退款会通过 webhook 送达，并添加到备注中。订单状态不会自动更改。

许可证密钥

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

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

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

故障排除

结账时未显示 Adyen：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的设置是否完整：Merchant account、该模式的 API 密钥和 HMAC 密钥，在正式模式下还需要 Live URL prefix。设置页面会列出缺少的内容。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：webhook 没有正常工作。请在您所用环境（测试或正式）的 Customer Area 中检查 Standard webhook 是否存在，其 URL 是否与 Webhook URL 中显示的完全一致，以及方法是否为 JSON。检查该 webhook 的 HMAC 密钥是否填在对应字段中（Test HMAC key 或 Live HMAC key）。HMAC 密钥无效或缺失时，扩展会返回 HTTP 401，Adyen 之后会重新投递，因此在修正密钥后订单会自动获得状态。日志会显示 HMAC 签名无效或未配置 HMAC 密钥。

Webhook 返回 [rejected] HMAC key not configured：通知所属环境的 HMAC 密钥为空。请将其粘贴到设置中。

Webhook 返回 [rejected] invalid HMAC signature：HMAC 密钥属于其他 webhook 或其他环境。如果批量中的某一项签名错误，则整批都会被拒绝。

Webhook 返回 [rejected] busy, retry later：订单在同一时刻正被另一次投递处理，或处理失败。Adyen 会自动重试 webhook。原因记录在日志中。

Webhook URL 在浏览器中显示 [rejected] POST required：这是正常的。该 URL 只接受来自 Adyen 的通知。

保存时的 HMAC 密钥警告：该字段必须包含 Customer Area 中的十六进制 HMAC 密钥。之前的值已保留。

顾客看到 Payment could not be initiated：请查看扩展页面上的 Log 字段（错误始终会被记录）。检查 API 密钥、商户账户，以及在正式模式下的正式 URL 前缀。

顾客看到 This payment method is not available. Please reload the checkout page.：结账会话已与订单不匹配，或付款方式在此期间已被关闭。顾客需要重新加载结账页面。

付款后订单处于审核状态：请阅读 VibeFox Adyen Gateway 选项卡中的备注。Adyen 确认的金额或币种与订单不符，扣款失败，或者付款是在订单状态已被更改之后才到达的。

选项卡中没有退款表单：选项卡会说明原因：Adyen 尚未授权该付款、已全额退款、您的用户组没有修改扩展的权限，或付款所用环境的凭据未配置。

退款失败：选项卡会显示 Adyen 返回的信息。如果使用手动扣款，则只有已扣款的付款可以退款。如果该订单的另一笔退款正在进行，请稍等片刻再重试。

面向开发者：在创建付款链接之前，扩展会触发 OpenCart 事件 adyg_payment_link_request，并附带请求数据和订单。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Adyen Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件以及允许 webhook 在维护模式下通过的 startup action）。如果 Delete data on uninstall 已开启，则其他网关设置（标题、描述、测试模式、商户账户、密钥、正式 URL 前缀、日志记录）和日志都会被删除。如果已关闭，这些设置会保留，供以后重新安装时使用。Adyen 的付款记录（PSP 参考号、webhook 事件、退款）始终保留，因此即使重新安装，之前已付款的订单仍可退款。现有订单会保留其付款备注。

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

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