VibeFox Eupago for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。

PHP：8.0 或更高版本。

店铺货币：欧元（EUR）。Eupago 仅收取欧元，因此对于其他货币，结账时会隐藏该付款方式。

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

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

安装

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

2. 点击 Activate。

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

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

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

6. 选择 Payment Method，开启 Enable/Disable，在沙盒模式下下一笔测试订单，然后取消勾选 Sandbox Mode。

配置

所有设置都在同一页面：WooCommerce > Settings > Payments > Eupago。启用网关后，如果当前模式的 API 密钥为空，页面会发出警告（此时网关会在结账时隐藏）；如果开启了沙盒模式，页面会显示 Sandbox mode: no real payments are taken.。在付款方式列表中，设置当前模式的 API 密钥之前，Eupago 会被标记为需要处理；沙盒模式下还会显示测试模式标识。

常规

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

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

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

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

Order Status After Payment：付款确认后设置的订单状态：Processing（默认）或 Completed。状态会立即设置，仅更改一次状态并发送一封邮件。

Eupago 账户

在 Eupago 后台获取您渠道的 API 密钥和 Webhook 2.0 密钥：clientes.eupago.pt（正式）或 sandbox.eupago.pt（沙盒）。

Sandbox Mode：Enable sandbox/test mode 将使用 sandbox.eupago.pt 和沙盒密钥。不会收取任何真实付款。默认：on。取消勾选即可使用正式密钥收取真实付款。

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 的加密密钥。

Webhook URL

Webhook 会通知您的店铺已完成付款。请在 Eupago 后台创建 Webhook 2.0，使用本设置页面此部分显示的 URL，方法选择 POST，并启用加密。URL 形如 https://your-site/wc-api/eupago_payment_callback/。请分别在沙盒后台和正式后台各创建一个 Webhook。

将每个 Webhook 的密钥复制到 Sandbox Webhook Key 或 Live Webhook Key。没有有效签名的 Webhook 会被拒绝。未加密的 Webhook 只有在 Eupago 对其签名时才会被接受，因此请保持加密开启。插件会对以下通知状态做出响应：

其他状态无需处理。Eupago 发送到同一 URL 的旧版 GET 回调也会被接受；它通过 API 密钥验证，并且始终表示一笔付款。若没有通知，订单绝不会被标记为已付款：插件不会轮询 Eupago，顾客返回页面也不会使订单付款。

高级

Debug Log：Enable logging 会将 API 调用和通知写入 WooCommerce > Status > Logs，来源为 wcp_eupago_gateway。密钥、邮件和完整手机号码不会被记录。错误始终会被记录。默认：off。

Delete Data on Uninstall：Delete all plugin data when uninstalling。如果勾选，删除插件时将移除网关设置和日志。订单及其付款数据会被保留。默认：off。

结账

顾客选择付款方式（默认为 Eupago）并下单。在沙盒模式下，结账页面会显示 SANDBOX / TEST MODE。后续流程取决于 Payment Method。

Multibanco：结账时，顾客会看到 You will receive Multibanco payment details after placing the order.。插件会为订单总额创建 Multibanco 参考编号。订单会被置为保留，库存减少，购物车被清空。订单接收页面会显示 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 应用。订单会被置为保留，库存减少，购物车被清空。订单接收页面会提示顾客打开 MB WAY 应用，并在 5 分钟内确认请求。

Credit Card：结账时，顾客会看到 You will be redirected to a secure payment page to enter your card details.。顾客会被引导至 Eupago 银行卡页面，页面语言会根据站点语言设为葡萄牙语、西班牙语或英语。订单保持待付款状态，购物车保留。付款后，顾客会返回订单接收页面，在收到通知之前该页面会显示 Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed.。若银行卡付款失败或被放弃，顾客会进入 Pay for order 页面，并看到 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 通过经验证的通知确认后，订单才会被标记为已付款。顾客可以通过 Pay for 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. 订单不会改变，详细信息记录在日志中。

该付款方式适用于经典结账、结账区块和 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。面向顾客的文字已翻译为葡萄牙语。

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

订单

订单状态

Pending payment：已发起银行卡付款，但 Eupago 尚未确认。

On hold, awaiting payment：已创建 Multibanco 参考编号或 MB WAY 请求。订单备注会显示实体编号和参考编号，或被隐藏的手机号码。

Processing or Completed：付款已确认。状态遵循 Order Status After Payment 的设置。订单备注会显示付款方式、Eupago 交易 ID 和参考编号。订单的交易 ID 即为 Eupago 交易 ID。

On hold, manual review：Eupago 报告的付款金额或币种不符，或参考编号并非为该订单创建，或订单在此期间已取消或失败（例如 Multibanco 参考编号被迟付）。备注会对此作出说明。请核对付款和库存，然后手动完成订单或为顾客退款。此后针对该付款的通知不会在您不知情的情况下完成订单。

Cancelled：对于未付款订单的当前付款尝试，Eupago 报告付款已取消或已过期。

Failed：对于未付款订单的当前付款尝试，Eupago 报告出现错误。

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

退款：不支持通过 WooCommerce 退款。请在 Eupago 后台为顾客退款，并使用 Refund manually 在 WooCommerce 中记录退款。

许可证密钥

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

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

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

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

故障排除

结账时没有显示 Eupago：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 API 密钥是否已设置（沙盒模式为 Sandbox API Key，正式模式为 Live API Key），以及店铺货币是否为 EUR。使用 Multibanco 时，订单金额须在 1 € 至 999 999.99 € 之间。

付款已成功，但订单仍为 Pending payment 或 On hold：Eupago 的通知未到达或被拒绝。在您所用模式的 Eupago 后台中，请检查 Webhook 2.0 是否存在、其 URL 是否与设置中显示的完全一致、方法是否为 POST，以及加密是否开启。确认其密钥位于对应字段（Sandbox Webhook Key 或 Live Webhook Key）中。开启 Debug Log，并在 WooCommerce > Status > Logs 中查看来源 wcp_eupago_gateway。如果通知始终未到达，请在 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：该通知使用的是与订单下单模式不同的密钥签名。沙盒通知绝不会为正式订单付款，反之亦然。

旧版回调返回 Invalid API key：Eupago 发送的 API 密钥与 Live API Key 或 Sandbox API Key 不匹配。

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

付款后订单处于 On hold：请阅读订单备注。金额或币种不符，参考编号未知，或付款发生在订单取消之后。请在 Eupago 后台核实付款，然后完成订单或为顾客退款。

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

对于开发者，插件文档列出了过滤器 eupago_p_icon（结账图标）和 eupago_p_card_language（Eupago 银行卡页面的语言：PT、EN 或 ES）。

卸载

停用插件会保留所有数据。若要删除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。仅当 Delete Data on Uninstall 已开启时，网关设置和日志才会被删除；否则将保留，以便日后重新安装。订单及其 Eupago 参考编号始终会被保留。现有订单会保留其付款备注和交易 ID。

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