VibeFox Eupago for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

货币：欧元（EUR）。Eupago 仅以欧元收费，因此您的店铺必须启用欧元；当顾客使用其他货币付款时，结账时将隐藏该付款方式。

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

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

安装

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

OpenCart 3

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

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

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

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

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

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_eupago_gateway.ocmod.zip。不要重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法工作。

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

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

4. 按照 OpenCart 3 中第 3 至 5 步的方式填写许可证密钥、Eupago 密钥和 webhook。设置页面及其字段在两个版本中相同。仅 webhook URL 不同（参见 Webhook URL）。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Eupago Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。当付款方式已启用时，如果当前模式的 API 密钥为空（此时结账时会隐藏该付款方式），页面会在设置上方发出提醒；如果沙盒模式开启，页面会显示 Sandbox mode: no real payments are taken.。如果没有修改扩展的权限，页面只能显示设置，无法保存。

保存时，标题不能为空，也不能超过 128 个字符；必须选择一种付款方式；Sort Order 必须为整数；Total 必须为不小于零的数字；并且所选的地理区域和订单状态必须存在。否则会出现错误提示说明问题，例如 Enter a title for the payment method (1 to 128 characters).，且不会保存任何内容。

Eupago

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

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

Description: 顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely via Eupago.

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

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

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

Total: 订单必须达到的结账总额（以店铺默认货币计算），才会提供 Eupago。留空则对任何金额都提供 Eupago。无论此字段如何设置，只有当顾客使用欧元付款时才会提供 Eupago，而 Multibanco 仅适用于 1 € 至 999 999.99 € 的金额。

Eupago 账户

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

Sandbox Mode: 使用 sandbox.eupago.pt 和沙盒密钥。不会产生真实付款。默认：开启。关闭后将使用正式密钥收取真实付款。开启期间，顾客在 Confirm Order 步骤中会看到 SANDBOX / TEST MODE。

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

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

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

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

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

Webhook URL

Webhook 会通知您的店铺某笔付款已完成。请在 Eupago 后台创建一个 Webhook 2.0，使用本部分显示的 URL，方法为 POST，并启用加密。在 OpenCart 3 中该 URL 类似于 https://your-store/index.php?route=extension/payment/wcp_eupago_gateway/webhook，在 OpenCart 4 中类似于 https://your-store/index.php?route=extension/wcp_eupago_gateway/payment/wcp_eupago_gateway.webhook，由您 OpenCart 安装的店铺前台地址生成。请完全按照设置中显示的内容复制该 URL。请在沙盒后台创建一个 webhook，在正式后台再创建另一个 webhook。

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

其他状态无需任何操作。Eupago 发往同一 URL 的旧版 GET 回调也会被接受；它使用 API 密钥进行验证，并且总是报告一笔付款。如果没有通知，订单绝不会被标记为已付款：扩展不会轮询 Eupago，顾客返回也不会支付订单。即使店铺处于维护模式，webhook 也能正常工作，因为 OpenCart 3 会放行付款扩展的请求，而 OpenCart 4 中该扩展会为此添加一个启动动作（也适用于顾客从银行卡页面返回）。

订单

OpenCart 在 Confirm Order 步骤中创建订单，此时没有状态（即缺失订单）。使用 Multibanco 和 MB WAY 时，一旦 Eupago 发出参考号或 MB WAY 请求，订单就会获得等待状态。使用银行卡时，订单只有在收到 Eupago 的通知后才会获得状态。只有当收到经过验证的通知，且其模式、参考号、金额和货币与订单一致时，订单才会被标记为已付款。下面每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment: 付款确认后设置的订单状态。默认：处理中。

Awaiting payment status: 已发出 Multibanco 参考号或 MB WAY 请求，顾客仍需付款。Multibanco 详细信息会随此状态发送（在订单邮件和顾客的订单历史中）。默认：待付款。

Manual review status: Eupago 报告了一笔与订单不符的付款（金额、货币、参考号），或订单取消后的付款，或购物车已被付款的订单的付款。备注会说明原因。默认：待付款，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled status: Eupago 报告某个等待中订单的当前付款已取消或过期。默认：已取消。

Failed status: Eupago 报告某个等待中订单的当前付款失败（ERROR）。默认：失败。

高级

Debug Log: 将 API 调用和通知写入 OpenCart 日志文件夹（storage/logs）中的 eupago_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移至 eupago_p_debug.old.log.php。密钥、电子邮件地址和完整的电话号码不会被记录。错误始终会被记录。默认：关闭。

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

