VibeFox DPO for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本，并启用 SimpleXML 扩展。缺少这些时，模块拒绝安装。

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

币种：商店币种必须受您的 DPO 账户支持。DPO 最多接受 2 位小数，因此带 3 位小数的购物车总额（例如 KWD 12.345）无法付款。

服务器 cron：一个每 15 分钟调用一次模块重新检查网址的 cron 任务（参见 Configuration）。

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

安装

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

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

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

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

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

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

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

Configuration

所有设置都在模块页面上：Modules > Module Manager > VibeFox DPO Pay Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。当模块已启用，但所选模式的 Company Token 或 Service Type 为空时，页面会提醒您该付款方式在结账时会被隐藏，保存时也会显示同样的提醒。测试模式开启期间，页面会显示 Test mode is on: payments are created with the test account credentials.

DPO Pay

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：开启时，新付款将使用测试 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。

已保存的 Company Token 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。Service Type 必须是数字。其他任何值都不会被保存：页面会显示警告并保留之前的值。

Clear saved Company Tokens：勾选某个 token 并点击 Save 即可将其删除。空字段会保留已保存的值。

付款通知

Push notification URL：推送通知会立即告知您的商店付款已完成，即使顾客付款后关闭了浏览器。该网址不能在后台面板中设置：请让 DPO 支持为您的账户设置此网址。使用友好网址时，它看起来像 https://your-shop/module/wcp_dpo_pay/notify，可能带有语言代码。请按页面显示的内容原样复制。它必须可以从互联网访问，前面不能有维护模式、防火墙或基本身份验证。

DPO 的推送通知没有签名，因此其内容绝不会被信任。模块仅利用它们通过交易令牌找到付款，然后由 DPO 本身核实结果。您的商店未创建的令牌会被直接拒绝，不会向 DPO 发出任何请求。

Scheduled status re-check (cron)：从服务器 cron 任务每 15 分钟调用一次此网址，例如使用 curl。未确认的付款会在跳转后 15 分钟以及付款时限到期后再次与 DPO 核实。该网址包含一个机密令牌，请妥善保管。若没有推送网址和 cron，只有当顾客付款后返回商店时才会创建订单。

订单

Successful payment status：经核实付款成功后的订单状态。

金额或币种不符、仅完成授权以及多付或少付的交易，始终会进入 DPO payment on hold。

高级

Logging：将 API 调用和通知写入模块文件夹中的 logs/dpo_p_debug.log.php。该文件无法通过网页打开。错误始终会被记录。令牌会被掩码处理，不记录任何顾客数据。默认：关闭。

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

Delete data：开启后，卸载模块会删除模块设置和日志。为订单保存的 DPO 数据以及订单状态 DPO payment on hold 始终保留。不启用此项时，卸载从不删除任何数据。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 DPO Pay），并看到提示 You will be redirected to the secure DPO Pay payment page. 确认后，模块会按购物车币种为购物车总额创建一笔 DPO 交易，以购物车编号和您的商店名称作为描述，并将顾客转到 DPO 付款页面。顾客的姓名、电子邮箱、电话和账单地址会被传递，用于预填页面。顾客可在该页面使用您 DPO 账户中已启用的任何方式付款。付款链接有效期为 5 小时。此时尚未创建订单。

付款后，顾客返回您的商店。只有在 DPO 确认后，订单才会标记为已付款：模块会在顾客返回时、推送通知到达时以及计划的重新检查中向 DPO 查询交易结果。随后订单才会被创建，顾客会看到标准的订单确认页面。

如果付款未获确认，顾客会带着以下任一提示返回结账页面。购物车会保留。

如果顾客点击 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 does not support the currency of this order. Please choose another payment method. 或 The amount exceeds the limit allowed by DPO Pay. Please choose another payment method or contact us. 其他错误则显示 DPO Pay is temporarily unavailable. Please try again or choose another payment method. 技术原因会写入日志。

推送通知和 cron 网址在商店处于维护模式时仍可工作，且不受您商店的国家限制影响。

