VibeFox DPO for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本，并启用 SimpleXML 扩展。

DPO Pay 账户：您需要 DPO 商户账户的 Company Token 和 Service Type ID。DPO 会在开通账户时发放这些信息；可向您的 DPO 客户经理索取，或访问 dpogroup.com 获取。DPO 也可能提供带有自己的令牌和服务类型的测试账户。DPO 没有独立的测试服务器：测试账户和正式账户使用相同的 API 地址，账户由令牌决定。

货币：订单货币必须受您的 DPO 账户支持。DPO 最多接受 2 位小数，因此小数位为 3 位的订单总额（例如 KWD 12.345）无法付款。

服务器 cron：一个每 15 分钟调用扩展重新检查网址的 cron 任务（参见配置）。

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

安装

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

OpenCart 3

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

2. 前往 Extensions > Extensions，选择类型 Payments。找到 VibeFox DPO Pay Gateway，点击 Install（绿色的 + 按钮）。您的后台用户需要具有修改付款扩展列表的权限。

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

4. 输入测试和/或正式的 Company Token 与 Service Type（参见配置）。

5. 将 Payment notifications 部分显示的推送通知网址发送给 DPO 支持，并请他们为您的账户设置。将 cron 网址添加到服务器的 cron 任务中。

6. 开启 Enable/Disable 并点击 Save。在测试模式下下一笔测试订单，然后关闭 Test mode 以接受真实付款。

OpenCart 4

1. 进入后台，前往 Extensions > Installer，点击 Upload，选择文件 wcp_dpo_pay.ocmod.zip。不要重命名该文件：OpenCart 4 从文件名读取扩展代码，重命名后的安装包无法工作。

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

3. 前往 Extensions > Extensions，选择类型 Payments。找到 VibeFox DPO Pay Gateway，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的步骤 3 至 6 输入许可证密钥、DPO 凭据、设置推送通知网址和 cron，并测试付款。设置页面及其字段在两个版本中相同。只有推送通知网址和 cron 网址不同（参见付款通知）。

新安装默认关闭付款方式，并开启测试模式。安装时，扩展会创建其交易表以及 cron 网址的密钥令牌。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox DPO Pay Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。如果付款方式已启用，但所选模式的 Company Token 或 Service Type 为空，页面会提示结账时将隐藏该付款方式，保存时也会显示同样的警告。测试模式开启时，页面会显示 测试模式已开启：付款将使用测试账户凭据创建。 没有修改扩展的权限时，页面只能显示设置，无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须是整数，Total 必须是大于或等于 0 的数字；否则不会保存任何内容。

DPO Pay

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

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

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：在 DPO Pay 付款页面上通过银行卡或移动钱包安全付款。

Sort Order：DPO Pay 在结账时付款方式中的排列位置。可留空或输入整数。

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

Total：订单必须达到的结账金额（以店铺默认货币计算），才会提供 DPO Pay。留空则对任何金额都提供 DPO Pay。

API 凭据

DPO 为您的商户账户发放 Company Token 和 Service Type ID，并为测试账户提供单独的凭据。可向您的 DPO 客户经理索取，或访问 dpogroup.com 获取（本部分提供了该网站的链接）。

Test mode：开启时，新付款将使用测试 Company Token 和 Service Type 创建。默认：开启。关闭后，将使用正式凭据接受真实付款。开启期间，顾客在 Confirm Order 步骤会看到 测试模式：付款将使用测试账户创建。 对已有付款的状态查询和取消，始终使用创建该付款时所用的账户。

Test Company Token：您的 DPO 测试账户的 Company Token。

Test Service Type：您的 DPO 测试账户的数字 Service Type ID。

Live Company Token：您的 DPO 正式商户账户的 Company Token。

Live Service Type：您的 DPO 正式商户账户的数字 Service Type ID。

已保存的 Company Token 不会再次显示。该字段保持为空，并显示 已保存：留空即保留原值。 仅在需要更改时输入新值。要删除已保存的令牌，请勾选字段下方的 Clear the saved Company Token on save，然后点击 Save。Service Type 必须是数字。其他任何值都不会被保存：页面会显示警告并保留之前的值，其他设置仍会保存。

付款通知

Push notification URL：推送通知会在顾客付款后立即告知您的店铺已完成付款，即使顾客付款后关闭了浏览器也是如此。该网址无法在控制面板中设置：请联系 DPO 支持，请其为您的账户设置。在 OpenCart 3 中网址格式为 https://your-store/index.php?route=extension/payment/wcp_dpo_pay/notify，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.notify，由您的 OpenCart 安装的店铺前台地址生成。请完全按页面显示的内容复制。该网址必须可以从互联网访问，前面不能有防火墙或基本身份验证。

DPO 的推送通知不带签名，因此其内容从不被视为可信。扩展仅使用它们，通过交易令牌找到付款，然后向 DPO 本身核实结果。非本店铺创建的令牌会被直接拒绝，不会向 DPO 发出任何请求。

