VibeFox Adyen for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法激活。

PHP：8.0 或更高版本。

Adyen 账户：每个您使用的环境（测试环境和正式环境）都需要您的 Adyen 商户账户名称、一个 API 密钥和一个 HMAC 密钥；正式付款还需要正式环境的 URL 前缀。该 API 密钥所属的 API 凭据须具备 Checkout webservice 和 Merchant PAL webservice 角色。HMAC 密钥在 Standard Webhook 中生成（参见「配置」）。测试环境的 Customer Area 地址为 ca-test.adyen.com，正式环境为 ca-live.adyen.com。测试密钥与正式密钥是分开的。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_adyen_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Adyen > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

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

6. 在 Adyen Customer Area（测试和正式环境）中，添加一个 Standard Webhook，URL 使用插件设置中显示的地址（参见「配置」）。

7. 开启 Enable/Disable。在 Test mode 开启的情况下测试一笔付款，然后取消勾选。

配置

所有设置位于同一页面：WooCommerce > Settings > Payments > Adyen。当前模式的设置不完整时，页面会显示 Adyen is hidden at checkout until the test settings are complete（或正式环境设置），并列出缺少的项目：Merchant account、API 密钥、HMAC 密钥，以及正式环境下的 Live URL prefix。保存时，若 HMAC 密钥不是十六进制格式，或正式环境 URL 前缀包含字母、数字和短横线以外的字符，将报错并拒绝保存，同时保留原有的值。

常规

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

Title: 顾客在结账时看到的付款方式名称。默认：Adyen。

Description: 结账时付款方式下方显示的文字。默认：Pay securely via Adyen。

Adyen 账户

API 密钥在 Adyen Customer Area 的 Developers > API credentials 中创建。请同时填写两套密钥；Test mode 开关决定使用哪一套。

Test mode: Use the Adyen test environment (no real money)。开启时，付款链接和退款会通过测试 API 密钥发送至 checkout-test.adyen.com。默认：开启。取消勾选即可接收真实付款。

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，保存时会自动提取前缀。

Webhook

只有 Adyen Webhook 才会将订单标记为已付款。请在 Customer Area（测试和正式环境）中进入 Developers > Webhooks，添加一个 Standard Webhook，URL 使用本设置区块中显示的地址，格式类似 https://your-site/wc-api/adyg_adyen_webhook/。选择 JSON 方式，开启 Generate HMAC key，并将密钥复制到 Test HMAC key 或 Live HMAC key 中。每条通知所属的环境决定使用哪个 HMAC 密钥。没有有效签名的 Webhook 会被拒绝，Adyen 之后会重试。如果没有 Webhook，订单将保持待付款状态。

插件处理以下事件：

其他事件会添加到订单备注中。与本店铺订单无关的通知（例如 Customer Area 中的测试按钮发出的通知）会被接受，但将被忽略。

高级

Order status after payment: 付款成功后设置的订单状态，一次状态变更完成。

Debug log: 将 Log API calls and webhook events 写入 WooCommerce > Status > Logs，来源为 wcp_adyen_gateway。错误始终会被记录。日志绝不包含 API 密钥、HMAC 密钥或顾客个人信息。默认：关闭。

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted。默认：关闭。

结账

顾客选择付款方式（默认为 Adyen）并下单。插件会以订单币种为订单总额创建 Adyen 付款链接，并将顾客转到 Adyen 付款页面。顾客可在该页面使用您 Adyen 账户中启用的任何付款方式。顾客的账单电子邮件、姓名、国家以及店铺语言会传递给 Adyen，付款记录会显示为 Order # 加订单号。

付款后，顾客会返回您店铺的订单已收到页面。返回本身不会将订单标记为已付款：只有当 Adyen 通过经签名的 AUTHORISATION Webhook 确认付款，且金额和币种与订单相符时，订单才会被标记为已付款。

若付款被拒绝，订单将变为失败，顾客可以重试。若顾客为同一订单重新发起付款（例如从 Pay for 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.

对于没有小数位的币种，如 JPY、KRW、IDR 或 VND，请将 WooCommerce > Settings > General > Number of decimals 设为 0。否则总额会被四舍五入为整数单位。

该付款方式支持经典结账和结账区块。兼容 WooCommerce 高性能订单存储（HPOS）。

