VibeFox Datatrans for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

Datatrans 账户：您需要商户 ID（merchant ID）、服务器到服务器的 API 密码，以及建议配置的用于 Webhook 的 HMAC-SHA256 签名密钥。沙盒凭据可从 Datatrans 沙盒 Web Admin（admin.sandbox.datatrans.com）获取，正式凭据可从正式 Web Admin（admin.datatrans.com）获取。沙盒和正式环境是两个独立的 Datatrans 账户，拥有不同的商户 ID 和密钥。

可访问的店铺：Datatrans 从其自身服务器发送 Webhook，因此您的店铺必须可以从互联网访问。

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

安装

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

OpenCart 3

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

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

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

4. 输入 Datatrans 沙盒 Web Admin 中的沙盒凭据（参见配置）。

5. 开启 Enable/Disable 并点击 Save。在沙盒模式下进行一次测试付款。一切正常后，输入正式凭据并关闭 Sandbox mode。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的步骤 3 至 5 输入许可证密钥和 Datatrans 凭据，并进行测试付款。设置页面及其字段在两个版本中相同。只有 Webhook URL 不同（参见 Webhook）。

新安装时，支付方式默认关闭，沙盒模式默认开启。每笔交易都会将 Webhook URL 发送给 Datatrans，因此您无需自行设置。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Datatrans Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。当支付方式已启用，但当前环境缺少商户 ID 或 API 密码时，页面会显示 Datatrans is hidden at checkout until these settings are filled in: 以及缺失的字段。沙盒模式开启期间，页面会显示 Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged. 若您没有修改扩展的权限，页面可以查看设置，但无法保存。

保存时，Title 不能为空或超过 128 个字符，Sort Order 必须是整数，Total 必须是 0 或更大的数字，且地理区域和订单状态必须存在。否则不会保存任何内容，并且页面会显示错误。不是十六进制字符串的签名密钥不会被保存：之前的值会保留，其他设置会正常保存，并且页面会显示指明该字段的警告。

Datatrans

Enable/Disable：Enable Datatrans Payment 用于开启或关闭该支付方式。默认：关闭。

Title：顾客在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。默认：Datatrans。必填，最多 128 个字符。

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

Sandbox mode：使用 Datatrans 沙盒：测试付款，不会产生真实费用。该开关会同时切换 Datatrans 服务器以及新付款所使用的凭据。默认：开启。关闭后即可收取真实付款。开启期间，顾客在 Confirm Order 步骤会看到 Sandbox mode: no real payment is taken. 无论此开关如何设置，退款和捕获始终使用付款时所在的环境。

Sort Order：Datatrans 在结账页支付方式中的排列位置。留空或输入整数。

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

Total：订单必须达到的结账总额（按店铺默认货币计算），达到后才会提供 Datatrans。留空则对任意金额都提供 Datatrans。

沙盒凭据

请从 Datatrans 沙盒 Web Admin（admin.sandbox.datatrans.com，页面中提供了链接）复制。签名密钥位于该后台的安全设置中。

Sandbox merchant ID：您沙盒账户的商户 ID。

Sandbox API password：沙盒账户的服务器到服务器 API 密码。

Sandbox HMAC sign key：用于验证 Webhook 的 Datatrans-Signature 请求头的十六进制密钥。若未设置，每个 Webhook 都会通过 Datatrans 状态 API 重新核对。

正式凭据

请从 Datatrans 正式 Web Admin（admin.datatrans.com）复制。

Production merchant ID：您正式账户的商户 ID。

Production API password：正式账户的服务器到服务器 API 密码。

Production HMAC sign key：用于验证正式 Webhook 的 Datatrans-Signature 请求头的十六进制密钥。若未设置，每个 Webhook 都会通过 Datatrans 状态 API 重新核对。

已保存的密码和签名密钥不会再次显示。该字段将保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。要删除已保存的值，请勾选该字段下方的 Clear the saved value on save，然后点击 Save。

Webhook URL

