VibeFox DPO for WooCommerce — 帮助

系统要求

WordPress：6.2 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。若未安装，插件将拒绝启用。

PHP：8.0 或更高版本。

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

币种：店铺币种必须受您的 DPO 账户支持，例如 USD、EUR、ZAR、KES、UGX、TZS、RWF、GHS、NGN、ZMW、XOF 或 AED。DPO 最多支持 2 位小数，因此含 3 位小数的订单总额（例如 KWD 12.345）无法支付。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_dpo_pay 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

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

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

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

6. 将设置页面上显示的推送通知 URL 发送给 DPO 支持团队，并请他们为您的账户进行配置。

7. 开启 Enable/Disable。在测试模式下下一个测试订单，然后取消勾选 Test mode 以接受真实付款。

配置

所有设置都在一个页面上：WooCommerce > Settings > Payments > DPO Pay。若网关已启用，但所选模式的 Company Token 或 Service Type 为空，页面会提示此付款方式在结账时将被隐藏，保存时也会显示相同的错误。测试模式开启时，页面会显示 Test mode is on: payments are created with the test account credentials.

常规

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

Title：顾客在结账时看到的付款方式名称。默认值：DPO Pay。

Description：结账时显示在付款方式下方的文字。默认值：Pay securely by card or mobile money on the DPO Pay payment page。

API 凭据

DPO 会为您的商户账户发放 Company Token 和 Service Type ID，并为测试账户单独发放一套。可向您的 DPO 客户经理索取，或在 dpogroup.com 上获取。

Test mode：Use the test account credentials below。开启时，新付款将使用测试用 Company Token 和 Service Type 创建。默认值：开启。取消勾选以使用正式凭据接受真实付款。现有订单的状态检查始终使用创建该付款时所用的账户。

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。

Service Type 必须是数字。其他任何值都不会被保存：页面会显示错误并保留之前的值。若您从 1.0 版本升级，该版本的凭据也会被复制到测试字段中。

付款通知

推送通知会立即告知您的店铺已完成付款，即使顾客在付款后关闭了浏览器也是如此。本节显示推送通知 URL，其格式类似 https://your-site/wc-api/dpo_pay_notify/。该地址不是在后台中设置的：请让 DPO 支持团队为您的账户设置此 URL。

DPO 推送通知不带签名，因此其内容绝不会被信任。插件只用它来查找订单，然后会直接向 DPO 核对付款。即使没有推送 URL，订单仍会在顾客返回店铺时得到确认，并在跳转后 15 分钟以及付款时限到期后由自动重新检查确认。

订单

Successful payment status：经核实付款成功后的订单状态。该状态会立即设置，不会再有第二次状态变更。

高级

Logging：Enable logging 会将 API 调用和通知写入 WooCommerce > Status > Logs，来源为 wcp_dpo_pay。错误始终会被记录。令牌会被掩码处理，不记录顾客数据。默认值：关闭。

Delete data：Delete all plugin data when the plugin is deleted。卸载时会删除设置、保存在订单上的 DPO 数据以及日志。停用插件绝不会删除数据。默认值：关闭。

结账

顾客选择付款方式（默认为 DPO Pay）并下单。插件会按订单币种为订单总额创建一笔 DPO 交易，并以订单编号和您的网站名称作为描述，随后将顾客转到 DPO 付款页面。顾客的姓名、电子邮箱、电话和地址会被传递过去用于预填该页面。在那里，顾客可使用您 DPO 账户中已启用的任何方式付款。付款链接的有效期为 5 小时。

付款后，顾客返回您的店铺。只有在 DPO 确认后，订单才会标记为已付款：插件会在顾客返回时、收到推送通知时以及每次自动重新检查时向 DPO 查询交易结果。付款确认后，顾客会进入订单接收页面。

若付款未被确认，顾客会返回结账页面或 Pay for order 页面，并看到以下其中一条消息：

如果顾客在 DPO 页面点击返回店铺的按钮，订单会按 WooCommerce 的标准方式被取消，其 DPO 付款链接也会在 DPO 一方被取消。

当顾客为同一订单再次付款时，系统会先检查此前的 DPO 付款链接。若已付款，订单会在不再次扣款的情况下完成。若仍在处理中，顾客会看到 Your previous payment for this order is still being processed by DPO. Please wait a few minutes before trying again.；否则旧链接会在 DPO 被取消，并创建一个新链接。

若 DPO 无法开始付款，顾客会看到依据 DPO 错误代码选定的简短消息，例如 DPO Pay 不支持此订单的币种，或金额超出了 DPO Pay 允许的限额，并可以选择其他付款方式。