插件不支持订阅或定期付款，不保存银行卡，不提供站内银行卡输入框（Drop-in 或 Components），WooCommerce 中没有扣款或取消按钮，Webhook 也不支持基本认证。

订单与退款

订单状态

Pending payment: 已创建付款链接，但 Adyen 尚未确认付款。订单备注会显示付款链接、金额和环境。

Processing, Completed or On Hold: 付款已授权。状态按 Order status after payment 设置。订单备注会显示金额、PSP 参考号和付款方式。交易 ID 即为 Adyen 的 PSP 参考号。

On hold after payment: Adyen 确认的金额或币种与订单总额不同。订单备注会同时显示两者，且订单不会被标记为已付款。若扣款失败，已付款订单也会被设为保留，因为款项未能收取。请在 Customer Area 中核对该笔付款。

Failed: 付款被拒绝。已付款、保留和已取消的订单不会因被拒绝的付款而改变。

Cancelled: 该订单的付款已在 Adyen 中取消。

若已付款的订单又收到一次付款成功的结果（例如来自旧的付款链接），订单不会再次被更改。备注会提示您在 Customer Area 中检查是否存在重复扣款，并在必要时在那里退款。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Adyen。支持全额和部分退款。退款会发送至付款所在的环境和商户账户，因此必须设置该环境的 API 密钥。Adyen 异步处理退款：请求会记录在订单上，最终结果由 REFUND 或 REFUND_FAILED Webhook 添加为订单备注。若 Adyen 未接受请求，WooCommerce 会显示错误，且不会记录退款。若在 Adyen 中使用手动扣款，则只能对已扣款的付款退款。

在 Adyen Customer Area 中进行的退款会通过 Webhook 送达，并添加到订单备注中。它们不会自动记录为 WooCommerce 退款。

许可证密钥

本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Adyen 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥仅适用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Adyen。若仍发起付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍可看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常使用。

许可证到期后，插件仍可继续使用，但更新和支持需要续费。系统会在后台自动重新检查状态。

故障排除

结账时未显示 Adyen：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的设置是否完整：Merchant account、该模式的 API 密钥和 HMAC 密钥，正式环境下还需要 Live URL prefix。设置页面会列出缺少的项目。

付款已完成，但订单仍为待付款：Webhook 未正常工作。请在您所用环境（测试或正式）的 Customer Area 中，检查 Standard Webhook 是否存在、其 URL 是否与设置中显示的地址完全一致，以及方式是否为 JSON。请确认该 Webhook 的 HMAC 密钥已填入对应字段（Test HMAC key 或 Live HMAC key）。HMAC 密钥无效或缺失时，插件会返回 HTTP 401，Adyen 之后会重新投递，因此修正密钥后订单会自动更新。日志中会显示 Webhook rejected: invalid HMAC signature，或提示未配置 HMAC 密钥。

Webhook 返回 busy，稍后重试：订单正在被另一次投递同时处理。Adyen 会自动重试该 Webhook。

保存时出现 HMAC 密钥错误：该字段必须填写 Customer Area 中的十六进制 HMAC 密钥。原有的值已被保留。

顾客看到 Payment could not be initiated：请查看订单备注，或开启 Debug log 并在 WooCommerce > Status > Logs 中查看来源为 wcp_adyen_gateway 的日志。请检查 API 密钥、商户账户，以及正式环境下的 Live URL prefix。

付款后订单为保留状态：请阅读订单备注。Adyen 确认的金额或币种与订单不符，或扣款失败。也可能是您的 Order status after payment 设置所致。

退款失败：订单必须有 Adyen PSP 参考号，该参考号随 AUTHORISATION Webhook 送达。必须设置付款所在环境的凭据。若使用手动扣款，则只能对已扣款的付款退款。

许可证区块显示错误：请按照区块中的提示操作。例如，若该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now，为新域名激活密钥。若无法连接许可证服务器，插件将继续使用最后已知的状态。

卸载

停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被移除。仅当开启了 Delete data on uninstall 时，才会移除网关设置以及订单上存储的 Adyen 数据（PSP 参考号、付款链接、已处理的事件）。否则它们将保留，以便日后重新安装时使用。现有订单保留其付款备注和交易 ID。

Adyen 是其各自所有者的商标。本插件与 Adyen 无关联，也未获得 Adyen 认可。