VibeFox ePayco for OpenCart — 帮助

要求

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

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 上购买。一个密钥只能用于一个域名。

安装

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

新安装默认关闭付款方式，并关闭测试模式。每次付款时都会将确认 URL 发送给 ePayco，因此无需在 ePayco 控制面板中进行任何设置。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox ePayco Payment > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会说明只有在 ePayco 确认交易后，订单才会获得状态。如果未填写全部四个密钥（此时结账时会隐藏该付款方式），或店铺的默认货币不是 COP 或 USD，页面会发出提醒；测试模式开启期间，页面会显示 Test mode is on: customers pay with ePayco test cards and no real money is charged.。如果没有修改扩展的权限，页面只能显示设置，无法保存。

保存时，Title 不得超过 128 个字符，Sort Order 必须为整数，Total 必须为不小于零的数字，并且所选的地理区域和订单状态必须存在。否则会出现错误提示，指出有问题的字段，且不会保存任何内容。

ePayco

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

Title: 顾客在结账时看到的付款方式名称。该名称也会保存在订单中。最多 128 个字符；如果留空，顾客将看到 ePayco。默认：ePayco。

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

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

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

Total: 订单必须达到的结账总额（以店铺默认货币计算），才会提供 ePayco。留空则对任何金额都提供 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 密钥。请妥善保密。

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

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

结账

Checkout Type: ePayco 结账的打开方式。

确认 URL

确认 URL 会告知您的店铺付款结果。每次付款时它都会自动发送给 ePayco，因此无需在 ePayco 控制面板中进行配置。本部分会显示该 URL。在 OpenCart 3 中其格式类似于 https://your-store/index.php?route=extension/payment/wcp_epayco_payment/confirmation，在 OpenCart 4 中类似于 https://your-store/index.php?route=extension/wcp_epayco_payment/payment/wcp_epayco_payment.confirmation，由您 OpenCart 安装的店铺前台地址生成。它必须能够从互联网访问，且不能被防火墙或基本身份验证阻止。店铺处于维护模式时它同样可用，因为 OpenCart 3 会放行付款扩展的请求，而 OpenCart 4 中该扩展会为此添加一个启动动作。

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

订单

OpenCart 在 Confirm Order 步骤中创建订单，此时订单没有状态（即缺失订单）。只有在 ePayco 确认交易后，订单才会获得状态。被拒绝或被放弃的付款会使订单保持无状态，并保留购物车。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment: ePayco 已批准付款，且金额和货币与订单一致。默认：处理中。

Awaiting Payment Status: ePayco 将付款报告为待处理或被冻结（PSE 转账、现金网络）。当 ePayco 批准或拒绝该付款时，订单会自动更改。默认：待付款。

On Hold (Review) Status: ePayco 批准了金额或货币与订单不符的付款，或者在订单已获得其他状态（例如已取消）之后才批准该付款。备注会说明原因。在 ePayco 控制面板中检查交易之前请勿发货。默认：待付款，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Payment Failed Status: 待处理的付款已被拒绝、失败、过期或取消。新的已批准付款仍会为订单付款。默认：失败。

Reversed Status: ePayco 已撤销该订单的付款。默认：已退款。

高级

Logging: 将 API 错误和付款确认写入 OpenCart 日志文件夹（storage/logs）中的 epc_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移至 epc_p_debug.old.log.php。密钥和顾客数据不会被记录。默认：关闭。即使此选项关闭，错误也始终会被记录。

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

Delete Data on Uninstall: 开启后，卸载扩展时会删除扩展设置和日志。为订单保存的 ePayco 数据始终保留。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 ePayco）。在 Confirm Order 步骤中，顾客会看到您的说明以及 After confirming the order you pay securely in the ePayco checkout (cards, PSE, cash, wallets). 的提示。OpenCart 在此步骤创建订单，此时仍没有状态。在 OpenCart 4 中，顾客使用 Payment method options 窗口中付款方式区块的 Choose 按钮选择付款方式，然后点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建 ePayco 结账会话，并包含税费、订单号以及账单姓名、地址、电子邮件和电话。在 ePayco 中，付款显示为 Order # 加订单号。结账语言为西班牙语或英语，取决于顾客所用店铺的语言。

随后，顾客会看到 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 链接。每次新的 Confirm Order 都会创建新的 ePayco 会话（OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则会更新结账订单，因此新的尝试会支付同一订单）。如果同一购物车的较早订单已经付款或正在等待 ePayco，顾客将被引导至订单成功页面，并且不会再次被扣款。

在 ePayco 结账页面中，顾客使用您 ePayco 账户中已启用的付款方式之一付款。之后，ePayco 会将确认发送到您的店铺，并把顾客带回。只有在 ePayco 确认后，订单才会被标记为已付款：通过已签名的确认，或在顾客返回时由服务器向 ePayco 发起请求。仅凭顾客返回并不会支付订单。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客则会看到 OpenCart 的订单成功页面。

对于待处理的付款（例如 PSE 或现金），订单会获得 Awaiting Payment Status，成功页面显示 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. 购物车会被保留，订单则保持无状态。在 OpenCart 4 中，这些消息显示在结账页面上方。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单期间在未付款的情况下被关闭（例如其待处理付款失败，或您取消了它），顾客会被带回结账页面，并显示关于付款被拒绝的消息，下一次点击 Confirm Order 时将为购物车支付一个新订单。如果该订单已有状态但购物车此后已更改（包括数量变化），顾客会被带回结账页面，下一次点击 Confirm Order 时将以新订单支付新购物车。已付款的订单绝不会对不同的购物车显示为已付款。