此部分显示您店铺的 Webhook URL。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_datatrans_gateway/webhook，在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_datatrans_gateway/payment/wcp_datatrans_gateway.webhook，由您 OpenCart 安装的前台地址生成。扩展会在每笔交易中将此 URL 发送给 Datatrans，因此您无需在任何地方输入它。您也可以将其填入 Datatrans Web Admin 的 Webhook 设置中，以接收在那里进行的扣款和取消更新；请按设置中显示的内容完整复制。在 Datatrans Web Admin 中进行的退款不会同步到订单。

Webhook 会报告交易的状态。扩展会根据以下状态执行相应操作：

设置 HMAC 签名密钥后，每个 Webhook 都会使用付款所在环境的签名密钥，通过其 Datatrans-Signature 请求头进行验证。没有有效签名的 Webhook 会被拒绝。若没有签名密钥，扩展不会信任 Webhook 的内容，而会通过 Datatrans 状态 API 检查每个 Webhook。若没有 Webhook，订单只有在顾客付款后返回店铺时才会获得状态。

付款处理

Auto settle：立即捕获（结算）付款。若关闭，付款仅会被授权：订单会被置为挂起状态，之后您可以在订单选项卡中使用 Capture Datatrans payment 进行捕获，或使用 Cancel Datatrans authorization 释放授权。默认：开启。

OpenCart 会在 Confirm Order 步骤创建没有状态的订单（缺失订单）。只有在 Datatrans 确认付款后，订单才会获得状态。付款失败或被取消时，订单保持无状态，购物车会被保留。以下每个字段都列出了您 OpenCart 中的订单状态。

Order status after payment：付款结算且金额和币种一致后，订单的状态。默认：Processing。

Datatrans payment on hold：仅授权的付款（Auto settle 已关闭）、金额或币种不符的付款，以及在订单取消后才到达的付款。备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Authorization canceled：当使用 Cancel Datatrans authorization 或在 Datatrans Web Admin 中释放授权时设置。默认：Canceled。

Refunded：在订单页面将付款全额退款后设置。默认：Refunded。

高级

Logging：将付款事件和 API 调用写入 OpenCart 日志文件夹（storage/logs）中的 datatrans_p_debug.log.php。该文件无法通过网页打开，大小达到 5 MB 时会被移动到 datatrans_p_debug.old.log.php。即使此开关关闭，错误也始终会被记录。不会写入任何密钥、银行卡数据或顾客数据。默认：关闭。

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

Delete data on uninstall：开启时，卸载扩展会删除模块设置和日志。订单的 Datatrans 付款记录（交易、退款）会被保留。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。密码和签名密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的密码和签名密钥会被保留。

结账

在 Payment Method 步骤中，顾客选择支付方式（默认为 Datatrans）。在 Confirm Order 步骤中，顾客会看到您的说明以及 You will be redirected to the Datatrans payment page to complete the payment securely. 的提示。OpenCart 会在此步骤创建订单，但仍然没有状态。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建一笔 Datatrans 交易，并以 OpenCart 订单号作为参考，然后将顾客带到 Datatrans 付款页面。如果店铺语言是德语、英语、法语或意大利语之一，该页面会以对应语言打开。顾客在那里可以使用您 Datatrans 账户中已启用的任意付款方式付款。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

付款后，顾客会返回您的店铺。只有在 Datatrans 确认付款后，订单才会被标记为已付款：通过 Webhook，或在顾客返回时由服务器向 Datatrans 状态 API 发出请求来确认。返回地址中带有本次付款尝试的随机令牌，而地址本身绝不会被信任。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面，并显示 Your payment with Datatrans has been received. 对于仅授权的付款，页面会显示 Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. 如果 Datatrans 尚未确认付款，Payment confirmation 页面会显示 Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. 并附带 Check again 和 Back to checkout 按钮；Webhook 一到达就会设置订单状态。在 OpenCart 4 中，Datatrans 把顾客送回时浏览器不会发送店铺会话，因此扩展会先显示一个短暂页面，从您的店铺再次打开同一返回地址：顾客会保留购物车和登录状态。

