VibeFox ePayco for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

币种：哥伦比亚比索（COP）或美元（USD）。对于使用其他币种的购物车，结账时会隐藏该付款方式。

ePayco 账户：您需要 ePayco 账户的四个密钥：P_CUST_ID_CLIENTE、P_KEY、PUBLIC_KEY 和 PRIVATE_KEY。它们位于 ePayco 后台的 Integrations, API keys 下。相同的密钥适用于测试模式和正式模式。顾客可使用的付款方式（银行卡、PSE、现金支付网络、电子钱包）即为您 ePayco 账户中已启用的方式。

公开网站：店铺的确认 URL 必须可以从互联网访问，不得被防火墙或基本身份验证拦截。

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

安装

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

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

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

4. 输入 ePayco 的四个密钥，并选择结账类型（见配置）。

5. 开启 Enable/Disable 并点击 Save。在开启 Test Mode 并使用 ePayco 测试卡的情况下测试一笔付款，然后关闭 Test Mode。

安装时，模块会创建两个订单状态：Awaiting ePayco payment 和 ePayco payment on hold。PrestaShop 会为所有币种、国家和客户组提供一个新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox ePayco Payment > Configure。每个部分都有自己的 Save 按钮，保存的是整个页面。在字段上方，如果未输入全部四个密钥（此时结账时会隐藏该付款方式），或店铺默认币种不是 COP 或 USD，页面会给出警告。开启测试模式期间，页面会显示 Test mode is on: customers pay with ePayco test cards and no real money is charged.

ePayco

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

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

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

ePayco 账户密钥

四个密钥位于 ePayco 后台的 Integrations, API keys 下。P_CUST_ID_CLIENTE 和 P_KEY 用于验证付款确认；PUBLIC_KEY 和 PRIVATE_KEY 用于创建结账会话。相同的密钥适用于测试模式和正式模式。

Customer ID (P_CUST_ID_CLIENTE)：您的 ePayco 客户 ID（数字）。

Secret Key (P_KEY)：用于验证 ePayco 付款确认的签名。请妥善保密。

Public Key (PUBLIC_KEY)：您的 ePayco 公共 API 密钥。

Private Key (PRIVATE_KEY)：您的 ePayco 私有 API 密钥。请妥善保密。

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

清除已保存的机密密钥：勾选 Secret Key (P_KEY) 或 Private Key (PRIVATE_KEY)，然后点击 Save 以删除。字段留空则保留已保存的值。

Test Mode：结账会话以测试交易的形式创建。顾客使用 ePayco 测试卡付款，不会扣除真实款项。测试交易绝不会为正式模式下创建的订单付款。默认：关闭。开启时，顾客会在付款方式下方和付款页面上看到 TEST MODE — use ePayco test cards, no real money is charged.

结账

Checkout Type：ePayco 结账页面的打开方式。

确认 URL

确认 URL 会告知您的店铺某笔付款的结果。每次付款时它都会自动发送给 ePayco，因此无需在 ePayco 后台进行任何设置。本部分会显示该 URL。启用友好 URL 时，它的形式为 https://your-shop/module/wcp_epayco_payment/confirmation，前面可能带有语言代码，例如 /en/。它必须可以从互联网访问，不得被防火墙或基本身份验证拦截。店铺处于维护模式时它仍然有效，也不会被店铺的国家限制拦截。

每个确认都必须带有使用您的 P_CUST_ID_CLIENTE 和 P_KEY 生成的有效签名。没有有效签名的确认会被拒绝，且不会改变任何内容。如果没有确认，只有在顾客付款后返回店铺时才会创建订单。

高级

Logging：将 API 错误和付款确认写入模块文件夹中的 logs/epc_p_debug.log.php。该文件无法通过网页打开。不记录密钥和顾客数据。默认：关闭。即使关闭，错误也始终会被记录。

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

Delete Data on Uninstall：开启后，卸载模块时会删除模块设置和日志。为订单保存的 ePayco 数据以及模块的订单状态始终保留，因此现有订单仍可正常使用。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 ePayco）并确认。模块会为购物车总额创建一个 ePayco 结账会话，使用购物车币种，并包含税费、购物车编号以及账单姓名、地址、电子邮件和电话。在 ePayco 中，该笔付款显示为 Cart # 加上购物车编号。结账语言为西班牙语或英语，取决于店铺语言。此时尚不存在订单。

随后，顾客会看到 ePayco payment 页面，并显示 Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. ePayco 结账页面会根据 Checkout Type 以弹窗或跳转方式打开。该页面还有 Pay with ePayco 按钮和 Choose another payment method 链接。每次点击付款按钮都会创建一个新的 ePayco 会话。

在 ePayco 结账页面中，顾客使用您 ePayco 账户中已启用的付款方式之一付款。之后，ePayco 会将确认信息发送到您的店铺，并将顾客带回。只有在 ePayco 确认后，订单才会被标记为已付款：通过经签名的确认，或在顾客返回时由服务器向 ePayco 发起请求。仅仅是顾客返回不会支付订单。随后订单被创建，顾客会看到标准的订单确认页面。