如果 ePayco 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 We could not connect to ePayco. Please try again in a moment or choose another payment method. 技术原因会写入日志。

该扩展仅支持一次性付款。它不支持店铺退款、已保存的银行卡、订阅或分期付款，也不会向 ePayco 轮询待处理交易：订单通过 ePayco 确认和顾客返回来更新。

订单

订单状态

No status (missing order): 顾客已被转到 ePayco 但尚未付款，ePayco 尚未确认付款，或付款被拒绝。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Order Status After Payment (default Processing): ePayco 已批准付款。备注会显示 ePayco 参考号、状态、金额、付款方式和批准代码。

Awaiting Payment Status (default Pending): ePayco 将付款报告为待处理或被冻结，例如 PSE 转账或现金付款。当 ePayco 批准后，订单会转为 Order Status After Payment；当付款被拒绝、失败、过期或取消时，订单会转为 Payment Failed Status。OpenCart 会就这些变更向顾客发送电子邮件。

On Hold (Review) Status (default Pending): ePayco 批准了金额或货币与订单不符的付款，或者在您为订单设置了其他状态（例如已取消）之后才批准付款。备注会对此进行说明。发货前请在 ePayco 控制面板中检查交易。

Payment Failed Status (default Failed): 待处理的付款未能完成。备注会显示 ePayco 给出的原因。新的已批准付款仍会为订单付款。延迟出现的失败绝不会更改已付款的订单。

Reversed Status (default Refunded): ePayco 撤销了为此订单付款的交易。

如果 ePayco 报告了同一已付款订单的另一笔已批准付款，订单状态不会改变。备注会要求您检查是否存在重复扣款，并在需要时在 ePayco 中退款。如果顾客为同一购物车支付了第二个订单（例如通过两个打开的 ePayco 窗口），该订单不会获得状态，顾客会看到订单成功页面，而已付款的订单会收到备注，要求您在 ePayco 中退回第二笔付款。对于在正式模式下下达的订单的测试交易，以及已属于其他订单的交易，将被忽略。备注是订单 History 中的条目，顾客看不到。

VibeFox ePayco Payment 选项卡

在 Sales > Orders 中打开一笔通过 ePayco 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox ePayco Payment 选项卡会显示该订单的 ePayco reference (ref_payco)、Transaction ID、State、Payment method、Approval code、Transaction date、Mode（测试付款会带有 Test mode 标签）、Attempt status 以及 ePayco notes。对于处于审核中的订单，该选项卡会显示一条提醒，要求在发货前检查交易。该选项卡为只读，仅对有权访问该扩展的用户显示。

退款

不支持从店铺退款。请在 ePayco 控制面板中退还该付款，然后如有需要，在 OpenCart 中手动更新订单。ePayco 报告的付款交易撤销会将订单设置为 Reversed Status。Sales > Returns 中的商品退货不会通过 ePayco 退还资金。

许可证密钥

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

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

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

故障排除

ePayco does not appear at checkout: 检查许可证是否有效、Enable/Disable 是否开启、四个密钥是否全部已填写，以及顾客是否使用 COP 或 USD 付款。缺少密钥时，设置页面会显示警告。另请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

The payment went through, but the order stays without a status: ePayco 的确认未能到达您的店铺。请检查设置中显示的确认 URL 能否从互联网打开，且未被防火墙、安全扩展或基本身份验证阻止。查看扩展页面上的 Log 字段；开启 Logging 以查看每一条确认。顾客付款后返回店铺时，订单也会获得状态。

Confirmation answers Invalid signature: Customer ID (P_CUST_ID_CLIENTE) 或 Secret Key (P_KEY) 与收取该付款的 ePayco 账户不匹配。请从 ePayco 控制面板重新复制这两项。

Confirmation answers Gateway not configured: P_CUST_ID_CLIENTE 或 P_KEY 为空。请在设置中填写。

Confirmation answers Order not found: 该确认指向的订单在本店铺中没有 ePayco 付款记录。

Confirmation answers Busy, retry later: 该订单正被另一个请求同时更新。ePayco 会重试确认。原因记录在日志中。

The customer sees We could not connect to ePayco: ePayco 拒绝了 PUBLIC_KEY 和 PRIVATE_KEY。日志会显示 ePayco 的回应。请重新复制这两个密钥。

The customer sees ePayco could not start the payment: ePayco 未能创建结账会话。请阅读日志中的 ePayco 错误。

The customer sees This payment method is not available right now: 结账会话已与订单不再匹配，付款方式已在此期间关闭，或密钥已被移除。顾客需要重新加载结账页面。

The ePayco checkout does not open: 顾客看到 The ePayco checkout could not be loaded. Please reload the page or choose another payment method. ePayco 结账脚本无法在付款页面上加载。顾客可以重新加载页面，或使用 Choose another payment method。

A test payment did not pay the order: 测试交易绝不会支付在正式模式下下达的订单。请在 Test Mode 开启时下测试订单。

Order is in the review status after payment: 请阅读 VibeFox ePayco Payment 选项卡中的备注（参见订单状态），并在发货前于 ePayco 控制面板中检查交易。

卸载

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

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

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