定时状态重新检查（cron）：请从服务器的 cron 任务中每 15 分钟调用一次此网址，例如使用 curl。未确认的付款会在跳转后 15 分钟，以及付款时限之后再次向 DPO 核实。该网址包含一个密钥令牌，请妥善保密。在 OpenCart 4 中，网址格式为 https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.cron&token= 加上令牌。如果没有推送网址和 cron，订单只有在顾客付款后返回店铺时才会获得状态。

订单

OpenCart 在 Confirm Order 步骤创建订单时不带状态（缺失订单）。只有在 DPO 确认付款后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Successful payment status：经过验证的成功付款后的订单状态。默认：处理中。如果每笔已付款订单都应完成，请选择已完成；如果每个订单都需要人工审核，请选择您自己的审核状态。

DPO payment on hold status：需要您审核的付款的状态：金额或币种不符、仅授权的付款、多付或少付的交易，或顾客取消后才完成的付款。订单历史中的备注会说明原因。默认：待付款，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled order status：将未付款的 DPO Pay 订单设为此状态时，其未完成的 DPO 付款也会在 DPO 中被取消。默认：已取消。

高级

Logging：将 API 调用和通知写入 OpenCart 日志文件夹（storage/logs）中的 dpo_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移至 dpo_p_debug.old.log.php。错误始终会被记录。令牌会被遮蔽，不记录顾客数据。默认：关闭。

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

Delete data：开启时，卸载扩展会删除网关设置和日志。为订单保存的 DPO 数据始终保留。不开启此选项时，卸载永远不会删除数据。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。Company Token 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 Company Token 会被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 DPO Pay）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 您将被重定向到安全的 DPO Pay 付款页面。 OpenCart 在此步骤创建订单，仍不带状态。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建一笔 DPO 交易，并以订单号和店铺名称作为描述，然后将顾客带到 DPO 付款页面。顾客的姓名、电子邮箱、电话和付款地址会被传递，用于预填页面。在页面上，顾客可使用您 DPO 账户中启用的任何付款方式付款。付款链接有效期为 5 小时。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。如果店铺不要求付款地址（OpenCart 4 默认设置），则传递配送地址。

付款后，顾客返回您的店铺。只有在 DPO 确认后，订单才会被标记为已付款：扩展会在顾客返回时、收到推送通知时以及定时检查时向 DPO 查询交易结果。之后，订单以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。在 OpenCart 4 中，顾客被 DPO 送回时，浏览器不会发送店铺会话，因此扩展会先显示一个短暂页面，从您的店铺再次打开同一返回地址：顾客会保留购物车和登录状态。

如果付款未获确认，顾客会带着以下信息之一返回结账页面（在 OpenCart 4 中，这些信息显示在结账页面上方）。购物车会被保留。

如果顾客点击 DPO 页面上返回店铺的按钮，系统会先检查交易。如果已付款，顾客会看到成功页面。否则，该交易会在 DPO 中被取消，顾客带着购物车返回结账页面。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 为结账保留一个订单并对其进行更新，新的尝试即为同一订单的一笔新 DPO 交易。在发起新付款之前，会检查该订单以及同一购物车的更早订单在 DPO 中未完成的交易。如果其中一笔已付款，则确认该付款，顾客直接进入成功页面，不会被再次扣款。如果其中一笔仍在处理中，顾客会看到 您此前对本订单的付款仍在 DPO 处理中，请等待几分钟后再重试。 否则，旧交易会在 DPO 中被取消，并创建新交易。

OpenCart 4 会在成功页面显示之前一直把订单保留在结账中。如果该订单在此期间已被关闭（例如已取消或已退款），Confirm Order 或 DPO 的返回会将顾客带回结账页面：若订单没有付款，显示 The payment was declined or cancelled. Please try again or choose another payment method.；若订单已有付款，显示 Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order.。如果订单已付款且此后购物车发生了变化（其他商品或数量），则显示 Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order.。在所有这些情况下，下一次 Confirm Order 都会为该购物车支付一个新订单。

如果 DPO 无法发起付款，顾客会停留在 Confirm Order 步骤，按钮上方会显示一条简短提示，提示内容根据 DPO 错误代码选择，例如 DPO Pay 不支持本订单的货币。请选择其他付款方式。 或 金额超出 DPO Pay 允许的限额。请选择其他付款方式或与我们联系。 其他错误会显示 DPO Pay 暂时不可用。请重试或选择其他付款方式。 技术原因会写入日志。

店铺处于维护模式时，推送通知和 cron 网址同样可以正常工作：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会为它们添加一个启动操作。即使您关闭了付款方式，已经发起的付款仍会被确认。

该扩展仅在 DPO 页面上处理一次性付款。不支持店铺退款、保存银行卡、订阅或定期付款，您的网站上也没有银行卡输入框，并且不支持对仅授权的付款进行扣款。

订单

订单状态

无状态（缺失订单）：顾客已被发送至 DPO，但尚未付款；或付款被拒绝或取消；或 DPO 尚未确认付款。在 Sales > Orders 中，此类订单仅在筛选条件 Order Status 设为 Missing Orders 时显示。