对于待处理的付款（例如 PSE 或现金），订单会以 Awaiting ePayco payment 状态创建，确认页面显示 Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. 如果待处理的付款之后被拒绝或过期，页面会显示 Your ePayco payment was not completed. Please contact us about this order. 如果顾客返回时 ePayco 尚未确认付款，则会出现 Payment confirmation 页面，显示 We are waiting for ePayco to confirm your payment. This page does not need to stay open. 以及 Check again 按钮。

如果付款被拒绝，顾客会回到结账页面，并看到 Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. 如果顾客未付款就返回，提示为 The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again. 购物车会被保留，不会创建订单。

如果 ePayco 无法启动付款，顾客会停留在结账页面，并看到简短提示，例如 We could not connect to ePayco. Please try again in a moment or choose another payment method. 技术原因会写入日志。

模块仅支持一次性付款。不支持在店铺内退款、保存银行卡、订阅或分账付款，也不会定期查询 ePayco 中待处理的交易：订单通过 ePayco 确认和顾客返回来更新。

订单

订单状态

No order yet：顾客已被引导至 ePayco 但尚未付款，ePayco 尚未确认付款，或付款被拒绝。仅存在购物车。

Payment accepted：ePayco 已批准付款。付款会以 ePayco 参考号（ref_payco）作为交易 ID 记录，备注中会显示参考号、状态、金额、付款方式和批准代码。

Awaiting ePayco payment：ePayco 将付款报告为待处理或保留，例如 PSE 转账或现金付款。当 ePayco 批准或拒绝付款时，订单会自动更改。

ePayco payment on hold：ePayco 批准了金额或币种与订单不符的付款（例如付款开始后购物车被修改），或在订单已取消后批准了一笔付款。币种一致时，实际付款金额会记录在订单上。发货前请先在 ePayco 后台核对该交易。

Payment error：待处理的付款被拒绝、失败、过期或取消。备注中会显示 ePayco 给出的原因。针对购物车的新付款获批准后，仍会为订单付款。延迟的失败永远不会改变已付款的订单。

Refunded：ePayco 撤销了该订单的付款。

如果 ePayco 报告了已付款订单的另一笔已批准付款，订单状态不会改变。备注会提醒您检查是否存在重复扣款，并在必要时在 ePayco 中退款。针对正式模式订单的测试交易，以及已属于其他订单的交易，都会被忽略并附带备注。

ePayco 付款区块

订单页面会显示一个 ePayco payment 区块，包含 ePayco 参考号（ref_payco）、交易 ID、状态、付款方式、批准代码、交易日期、测试付款的 Test mode 标记以及订单的 ePayco notes。对于处于 ePayco payment on hold 状态的订单，该区块会显示一条警告，提醒您发货前先核对交易。

退款

不支持在店铺内退款。请在 ePayco 后台退还付款，如有需要再在 PrestaShop 中手动更新订单。ePayco 报告的对付款交易的撤销会将订单设为 Refunded。

许可证密钥

模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox ePayco Payment 是 Modules > Module Manager > VibeFox ePayco Payment > Configure 页面上位于设置上方的第一个区块。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期以及您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺中移除密钥。它们下方是 Product: presta-payment-epayco 这一行，以及 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 账户中释放名额。

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

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

故障排除

结账时没有显示 ePayco：请检查许可证是否有效、Enable/Disable 是否开启、四个密钥是否都已输入，以及购物车币种是否为 COP 或 USD。缺少密钥时，设置页面会显示警告。在 Payment > Preferences 中检查该模块是否允许用于购物车币种、顾客所在国家和顾客所属客户组。

付款已完成，但未创建订单：ePayco 的确认没有到达您的店铺。请检查设置中显示的确认 URL 能否从互联网打开，且未被防火墙、安全模块或基本身份验证拦截。查看模块页面上的 Log 字段；开启 Logging 可查看每一次确认。顾客付款后返回店铺时，也会创建订单。

确认返回 «Invalid signature»：Customer ID (P_CUST_ID_CLIENTE) 或 Secret Key (P_KEY) 与收款的 ePayco 账户不匹配。请从 ePayco 后台重新复制这两项。

确认返回 «Gateway not configured»：P_CUST_ID_CLIENTE 或 P_KEY 为空。请在设置中输入。

确认返回 «Order not found»：该确认所指的购物车没有属于本店铺的 ePayco 付款。

确认返回 «Busy, retry later»：订单恰好正被另一请求更新，或订单无法创建（例如模块已禁用）。ePayco 会重试确认。原因记录在日志中。

顾客看到 «We could not connect to ePayco»：ePayco 拒绝了 PUBLIC_KEY 和 PRIVATE_KEY。日志会显示 ePayco 的响应。请重新复制这两个密钥。

顾客看到 «ePayco could not start the payment»：ePayco 未能创建结账会话。请查看日志中的 ePayco 错误。

ePayco 结账页面无法打开：顾客看到 The ePayco checkout could not be loaded. Please reload the page or choose another payment method. 付款页面未能加载 ePayco 结账脚本。顾客可以刷新页面，或使用 Choose another payment method。

测试付款未能支付订单：测试交易绝不会支付在正式模式下下达的订单。请在 Test Mode 开启时下测试订单。

订单处于 ePayco payment on hold：请阅读 ePayco payment 区块中的备注（见订单状态），并在发货前在 ePayco 后台核对交易。

卸载

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

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