VibeFox Eupago for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

货币：欧元（EUR）。Eupago 仅收取欧元，因此对于使用其他货币的购物车，结账时会隐藏该付款方式。

Eupago 账户：您需要 Eupago 渠道的 API 密钥，以及您在 Eupago 后台创建的 Webhook 2.0 的密钥（参见配置）。正式环境后台为 clientes.eupago.pt，沙盒后台为 sandbox.eupago.pt。沙盒与正式环境是各自独立的账户，密钥也各不相同。

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

安装

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

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

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

4. 输入您 Eupago 渠道的 API 密钥，在 Eupago 后台创建 Webhook 2.0，并粘贴其密钥（参见配置）。

5. 选择 Payment Method，开启 Enable/Disable，然后点击 Save。在沙盒模式下下一笔测试订单，然后关闭 Sandbox Mode。

安装时，模块会创建两个订单状态：Awaiting Eupago payment 和 Eupago payment on hold。PrestaShop 会为所有货币、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中限制这些设置；欧元必须保持为该模块允许的货币。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Eupago Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。启用付款方式后，如果当前模式的 API 密钥为空，页面会在字段上方发出警告（此时该付款方式会在结账时隐藏）；沙盒模式开启期间，页面会显示 Sandbox mode: no real payments are taken.

Eupago

Enable/Disable：Enable Eupago Gateway 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Eupago。必填：标题为空时会显示 Enter a title for the payment method.

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

Payment Method：结账时提供的唯一一种 Eupago 付款方式。

Order Status After Payment：付款确认后设置的订单状态。

Eupago 账户

请在 Eupago 后台获取您渠道的 API 密钥和 Webhook 2.0 密钥：clientes.eupago.pt（正式环境）或 sandbox.eupago.pt（沙盒）。沙盒与正式环境是各自独立的账户，密钥也各不相同。

Sandbox Mode：使用 sandbox.eupago.pt 和沙盒密钥。不会收取任何真实付款。默认：开启。如需使用正式密钥收取真实付款，请关闭。开启期间，顾客会在付款方式下方看到 SANDBOX / TEST MODE。

Live API Key：您正式环境 Eupago 渠道的 API 密钥（clientes.eupago.pt）。

Live Webhook Key：您正式环境 Webhook 2.0 的加密密钥。必填：没有有效签名的通知会被拒绝。

Sandbox API Key：您沙盒渠道的 API 密钥（sandbox.eupago.pt）。

Sandbox Webhook Key：您沙盒 Webhook 2.0 的加密密钥。

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

Clear saved keys：勾选某个密钥，然后点击 Save 将其删除。字段为空时会保留已保存的值。

Webhook URL

Webhook 会通知您的商店某笔付款已完成。请在 Eupago 后台创建 Webhook 2.0，使用本部分显示的 URL，方法为 POST，并启用加密。如果启用了友好 URL，它看起来像 https://your-shop/module/wcp_eupago_gateway/webhook，前面可能带有 /pt/ 之类的语言代码。请完全按照设置页面显示的内容复制 URL。沙盒后台和正式环境后台各创建一个 webhook。

将每个 webhook 的密钥复制到 Sandbox Webhook Key 或 Live Webhook Key。没有有效签名的 webhook 会被拒绝。未加密的 webhook 只有在 Eupago 对其签名时才会被接受，因此请保持加密开启。通知必须使用付款发起时所用模式的密钥签名，因此沙盒通知绝不会支付正式环境的付款。模块会对以下通知状态作出响应：

其他状态无需任何操作。Eupago 发送到同一 URL 的旧版 GET 回调同样会被接受；它通过 API 密钥验证，并且始终表示一笔付款。没有通知时，订单绝不会被标记为已付款：模块不会轮询 Eupago，顾客返回商店也不会使订单付款。即使商店处于维护模式，webhook 仍可正常工作，并且不会受商店国家限制的影响。

高级

Debug Log：将 API 调用和通知写入模块文件夹中的 logs/eupago_p_debug.log.php。该文件无法通过网页打开。密钥、邮箱地址和完整手机号码不会被记录。错误始终会被记录。默认：关闭。

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