此付款方式适用于经典结账、结账区块以及 Pay for order 页面。它与 WooCommerce High-Performance Order Storage（HPOS）兼容。

本插件仅在 DPO 页面接受一次性付款。不支持通过 WooCommerce 退款，不支持保存银行卡、订阅或周期性付款，不在您网站上显示银行卡字段，也不会对仅完成授权的付款进行扣款。

订单

订单状态

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

Processing、Completed 或 On hold：付款已经过核实。该状态遵循 Successful payment status 设置。订单备注会显示金额、币种、批准码以及 DPO 交易令牌的开头部分。交易 ID 即为 DPO 交易令牌。

On hold after payment：DPO 已确认一笔付款，但金额或币种与订单不符，或该付款仅完成授权尚未扣款，或该交易为多付或少付，或该订单已被取消。订单备注会说明原因。请在 DPO 后台核对该交易。在 DPO 后台对仅完成授权的付款进行扣款或撤销，然后更新订单。

Failed：付款被拒绝、被取消，或已超过付款时限。顾客可以重新付款。

Cancelled：顾客从 DPO 页面返回了店铺，或订单被您取消，或因未付款订单的 WooCommerce 超时而被取消。未付款的 DPO 付款链接会在 DPO 一方被取消。

之后出现的拒绝消息绝不会改变已付款的订单，而较旧付款链接的结果也绝不会使当前尝试失败。如果 DPO 为一个已付款的订单确认了第二次成功付款，该订单会收到一条关于可能重复付款的备注，以便您在 DPO 后台进行退款。

退款

此版本不支持通过 WooCommerce 退款。请在 DPO 商户后台进行退款，然后在 WooCommerce 中将订单标记为已退款。

许可证密钥

本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥才能工作。许可证区块位于 WooCommerce > Settings > Payments > DPO Pay 页面顶部。将密钥粘贴到 License key 中并点击 Activate。该区块会显示状态，例如许可证的有效截止日期和您的域名。使用 Check now 可重新检查状态，Change key 可输入其他密钥，Remove key 可将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

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

若没有有效的密钥，DPO Pay 不会显示给结账中的顾客。若仍有付款被启动，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍可看到此付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前进行设置和测试。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已经开始的付款仍会被确认。

许可证到期后，插件会继续正常工作，但更新和支持服务需要续订。系统会在后台自动重新检查状态。

故障排查

结账时未显示 DPO Pay：请检查许可证是否处于有效状态、Enable/Disable 是否已开启，以及所选模式的 Company Token 和 Service Type 是否已设置：测试模式下为测试字段，否则为正式字段。设置页面会在缺失这些信息时显示警告。

付款已完成，但订单仍停留在 Pending payment：可能是您的 DPO 账户尚未设置推送通知 URL，且顾客未返回店铺。请让 DPO 支持团队设置设置页面中显示的 URL。订单也会在跳转后 15 分钟由自动重新检查确认。请开启 Logging，并查看 WooCommerce > Status > Logs，来源为 wcp_dpo_pay。

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

推送通知返回 Verification failed：无法连接到 DPO 以核实该付款。DPO 会重新发送该通知，自动重新检查也会确认该订单。

Service Type 无法保存：它必须是来自 DPO 的数字型 Service Type ID。

顾客看到 DPO Pay is temporarily unavailable：DPO 拒绝创建该交易，例如由于 Company Token 或 Service Type 错误，或使用了另一种模式的令牌。DPO 的结果代码记录在 WooCommerce > Status > Logs 中，来源为 wcp_dpo_pay。

顾客看到 DPO 最多接受 2 位小数的提示：该订单总额含有 3 位小数。DPO 无法对这类金额进行扣款。

订单在付款后处于 On hold 状态：请阅读订单备注。已付金额或币种与订单不符，或该付款仅完成授权，或该交易为多付或少付，或该订单已被取消。请在 DPO 后台核对该交易。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址发生变化，请点击 Check now 以为新域名激活该密钥。如果无法连接到许可证服务器，插件会继续以上一次已知的状态运行。

卸载

停用插件会保留所有数据，仅停止已安排的状态检查。要将其移除，请在 Plugins 页面停用并删除它。本插件的许可证密钥和许可证状态始终会被移除。设置、保存在订单上的 DPO 数据、已安排的检查以及日志，只有在开启了 Delete data 时才会被移除。否则这些内容会保留以供日后重新安装使用。现有订单会保留其付款备注和交易 ID。

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