VibeFox Adyen for PrestaShop — 帮助

系统要求

PrestaShop:8.0 至 9.x。

PHP:8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。

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

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Adyen Gateway，点击 Configure。

3. 在模块配置页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。

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

5. 在 Adyen 客户区（测试和正式）中，添加一个 Standard Webhook，URL 使用本模块 Webhook 部分显示的地址（见“配置”）。

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

安装时，模块会创建订单状态 Adyen payment on hold。PrestaShop 会为当时启用的货币、国家和客户群组提供新的付款模块。请在 Payment > Preferences 中检查和修改；之后添加的国家必须在那里勾选。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Adyen Gateway > Configure。每个部分都有自己的 Save 按钮，会保存整个页面。当前模式的设置不完整时，页面会显示 Adyen is hidden at checkout until the test settings are complete（或 live settings），并列出缺少的项目：Merchant account、API 密钥、HMAC 密钥，以及正式模式下的 Live URL prefix。开启测试模式时，页面会显示 Test mode is on: payment links and refunds go to the Adyen test environment, no real money. 保存时，不是十六进制的 HMAC 密钥，以及包含字母、数字和连字符以外字符的正式环境 URL 前缀，都不会被保存：警告会指出该字段，并保留原值。

Adyen

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

Title:顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Adyen。必填。

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

Adyen 账户

API 密钥在 Adyen 客户区的 Developers > API credentials 下创建。请填写两组密钥；Test mode 开关决定使用哪一组。

Test mode:使用 Adyen 测试环境（不涉及真实资金）。开启时，付款链接和退款会使用测试 API 密钥发送到 checkout-test.adyen.com。默认：开启。关闭它即可接受真实付款。开启期间，顾客会在付款方式下方看到 Test mode: no real payment is taken.

Merchant account:您的 Adyen 商户账户名称（不是公司账户），例如 MyShopECOM。测试和正式客户区通常相同。

测试凭据

在 Test mode 开启时使用。

Test API key:来自测试客户区：Developers > API credentials > 您的凭据 > API key。

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

正式凭据

在 Test mode 关闭时使用。

Live API key:来自正式客户区：Developers > API credentials > 您的凭据 > API key。

Live HMAC key:来自正式客户区：Developers > Webhooks > 您的 Standard Webhook > HMAC key（十六进制）。

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

已保存的 API 密钥和 HMAC 密钥不会再次显示。该字段保持为空，其提示以 Saved — leave empty to keep it. 结尾。只有需要更改时才输入新值。

Clear saved secrets:勾选某个密钥并点击 Save 即可删除。空字段会保留已保存的值。

Webhook

订单只由 Adyen Webhook 创建。在客户区（测试和正式）中，进入 Developers > Webhooks，添加一个 Standard webhook，URL 使用本部分 Webhook URL 中显示的地址。启用友好 URL 时，地址形如 https://your-shop/module/wcp_adyen_gateway/webhook，可能带有语言代码，例如 /en/。请完全按设置中显示的 URL 复制，因为 Adyen 不会跟随重定向。选择 JSON 格式，启用 Generate HMAC key，并将密钥复制到 Test HMAC key 或 Live HMAC key。

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

模块处理以下事件：

其他事件会添加到订单备注中。不属于本店购物车的通知（例如客户区中的测试按钮）会被接受并忽略。即使店铺处于维护模式，Webhook 仍可工作，且不会被店铺的国家限制阻止。

高级

Order status after payment:成功的 AUTHORISATION Webhook 设置的订单状态。

金额或币种不一致以及扣款失败的情况，始终会进入 Adyen payment on hold。

Debug log:将 API 调用和 Webhook 事件写入模块文件夹中的 logs/adyg_debug.log.php。该文件无法通过网页打开。即使开关关闭，错误也始终会被记录。日志绝不包含 API 或 HMAC 密钥，也不包含顾客个人信息。默认：关闭。

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

Delete data on uninstall:开启后，卸载模块时会删除模块设置、Adyen 付款记录（PSP 参考号、Webhook 事件、退款）以及日志。订单状态 Adyen payment on hold 和订单会保留。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 Adyen），并看到提示 You will be redirected to Adyen to complete the payment securely. 确认后，模块会按购物车币种为购物车总额创建 Adyen 付款链接，并将顾客转到 Adyen 付款页面。在那里，顾客可以使用您 Adyen 账户中启用的任何方式付款。顾客的电子邮件、姓名、账单国家以及店铺语言会传给 Adyen，付款在 Adyen 中显示为 Cart # 加购物车编号。此时尚未生成订单。

付款后，顾客返回您的店铺。返回本身不会创建或支付订单：只有在 Adyen 通过已签名的 AUTHORISATION Webhook 确认付款，且金额和币种与购物车一致后，订单才会被标记为已付款。如果 Webhook 已经到达，顾客会看到标准订单确认页面，并显示 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 created as soon as Adyen confirms the payment, and you will receive an e-mail.，并带有 Check again 和 Back to checkout 按钮，供未完成付款的顾客使用。

如果付款被拒绝，不会创建订单，顾客可以重试。当顾客为同一购物车发起新的付款时，之前的付款链接会过期，因此也无法再通过它付款。如果购物车已有订单，顾客会被带到该订单的确认页面，而不是新的付款页面。

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