Delete Data on Uninstall：开启后，卸载模块会删除网关设置、本模块的 Eupago 付款记录和日志。订单及其付款数据会被保留。默认：关闭。

结账

顾客在付款步骤选择付款方式（默认为 Eupago），然后下单。之后的流程取决于 Payment Method 的设置。

Multibanco：在结账时，顾客会看到 You will receive Multibanco payment details after placing the order. 模块会按购物车总额创建 Multibanco 参考编号。订单会立即以 Awaiting Eupago payment 状态创建，与任何 PrestaShop 订单一样，购物车随之清空。订单确认页面会显示 Multibanco Payment Details，包括实体编号、参考编号和金额。相同信息也会添加到订单确认邮件的付款行中。顾客可在 ATM 机或网上银行付款。

MB WAY：在结账时，顾客需填写 MB WAY Phone Number，该字段会预先填入账单地址中的手机号码。葡萄牙号码可省略 +351 输入。号码错误时会显示 Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). 模块会将付款请求发送到 MB WAY 应用，并以 Awaiting Eupago payment 状态创建订单。订单确认页面会要求顾客在隐藏部分数字的手机号码上打开 MB WAY 应用，并在 5 分钟内确认请求。

Credit Card：在结账时，顾客会看到 You will be redirected to a secure payment page to enter your card details. 顾客会被跳转到 Eupago 银行卡页面，页面语言根据购物车语言显示为葡萄牙语、西班牙语或英语。此时尚未创建订单，购物车会被保留。只有在 Eupago 确认付款后才会创建订单。如果顾客返回时通知已经到达，他会看到标准的订单确认页面。否则，Payment confirmation 页面会显示 Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed.，并带有 Check again 按钮。如果银行卡付款失败或被放弃，顾客会返回结账页面，并看到 The card payment was not completed. You can try again or choose another payment method. 或 The card payment was cancelled. You can try again or choose another payment method.

对于所有付款方式，只有在 Eupago 通过经过验证的通知确认付款后，订单才会被标记为已付款。付款详情仅在订单处于 Awaiting Eupago payment 状态时显示。如果 Eupago 随后报告付款已取消、已过期或失败，且订单未付款，订单确认页面会显示 Your Eupago payment was not completed. Please contact us about this order.

如果 Eupago 无法发起付款，顾客会停留在结账页面，并看到简短提示，例如 The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. 不会创建订单，详细信息记录在日志中。购物车使用其他货币时，会显示 Eupago only supports payments in EUR.

模块每次安装只提供一种 Eupago 付款方式。不支持通过 PrestaShop 退款、保存银行卡、订阅或预授权，也不支持 PayShop、Cofidis Pay、Bizum 或其他 Eupago 付款方式，不支持短信提醒、Multibanco 到期日和状态轮询。

订单

订单状态

No order yet：已发起银行卡付款，但 Eupago 尚未确认。此时只存在购物车。

Awaiting Eupago payment：已创建 Multibanco 参考编号或 MB WAY 请求。备注中会显示实体编号和参考编号，或隐藏部分数字的手机号码。

Payment accepted or Delivered：付款已确认。状态遵循 Order Status After Payment 的设置。付款会以 Eupago 交易 ID 作为交易 ID 进行记录，备注中会显示付款方式、交易 ID 和参考编号。

Eupago payment on hold：Eupago 报告了一笔金额或货币不符的付款，或使用了并非为该购物车创建的参考编号，或者付款针对的是在此期间已取消或失败的订单（例如迟到付款的 Multibanco 参考编号）。备注会说明原因。请检查付款和库存，然后手动完成订单，或向顾客退款。此后针对该付款的通知不会在您不知情的情况下完成订单。

Canceled：Eupago 报告等待中订单的当前付款尝试已取消或过期。

Payment error：Eupago 报告等待中订单的当前付款尝试出现错误。

如果 Eupago 对一个已付款的订单报告了另一笔付款（例如较早的 Multibanco 参考编号也被付款），订单不会有任何变化。备注会提醒您检查是否存在重复付款，并在 Eupago 后台退款。已付款后又被取消或退款的订单，永远不会因为付款通知而重新打开。