如果顾客在 Datatrans 页面上取消，会返回结账页面，并显示 The payment was canceled. You can try again or choose another payment method. 如果付款失败，提示为 The payment was not completed. Please try again or choose another payment method. 在 OpenCart 4 中，这些消息显示在结账页面上方。购物车会被保留。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 为结账保留一个订单并对其进行更新，新的尝试即为同一订单的一笔新 Datatrans 交易。在开始新的付款之前，会检查同一购物车之前订单中仍处于打开状态的 Datatrans 交易：已付款或已授权的交易会被确认，而不会再发起新付款；未完成的交易则会在 Datatrans 中被取消。同一购物车只会支付一次：如果该购物车的另一个订单已经付款或已授权，则不会发起新的付款，顾客会被引导至成功页面。如果已付款购物车中另一个订单的付款仍然到达，该订单会保持无状态，已付款的订单会收到一条备注，提示您在 Datatrans 中核查并退还重复的付款。

OpenCart 4 会在成功页面显示之前一直把订单保留在结账中。如果该订单在未付款的情况下已被关闭（例如已取消、您取消了某个授权，或已退款），Confirm Order 或 Datatrans 的返回会将顾客带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，随后的 Confirm Order 会为该购物车支付一个新订单。如果订单已付款且此后购物车发生了变化（其他商品或数量），顾客会被带回结账页面，变更后的购物车会获得新订单及其自己的付款；相同的购物车则会直接进入成功页面，不会再次付款。

如果 Datatrans 无法发起付款，顾客会停留在 Confirm Order 步骤，并显示 The payment could not be started. Please try again or choose another payment method. 技术原因会被写入日志。

即使店铺处于维护模式，Webhook 仍然有效：OpenCart 3 允许支付扩展的请求通过，而在 OpenCart 4 中，扩展会为 Webhook 和顾客返回添加一个启动操作。

本扩展支持在 Datatrans 付款页面进行一次性付款。它不支持保存的银行卡或别名、订阅、您网站上的 Lightbox 或 Secure Fields、在设置中选择付款方式，也不支持授权的部分捕获。

订单与退款

订单状态

No status (missing order)：顾客已被引导至 Datatrans 但尚未付款，付款失败或被取消，或 Datatrans 尚未确认付款。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时，才会显示此类订单。

Order status after payment（默认 Processing）：付款已结算。备注会显示金额、付款方式、Datatrans 交易 ID、环境以及确认方式（Webhook 或返回）。

Datatrans payment on hold after an authorization（默认 Pending）：Auto settle 已关闭，付款仅已授权。请在订单选项卡中进行捕获或取消。

Datatrans payment on hold after payment：Datatrans 报告的金额或币种与订单总额不同，或付款是在订单被取消后到达的。备注会说明原因。请在 Datatrans Web Admin 中检查该交易，然后完成订单或退款。

Authorization canceled（默认 Canceled）：授权已通过订单选项卡或 Datatrans Web Admin 释放。

Refunded（默认 Refunded）：付款已通过扩展全额退款。

如果已付款或已授权的订单再次收到付款，订单不会被更改。备注会要求您核查并在 Datatrans 中退还重复的付款。失败或取消的交易永远不会降低已付款订单的状态。对已退款订单的付款只会添加备注。

备注是订单 History 中的条目，顾客看不到。

VibeFox Datatrans Gateway 选项卡

在 Sales > Orders 中打开一个通过 Datatrans 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Datatrans Gateway 选项卡会显示 Transaction ID（沙盒付款会带有 Sandbox 标签）、Datatrans Status、Payment method、Amount、Paid / refunded 金额、捕获和取消按钮或退款表单、退款记录，以及订单的 Datatrans notes。该选项卡仅显示给有权访问本扩展的用户。其操作需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。

捕获与取消

对于仅授权的付款，该选项卡会显示 Capture Datatrans payment 和 Cancel Datatrans authorization。捕获会按当前订单总额结算付款，且该金额不能超过已授权金额；之后订单会变为 Order status after payment。取消会释放授权，并将订单设为 Authorization canceled。两者都会发送至付款所在的环境。如果 Datatrans 拒绝，选项卡会显示错误，并添加一条备注。