Successful payment status（默认 处理中）：付款已通过验证。订单历史中的备注会显示金额、币种、批准代码以及 DPO 交易令牌的开头部分。

DPO payment on hold status（默认 待付款）：DPO 确认了一笔付款，但金额或币种与订单不符，付款仅为授权而未扣款，交易多付或少付，或顾客已取消付款，或订单已被取消。备注会说明原因。请在 DPO 门户中核对该交易。在 DPO 门户中对仅授权的付款进行扣款或撤销，然后更新订单状态。

Cancelled order status（默认 已取消）：当您将扩展中未付款的订单（例如因仅授权付款而被暂停的订单）设为此状态时，其未完成的 DPO 交易也会在 DPO 中被取消。

之后收到的拒绝结果不会改变订单，旧交易的结果也不会导致当前尝试失败。如果 DPO 为已付款的订单确认了第二笔成功付款，该订单不会被改变，并会收到一条可能重复付款的备注，以便您在 DPO 门户中退款。当同一购物车（相同的顾客会话和购物车内容）在另一个订单中被再次付款时（例如在第二个浏览器标签页中），也会在已付款订单中添加同类备注；该另一订单不会获得任何状态。已被您改为其他状态（例如已退款）的订单永远不会被重新打开；迟到的付款只会添加一条备注。

备注是订单 History 中的条目，顾客不可见。扩展在订单页面上没有选项卡。

退款

本版本不支持从店铺退款。请在 DPO 商户门户中退还付款，然后在 OpenCart 中更改订单状态。

许可证密钥

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

没有有效的密钥时，结账时不会向顾客显示 DPO Pay。如果仍然发起了付款，顾客会看到 此付款方式不可用。请选择其他方式。 在同一浏览器中登录后台的管理员，仍可在店铺中看到该付款方式，并标记为 (unlicensed — visible to admins only)（未授权，仅管理员可见），以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 中，此预览不可用：店铺看不到管理员的登录状态，因此在没有有效密钥的情况下，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认。

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

故障排除

DPO Pay 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及所选模式的 Company Token 和 Service Type 是否已填写：测试模式下填写测试字段，否则填写正式字段。缺失时，设置页面会显示警告。另请检查付款地址是否位于所选 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已成功，但订单仍无状态：DPO 账户很可能未设置推送通知网址，而且顾客也未返回店铺。请让 DPO 支持设置设置页面中显示的网址，并检查 cron 是否每 15 分钟调用一次重新检查网址。开启 Logging，并查看扩展页面上的 Log 字段。

推送通知返回 Unknown transaction：交易令牌不属于本店铺的 DPO Pay 付款，例如该推送来自同一 DPO 账户下的另一家店铺。

推送通知返回 Verification failed：无法联系 DPO 核实付款，订单同时被另一请求处理，或无法设置订单状态。DPO 会重复发送通知，定时检查也会确认订单。原因记录在日志中。

推送网址在浏览器中显示 Method not allowed：这是正常现象。该网址只接受来自 DPO 的请求。

cron 网址返回 Forbidden：网址中的令牌不正确。请从设置页面重新复制网址。正常调用会返回 OK checked= 以及已检查的付款数量。

Service Type 未能保存：它必须是 DPO 提供的数字 Service Type ID。

顾客看到 This payment method is not available. Please reload the checkout page.:结账会话与订单不再匹配，或付款方式在此期间已被关闭。顾客需重新加载结账页面。

顾客看到 DPO Pay is temporarily unavailable：DPO 拒绝创建交易，例如 Company Token 或 Service Type 错误，或使用了另一模式的令牌。DPO 结果代码记录在日志中。

顾客看到 DPO 最多接受 2 位小数：订单总额有 3 位小数。DPO 无法扣取此类金额。

顾客看到 This order has already been paid with DPO Pay：DPO 拒绝了同一订单的第二笔付款。请在 DPO 门户中核对付款，并在 OpenCart 中核对订单。

付款后订单处于审核状态：请阅读订单 History 中的备注（参见订单状态），然后在 DPO 门户中核对该交易。

开发人员须知：扩展会触发 OpenCart 事件 wcp_dpo_pay_customer_data（发送给 DPO 的顾客数据）以及 wcp_dpo_pay_payment_time_limit（付款时限，以小时计）。

卸载

前往 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox DPO Pay Gateway 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态；重新安装后，这些设置会恢复为默认值。扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件以及使 DPO 和 cron 能在维护模式下通过的启动操作）。如果 Delete data 已开启，则其余网关设置（标题、描述、测试模式、Company Token、Service Type、日志记录）以及日志都会被删除，重新安装时会生成新的 cron 网址。如果未开启，这些设置会保留，供以后重新安装时使用。为订单保存的 DPO 数据始终会被保留，因此重新安装后，迟到的通知和旧付款的重新检查仍然有效。现有订单会保留其付款备注。

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

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