Delete Data on Uninstall: 开启后，卸载扩展时会删除网关设置和日志。订单及其 Eupago 付款记录会被保留。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Eupago）。OpenCart 在 Confirm Order 步骤中创建订单，此时仍没有状态。在 OpenCart 4 中，顾客使用 Payment method options 窗口中付款方式区块的 Choose 按钮选择付款方式，然后点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后会发生什么，取决于 Payment Method。

Multibanco: 顾客会看到 You will receive Multibanco payment details after placing the order. 扩展会以欧元为订单总额创建一个 Multibanco 参考号，订单获得 Awaiting payment status。订单邮件和顾客的订单历史会收到 Multibanco Payment Details 备注，其中包含实体编号、参考号和金额。订单成功页面显示相同的详细信息。顾客可在 ATM 机或网上银行付款。

MB WAY: 顾客需输入 MB WAY Phone Number，该字段已预填订单中的电话号码。葡萄牙号码可以不带 +351 输入。OpenCart 4 默认不要求手机号，因此该字段通常为空，顾客需自行输入号码。号码错误时会显示 Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). 扩展会将付款请求发送到 MB WAY 应用，订单获得 Awaiting payment status。成功页面会提示顾客在显示的遮蔽手机号码上打开 MB WAY 应用，并在 5 分钟内确认该请求。如果 Eupago 拒绝该请求，顾客会停留在 Confirm Order 步骤，并看到 The MB WAY payment could not be started. Check that the phone number is associated with MB WAY and try again.

Credit Card: 顾客会看到 You will be redirected to a secure payment page to enter your card details. 顾客会被转到 Eupago 的银行卡付款页面，页面语言根据店铺语言设置为葡萄牙语、西班牙语或英语。订单保持无状态，购物车会被保留。如果顾客返回时通知已到达，顾客会看到 OpenCart 的订单成功页面。否则，Payment confirmation 页面会显示 Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. 并附有 Check again 和 Back to checkout 按钮。如果银行卡付款失败或被放弃，顾客会返回结账页面，并看到 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. 在 OpenCart 4 中这些消息显示在结账页面上方。

对于每种付款方式，只有在 Eupago 通过经过验证的通知确认付款后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并更新库存。付款详细信息仅在订单等待付款期间显示在成功页面上。如果 Eupago 已报告付款已取消、过期或失败，成功页面会显示 Your Eupago payment was not completed. Please contact us about this order.

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单。OpenCart 4 会更新结账订单，因此在银行卡付款被取消或失败后，顾客会以新的 Eupago 付款支付同一订单。如果同一购物车的较早订单已通过 Eupago 付款，顾客将被引导至成功页面，并且不会创建新的付款。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单期间在未付款的情况下被关闭（例如其 Multibanco 参考号已过期、MB WAY 请求被拒绝，或您取消了订单），顾客会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，下一次点击 Confirm Order 时将为购物车支付一个新订单。如果该订单已付款或正在等待付款，但购物车此后已更改（包括数量变化），提示为 Your previous order is already paid or awaiting its payment. Please confirm the order again: the cart will be paid with a new order. 已付款的订单绝不会对不同的购物车显示为已付款。

如果 Eupago 无法发起付款，顾客会停留在 Confirm Order 步骤，并看到一条简短提示，例如 The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. 订单保持无状态，详细信息会记录在日志中。

该扩展每次安装只提供一种 Eupago 付款方式。它不支持店铺退款、已保存的银行卡、订阅或预授权，也不支持 PayShop、Cofidis Pay、Bizum 或其他 Eupago 付款方式，不支持短信提醒，不支持 Multibanco 到期日，也不支持状态轮询。

订单

订单状态

No status (missing order): 银行卡付款已发起，但 Eupago 尚未确认，或付款失败。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Awaiting payment status (default Pending): 已创建 Multibanco 参考号或 MB WAY 请求。备注会显示实体编号和参考号，或遮蔽后的手机号码。

Order Status After Payment (default Processing): 付款已确认。备注会显示付款方式、Eupago 交易 ID 和参考号。

Manual review status (default Pending): Eupago 报告了金额或货币不符的付款、使用了并非为此订单创建的参考号的付款、针对在此期间已取消或失败的订单的付款（例如迟付的 Multibanco 参考号），或针对购物车已被其他订单付款的订单的付款。备注会说明原因。请核对付款和库存，然后手动完成订单或为顾客退款。此付款之后的通知不会在您不知情的情况下完成订单。

