VibeFox ePayco for WooCommerce — 帮助

系统要求

WordPress：5.8 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce，插件无法启用。

PHP：8.0 或更高版本。

店铺货币：哥伦比亚比索（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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_epayco_payment 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

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

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

5. 输入四个 ePayco 密钥，并选择结账类型（参见「配置」）。

6. 启用 Enable/Disable。使用 ePayco 测试卡在 Test Mode 下测试付款，然后取消勾选 Test Mode。

配置

所有设置位于同一页面：WooCommerce > Settings > Payments > ePayco。在字段上方，页面会在以下情况提示您：未输入全部四个密钥（此时结账时不显示该付款方式）、店铺货币不是 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）。请妥善保密。

Test Mode：Enable test mode 会将结账会话创建为测试交易。顾客使用 ePayco 测试卡付款，不会扣除真实款项。测试交易绝不会为正式模式下创建的订单付款。默认：关闭。

结账

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

确认 URL

确认 URL 用于告知您的店铺付款结果。每次付款时都会自动发送给 ePayco，因此无需在 ePayco 后台进行任何配置。此部分显示该 URL，格式如：https://your-site/wc-api/epc_p/。该 URL 必须可从互联网访问，不能被维护模式、防火墙或基本身份验证拦截。

每一条确认信息都必须带有使用您的 P_CUST_ID_CLIENTE 和 P_KEY 生成的有效签名。签名无效的确认会被拒绝，且不会更改订单。若没有确认信息，订单只会在顾客付款后返回店铺时才会更新。

高级

Logging：Enable logging 会将 API 错误和付款确认写入 WooCommerce > Status > Logs，来源为 wcp_epayco_payment。密钥和顾客数据不会被记录。默认：关闭。

Delete Data on Uninstall：Remove the gateway settings and logs when the plugin is deleted。停用插件不会删除任何内容。订单中保存的 ePayco 数据会保留。默认：关闭。

结账

顾客选择付款方式（默认为 ePayco）并提交订单。插件会以订单货币为订单总额创建 ePayco 结账会话，并附带订单税费、订单号以及账单姓名、地址、电子邮件和电话。结账语言为西班牙语或英语，跟随站点语言。随后顾客会进入订单付款页面，该页面显示 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 链接。在测试模式下，页面和结账页面显示 TEST MODE — use ePayco test cards, no real money is charged.

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

如果付款尚未确认，订单接收页面会显示 We are waiting for ePayco to confirm your payment. This page does not need to stay open. 对于待处理的付款（例如 PSE 或现金），页面会显示 Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved.

如果付款被拒绝，顾客会返回 Pay for order 页面，并显示 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. 原因会添加到订单备注和日志中。

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

插件仅支持一次性付款。不支持通过 WooCommerce 退款、保存银行卡、订阅或分账付款，也不会向 ePayco 查询待处理交易：订单通过 ePayco 确认和顾客返回来更新。

订单

订单状态

Pending payment：顾客已被跳转到 ePayco，但尚未付款，或 ePayco 尚未确认付款。

Processing：付款已被接受（仅包含虚拟可下载商品的订单会变为已完成，即 WooCommerce 默认行为）。订单备注显示 ePayco 参考号、状态、金额、付款方式和批准代码。订单的交易 ID 即为 ePayco 参考号（ref_payco）。

On hold, payment pending：ePayco 将付款报告为待处理或被保留，例如 PSE 转账或现金付款。ePayco 确认或拒绝后，订单会自动更改。

On hold, amount/currency mismatch：ePayco 批准了一笔金额或币种与订单不一致的付款。发货前请先在 ePayco 后台核对该交易。

On hold, payment for a cancelled order：订单取消后，ePayco 批准了一笔付款。请恢复订单，或在 ePayco 中退款。

Failed：付款被拒绝、失败、过期、被放弃、取消或被反欺诈系统拦截。备注会显示 ePayco 给出的原因。顾客可以重新付款。延迟出现的失败绝不会更改已付款的订单。

Refunded：ePayco 已对此订单的付款进行退款。

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

退款：不支持通过 WooCommerce 退款。请在 ePayco 后台退款，然后使用 Refund manually 在 WooCommerce 中记录退款。

许可证密钥

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

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

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

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

故障排除

结账时不显示 ePayco：请检查许可证是否有效、Enable/Disable 是否开启、四个密钥是否全部已输入，以及店铺货币是否为 COP 或 USD。在 Pay for order 页面，会检查订单货币。设置页面会在缺少某项内容时显示警告。

付款已完成，但订单仍为 Pending payment：ePayco 的确认信息未能到达您的店铺。请检查设置中显示的确认 URL 能否从互联网打开，并且未被维护模式、防火墙、安全插件或基本身份验证拦截。开启 Logging，并查看 WooCommerce > Status > Logs，来源 wcp_epayco_payment。顾客付款后返回店铺时，订单也会更新。

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

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

确认返回 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 开启时下测试订单。

订单处于 On hold：请阅读订单备注。ePayco 将付款报告为待处理，批准的金额或币种与订单不一致，或付款发生在订单取消之后。发货前请在 ePayco 后台核对该交易。

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

对于开发人员，插件文档列出了以下过滤器：epc_p_supported_currencies（提供该付款方式的货币）、epc_p_session_payload（发送给 ePayco 的数据）和 epc_p_icon（结账图标）。

卸载

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

ePayco 是其各自所有者的商标。本插件与 ePayco 无关联，亦未获得 ePayco 的认可。