开发者可以使用 actionAdygPaymentLinkRequest 钩子修改付款链接请求。

模块不支持订阅或定期付款、不保存银行卡、不提供站内银行卡输入框（Drop-in 或 Components）、在 PrestaShop 中没有扣款或取消按钮，也不支持 Webhook 的基本身份验证。

订单与退款

订单状态

No order yet:顾客已被转到 Adyen 但尚未付款，付款被拒绝，或 Adyen 尚未确认付款。此时只存在购物车。

Payment accepted, Delivered or Adyen payment on hold:付款已授权。状态取决于 Order status after payment。付款会以 Adyen PSP 参考号作为交易 ID 记录，备注会显示金额、PSP 参考号和付款方式。

Adyen payment on hold after payment:Adyen 确认的金额或币种与购物车总额不一致（例如付款开始后购物车被修改），扣款失败，或付款在订单取消后才到达。备注会说明原因。请在客户区核对付款，然后处理订单或退款。

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

Refunded:付款已通过模块全额退款。

如果已付款的订单又收到第二笔付款成功的结果（例如来自旧的付款链接），订单不会改变。备注会提醒您在客户区检查是否存在重复扣款，并在需要时在那里退款。

Adyen 付款区块

订单页面会显示一个 Adyen payment 区块，包含 PSP 参考号、付款链接、商户账户和环境、付款状态、已付和已退金额、测试付款的 Test mode 标记、退款记录，以及 Adyen notes（模块为订单添加的备注：付款已授权、金额不符、重复付款、扣款、取消、退款结果），按最新在前排列。这些备注是订单的私密消息；PrestaShop 8.2 和 9 不会在订单页面的其他位置显示它们。

退款

在 Adyen payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Adyen。确认提示 Refund this amount through Adyen? This cannot be undone.。支持全额和部分退款。您需要具备编辑订单的权限。退款会按 Adyen 授权的金额和币种进行，因此在金额或币种不符之后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会发送到付款时所用的环境和商户账户，因此该环境的 API 密钥必须已设置。如果 Adyen 不接受请求，区块会显示错误，且不会记录任何退款。

Adyen 异步处理退款：请求会以 received 状态添加到退款记录和备注中，最终结果通过 REFUND 或 REFUND_FAILED Webhook 返回。失败的退款不再计入已退款。当已发送的退款达到已付金额时，订单会设为 Refunded。部分退款不会改变状态。若在 Adyen 中采用手动扣款，则只能退还已扣款的付款。

模块不会生成贷项凭证。订单页面上 PrestaShop 的标准退款按钮不会通过 Adyen 退款。在 Adyen 客户区中进行的退款会通过 Webhook 送达，并添加到备注中。订单状态和贷项凭证不会自动更改。

许可证密钥

模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Adyen Gateway 位于 Modules > Module Manager > VibeFox Adyen Gateway > Configure 页面的设置上方，是第一个区块。将密钥输入 License key，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从此商店中移除密钥。其下方是 Product: presta-payment-adyen 一行，以及打开您 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 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Adyen。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法识别您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已经发起的付款仍会被确认，退款也可以正常进行。

许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台操作期间，系统会自动重新检查状态：密钥输入后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Adyen:请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的设置是否完整：Merchant account、该模式的 API 密钥和 HMAC 密钥，以及正式模式下的 Live URL prefix。设置页面会列出缺少的项目。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家和顾客群组。

付款已完成，但未创建订单:Webhook 未正常工作。在您所用环境（测试或正式）的客户区中，检查 Standard Webhook 是否存在、其 URL 是否与 Webhook URL 中显示的完全一致，以及方法是否为 JSON。检查该 Webhook 的 HMAC 密钥是否位于对应字段中（Test HMAC key 或 Live HMAC key）。若 HMAC 密钥无效或缺失，模块会返回 HTTP 401，Adyen 之后会重试投递，因此修正密钥后订单会自动创建。日志会显示 Webhook rejected: invalid HMAC signature，或显示 HMAC 密钥未配置。

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

Webhook 返回 [rejected] busy, retry later:购物车在同一时刻正被另一次投递处理，或订单无法创建（例如模块已禁用）。Adyen 会自动重试 Webhook。原因见日志。

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

保存时的 HMAC 密钥警告:该字段必须包含客户区中的十六进制 HMAC 密钥。已保留原值。

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

付款后订单显示为 Adyen payment on hold:请阅读订单上的备注。Adyen 确认的金额或币种与购物车不符，扣款失败，或付款发生在取消之后。也可能是您的 Order status after payment 设置造成的。

退款失败:订单必须有 Adyen PSP 参考号，该参考号随 AUTHORISATION Webhook 到达。付款所在环境的凭据必须已设置；否则区块会显示凭据未配置。在手动扣款模式下，只能退还已扣款的付款。

卸载

进入 Modules > Module Manager，打开 VibeFox Adyen Gateway 旁边的菜单，选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块设置、Adyen 付款记录（PSP 参考号、Webhook 事件、退款）和日志都会被删除。如果关闭，则全部保留，以便之后重新安装，这样之前已付款的订单仍可退款。订单状态 Adyen payment on hold 始终保留。现有订单会保留其付款备注和交易 ID。

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