退款

在该选项卡中输入 Amount（系统会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Datatrans。确认提示 Refund this amount through Datatrans? This cannot be undone. 支持全额和部分退款，上限为 Datatrans 实际扣款金额减去之前的退款金额。退款会发送至付款所在的环境，因此该环境的商户 ID 和 API 密码必须已设置。重试的退款不会被重复入账。如果 Datatrans 不接受退款，选项卡会显示错误，且不会记录退款。退款成功后，会在退款记录和备注中添加 Datatrans 退款交易 ID。全额退款会将订单设为 Refunded，且不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。

只有在 Datatrans 结算付款后才能退款。仅授权的付款会改为捕获或取消；金额不一致的授权在结算前无法退款。

Sales > Returns 中的商品退货不会通过 Datatrans 退还款项。在 Datatrans Web Admin 中进行的退款不会记录到 OpenCart 中。

许可证密钥

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

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

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

故障排除

Datatrans 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及当前环境是否已设置商户 ID 和 API 密码：沙盒模式下为沙盒字段，否则为正式字段。设置页面会列出缺失的字段。还请检查付款地址是否位于所选的 Geo Zone 中，以及订单金额是否达到设置中的 Total。

付款已完成，但订单仍无状态：Datatrans 无法访问 Webhook URL，且顾客也没有返回店铺。请检查店铺是否可以从互联网访问，以及防火墙是否阻止了对 Webhook URL 的请求。检查设置中的签名密钥是否属于付款所在的环境。请查看扩展页面上的 Log 字段。

Webhook 返回 Invalid signature：设置中的 HMAC 签名密钥与 Datatrans Web Admin 中的不一致，或属于另一个环境。请重新复制该密钥。

Webhook 返回 Not configured 或 Verification failed：该 Webhook 需要通过 Datatrans 状态 API 核对，但该环境的凭据缺失，或 Datatrans 没有响应。Datatrans 会重试该 Webhook。

Webhook 返回 Busy, retry：订单在同一时刻正被另一个请求确认，或无法设置订单状态。Datatrans 会重试该 Webhook。日志会显示具体原因。

Webhook URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 Datatrans 的请求。

HMAC 签名密钥未能保存：密钥必须是十六进制字符串。请从 Datatrans Web Admin 重新复制。

顾客看到 Datatrans payments are not configured yet：当前环境的商户 ID 或 API 密码缺失。

顾客看到 The payment could not be started：请查看 Log 字段。商户 ID 或 API 密码错误，或使用了错误环境的凭据，是常见原因。

顾客看到 We could not verify the payment：返回地址与该订单的任何付款尝试都不匹配。如果已扣款，Webhook 仍会设置订单状态。

付款后订单处于 on hold 状态：请阅读订单选项卡中的 Datatrans notes（参见订单状态），然后完成订单或退款。

捕获被拒绝：订单总额高于已授权金额。Datatrans 无法结算超过授权金额的部分。

选项卡中没有捕获按钮或退款表单：选项卡会说明原因：付款尚未结算、已全额退款、您的用户组没有修改扩展的权限，或付款环境的凭据缺失。

退款或捕获因缺少凭据而失败：付款是在另一个环境中完成的，而该环境的商户 ID 或 API 密码未设置。请输入后重试。

面向开发者：在创建 Datatrans 交易之前，扩展会触发 OpenCart 事件 datatrans_p_init_request，并传入请求正文和订单。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Datatrans Gateway 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Payment processing 部分中的四个订单状态；重新安装后，这些设置会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除其事件以及使 Datatrans 能在维护模式下通过的启动操作）。如果 Delete data on uninstall 已开启，其他模块设置（标题、说明、沙盒模式、凭据、auto settle、日志记录）和日志都会被删除。如果已关闭，则会保留这些设置，供之后重新安装时使用。Datatrans 的交易和退款始终会保留，因此即使重新安装后，之前已付款的订单仍可退款或捕获。现有订单会保留其付款备注。

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

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