Eupago 付款区块

订单页面会显示 Eupago payment 区块，列出购物车的每一次付款尝试：日期、付款方式、沙盒付款的 Sandbox 标识、金额、Multibanco 实体编号和参考编号或 MB WAY 隐藏部分数字的手机号码、Eupago 交易 ID 和状态。订单处于 Eupago payment on hold 时，该区块会显示 Manual review 警告。其下方的 Eupago notes 列出模块在该订单上的备注，最新的排在最前。

退款

不支持通过 PrestaShop 退款。请在 Eupago 后台向顾客退款，并在 PrestaShop 中手动更新订单。订单页面上的标准 PrestaShop 退款按钮不会通过 Eupago 退回款项。

许可证密钥

模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Eupago Gateway 是 Modules > Module Manager > VibeFox Eupago Gateway > Configure 页面上位于设置上方的第一个区块。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期以及您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺中移除密钥。它们下方是 Product: presta-payment-eupago 这一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加上日期。店铺地址变更后，或您在账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最近一次已知的状态运行。

一个密钥只能用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

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

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

故障排除

结账时没有显示 Eupago：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的 API 密钥是否已设置（沙盒模式为 Sandbox API Key，正式模式为 Live API Key）。购物车货币必须为 EUR，并且在 Payment > Preferences 中，模块必须允许欧元、顾客所在国家和顾客所在群组。使用 Multibanco 时，订单总额必须在 1 € 至 999,999.99 € 之间。

已完成付款，但订单仍为 Awaiting Eupago payment，或者没有创建订单：Eupago 通知没有到达，或被拒绝。请在您所用模式的 Eupago 后台检查：Webhook 2.0 是否存在，其 URL 是否与 Webhook URL 中显示的完全一致，方法是否为 POST，加密是否开启。检查其密钥是否填在对应字段中（Sandbox Webhook Key 或 Live Webhook Key）。开启 Debug Log，并查看模块页面上的 Log 字段。如果通知始终没有到达，请在 Eupago 后台检查该付款。

Webhook 返回 Invalid signature 或 Missing signature：模块中的 webhook 密钥与 webhook 的密钥不匹配，或者 webhook 既未加密也未签名。请重新复制密钥，并保持加密开启。

Webhook 返回 Webhook key not configured：两个 webhook 密钥都未设置。粘贴密钥后，Eupago 会重新发送通知。

Webhook 返回 Decryption failed：签名有效，但无法解密内容。请检查 Eupago 后台中的 Webhook 2.0 设置。

Webhook 返回 Environment mismatch：通知使用的是与付款发起模式不同的模式密钥签名。沙盒通知绝不会支付正式环境的付款，反之亦然。请检查沙盒和正式密钥是否被调换。

Webhook 返回 Order not found：通知对应的购物车在本商店中没有 Eupago 付款，例如使用同一 Eupago 渠道在其他商店完成的付款。

Webhook 返回 Busy or Retry：购物车在同一时刻正被另一个请求处理，或者无法创建订单（例如模块已被禁用）。Eupago 会重新发送通知。原因记录在日志中。

旧版回调返回 Invalid API key：Eupago 发送的 API 密钥与 Live API Key 或 Sandbox API Key 不匹配。如果在浏览器中打开 webhook URL，也会出现相同的响应，这是正常现象。

顾客看到 The MB WAY payment could not be started：请检查该手机号码是否已关联 MB WAY，然后重试。

付款后订单处于 Eupago payment on hold：请阅读 Eupago payment 区块中的 Eupago notes。可能是金额或货币不符，参考编号未知，或者付款在订单取消之后才到达。请在 Eupago 后台核实付款，然后完成订单或向顾客退款。

卸载

前往 Modules > Module Manager，打开 VibeFox Eupago Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，则会删除网关设置、本模块的 Eupago 付款记录和日志。如果已关闭，所有设置和记录都会保留，以便日后重新安装。订单状态 Awaiting Eupago payment 和 Eupago payment on hold 始终会被保留。现有订单会保留其付款备注和交易 ID。

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