本模块仅在 DPO 页面上接受一次性付款。不支持商店退款、保存银行卡、订阅或定期付款、您网站上的银行卡字段，也不支持仅授权付款的扣款。

订单

订单状态

No order yet：顾客已被转到 DPO 但尚未付款，付款被拒绝或取消，或 DPO 尚未确认付款。此时只存在购物车。

Payment accepted, Delivered or DPO payment on hold：付款已通过核实。状态取决于 Successful payment status。付款会以 DPO 交易令牌作为交易 ID 进行记录。订单页面上的私人备注会显示金额、币种、批准代码和令牌的开头部分。

DPO payment on hold after payment：DPO 已确认付款，但金额或币种与购物车不符，付款仅为授权而未扣款，交易多付或少付，或顾客已取消付款，或订单已被取消。私人备注会说明原因。请在 DPO 后台检查该交易。在 DPO 后台对仅授权的付款进行扣款或撤销，然后更新订单状态。

Cancelled：当您取消模块中一个未付款的订单（例如因仅授权付款而处于保留状态的订单）时，其未完成的 DPO 交易也会在 DPO 被取消。

之后收到的拒绝结果绝不会更改订单，旧交易的结果也绝不会使当前尝试失败。如果 DPO 为一个已付款的订单确认了第二笔成功付款，该订单不会被更改，并会添加一条关于可能重复付款的备注，以便您在 DPO 后台退款。已付款或已退款的订单绝不会被重新打开。

退款

本版本不支持在商店内退款。请在 DPO 商户后台退还该付款，然后在 PrestaShop 中更改订单状态。

许可证密钥

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

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

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

故障排除

DPO Pay does not appear at checkout：请检查许可证是否有效、Enable/Disable 是否开启，以及所选模式的 Company Token 和 Service Type 是否已设置：测试模式下填写测试字段，否则填写正式字段。缺少这些信息时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家和顾客所属群组。

The payment went through, but no order was created：很可能是您的 DPO 账户未设置推送通知网址，且顾客未返回商店。请让 DPO 支持设置设置页面中显示的网址，并检查 cron 是否每 15 分钟调用一次重新检查网址。开启 Logging，并查看模块页面上的 Log 字段。

Push notification answers Unknown transaction：该交易令牌不属于本商店的 DPO Pay 付款，例如推送来自同一 DPO 账户下的另一家商店。

Push notification answers Verification failed：无法联系 DPO 核实付款，购物车在同一时刻正被另一个请求处理，或无法创建订单（例如模块已被禁用）。DPO 会重复发送通知，计划的重新检查也会确认订单。原因记录在日志中。

The push URL shows Method not allowed in the browser：这是正常现象。该网址只接受来自 DPO 的请求。

The cron URL answers Forbidden：网址中的令牌有误。请从 Configure 页面重新复制网址。成功的调用会返回 OK checked= 以及已检查的付款数量。

The Service Type is not saved：必须是 DPO 提供的数字 Service Type ID。

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

The customer sees that DPO accepts at most 2 decimal places：购物车总额有 3 位小数。DPO 无法对此类金额扣款。

The customer sees This order has already been paid with DPO Pay：DPO 拒绝了同一购物车的第二笔付款。请在 DPO 后台检查该付款，并在 PrestaShop 中检查订单。

Order is DPO payment on hold after payment：请阅读订单页面上的私人备注（参见订单状态），然后在 DPO 后台检查该交易。

开发者可以使用钩子 actionWcpDpoPayCustomerData 更改发送给 DPO 的顾客数据，并使用 actionWcpDpoPayPaymentTimeLimit 更改付款时限。

卸载

进入 Modules > Module Manager，打开 VibeFox DPO Pay Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data 已开启，模块设置和日志将被删除。如果未开启，所有设置都会保留，以便日后重新安装。为订单保存的 DPO 数据以及订单状态 DPO payment on hold 始终保留，因此即使重新安装后，旧付款的延迟通知仍能正常处理。现有订单会保留其付款备注和交易 ID。

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