Cancelled status (default Canceled): Eupago 报告等待中订单的当前付款尝试已取消或过期。

Failed status (default Failed): Eupago 报告等待中订单的当前付款尝试出错。

如果 Eupago 为一个已付款的订单报告了另一笔付款（例如较早的 Multibanco 参考号也被付款），订单不会改变。备注会要求您检查是否存在重复付款，并在 Eupago 后台中退款。付款通知绝不会重新打开已付款后又被取消或退款的订单。备注是订单 History 中的条目，顾客看不到。

VibeFox Eupago Gateway 选项卡

在 Sales > Orders 中打开一笔通过 Eupago 付款的订单。在订单页面底部、History 和 Additional 旁边，VibeFox Eupago Gateway 选项卡会列出该订单的每一次付款尝试：Date、Method（沙盒付款会带有 Sandbox 标签）、Amount、Entity / reference / phone、Eupago transaction ID 和 Status。对于处于人工审核中的订单，该选项卡会显示警告。其下方的 Eupago notes 会列出扩展对该订单的备注。该选项卡为只读，仅对有权访问该扩展的用户显示。

退款

本扩展不支持退款。请在 Eupago 后台为顾客退款，然后在 OpenCart 中手动更新订单。Sales > Returns 中的商品退货不会通过 Eupago 退还资金。

许可证密钥

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

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

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

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

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

故障排除

Eupago does not appear at checkout: 检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的 API 密钥（沙盒模式为 Sandbox API Key，正式模式为 Live API Key）是否已设置。顾客必须使用 EUR 付款，并且使用 Multibanco 时订单金额须在 1 € 至 999 999.99 € 之间。另请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

The payment went through, but the order stays in the awaiting status or without a status: Eupago 通知未到达或被拒绝。请在您所用模式的 Eupago 后台中，检查 Webhook 2.0 是否存在，其 URL 是否与 Webhook URL 中显示的完全一致，方法是否为 POST，以及加密是否已启用。检查其密钥是否填入了对应的字段（Sandbox Webhook Key 或 Live Webhook Key）。开启 Debug Log，并查看扩展页面上的 Log 字段。如果一直收不到通知，请在 Eupago 后台检查该付款。

Webhook answers Invalid signature or Missing signature: 扩展中的 webhook 密钥与 webhook 的密钥不匹配，或该 webhook 未加密也未签名。请重新复制密钥，并保持加密开启。

Webhook answers Webhook key not configured: 未设置任何 webhook 密钥。粘贴密钥后，Eupago 会重试通知。

Webhook answers Decryption failed: 签名有效，但无法解密请求体。请检查 Eupago 后台中 Webhook 2.0 的设置。

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

Webhook answers Order not found: 该通知针对的订单在本店铺中没有 Eupago 付款记录，例如使用同一 Eupago 渠道在其他店铺完成的付款。

Webhook answers Busy or Retry: 订单在同一时刻正被另一请求处理，或处理失败。Eupago 会重试通知。原因记录在日志中。

Legacy callback answers Invalid API key: Eupago 发送的 API 密钥与 Live API Key 或 Sandbox API Key 不匹配。如果您在浏览器中打开 webhook URL，也会看到同样的响应；这是正常的。

The customer sees This payment method is temporarily unavailable: 缺少当前模式的 API 密钥。请在设置中输入。

The customer sees The MB WAY payment could not be started: 请检查该手机号码是否已关联 MB WAY，然后重试。

Order is in the manual review status after payment: 请阅读 VibeFox Eupago Gateway 选项卡中的 Eupago notes。金额或货币不符、参考号未知、付款是在订单取消之后到达的，或者购物车已被另一订单付款。请在 Eupago 后台核实该付款，然后完成订单或为顾客退款。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Eupago Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其事件以及在维护模式下放行 webhook 和顾客返回的启动动作）。如果 Delete Data on Uninstall 已开启，则其他网关设置（标题、说明、付款方式、沙盒模式、密钥、调试日志）和日志都会被删除。如果已关闭，这些设置将被保留，以便之后重新安装时使用。订单的 Eupago 付款记录始终会保留，因此重新安装后，旧订单的延迟通知仍可正常工作。现有订单会保留其付款备注。

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

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