VibeFox Datatrans for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。

PHP：8.0 或更高版本。

HTTPS：您的网站必须可通过 HTTPS 从互联网访问，以便 Datatrans 发送 Webhook。

Datatrans 账户：您需要 Merchant ID、服务器对服务器的 API 密码，以及建议配置的用于 Webhook 的 HMAC-SHA256 签名密钥。测试环境凭据来自 Datatrans 测试环境 Web Admin（admin.sandbox.datatrans.com），正式环境凭据来自正式环境 Web Admin（admin.datatrans.com）。测试环境和正式环境是各自独立的 Datatrans 账户，Merchant ID 和密钥也不相同。

币种：店铺币种（或您的多币种插件所使用的订单币种）必须已在您的 Datatrans 商户账户中启用。

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

安装

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

2. 点击 Activate。WooCommerce 必须处于启用状态。

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

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

5. 输入测试环境凭据；如需接受真实付款，还需输入正式环境凭据（见“配置”）。

6. 开启 Enable/Disable。测试期间请保持 Sandbox mode 开启，之后取消勾选即可接受真实付款。

配置

所有设置都在同一页面：WooCommerce > Settings > Payments > Datatrans。当网关已启用，但当前环境的 Merchant 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.

Webhook

Webhook URL 显示在设置页面顶部，形式类似 https://your-site/wc-api/datatrans_payment_callback/。插件会在每笔交易中将此 URL 发送给 Datatrans，因此您无需在其他任何地方填写。您也可以将它填入 Datatrans Web Admin 的 Webhook 设置，以接收在那里进行的扣款和取消的更新。

Webhook 会报告交易的状态。插件会根据以下状态执行操作：

settled / transmitted: 付款已扣款。订单标记为已付款。

authorized: 付款已预授权但未扣款（仅在 Auto settle 关闭时）。订单被设为暂缓处理。

failed: 付款失败或被拒绝。订单变为失败，可以重新付款。

canceled: 顾客在付款页面取消（订单保持待付款），或预授权已被释放（订单被取消）。

配置 HMAC 签名密钥后，每个 Webhook 都会通过其 Datatrans-Signature 标头进行校验。没有有效签名的 Webhook 会被拒绝。未配置签名密钥时，插件不信任 Webhook 的内容，而是对每个 Webhook 都通过 Datatrans 状态 API 进行核对。没有 Webhook 时，只有在顾客付款后返回店铺时，订单才会得到确认。

常规

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

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

Description: 结账时显示在付款方式下方的文字。默认：Pay securely via Datatrans。

Sandbox mode: Use the Datatrans sandbox (test payments, no real money)。它会同时切换 API 和付款页面的主机，以及下方的凭据。退款和扣款始终使用付款时所在的环境。默认：开启。取消勾选即可接受真实付款。

测试环境凭据

从 Datatrans 测试环境 Web Admin（admin.sandbox.datatrans.com）复制。签名密钥位于该处的安全设置中。

Sandbox merchant ID: 您的测试环境账户的 Merchant ID。

Sandbox API password: 您的测试环境账户的服务器对服务器 API 密码。

Sandbox HMAC sign key: 用于校验 Webhook 的 Datatrans-Signature 标头的十六进制密钥。没有它时，每个 Webhook 都会通过 Datatrans 状态 API 重新核对。

正式环境凭据

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

Production merchant ID: 您的正式环境账户的 Merchant ID。

Production API password: 您的正式环境账户的服务器对服务器 API 密码。

Production HMAC sign key: 用于校验正式环境 Webhook 的 Datatrans-Signature 标头的十六进制密钥。没有它时，每个 Webhook 都会通过 Datatrans 状态 API 重新核对。

签名密钥必须是 Datatrans 签发的十六进制字符串。任何其他值都不会被保存：页面会显示错误并保留之前的值。如果您从 1.0 版升级，该版本的单一凭据集在测试模式开启时会移至测试环境字段，否则保留在正式环境字段中。

付款处理

Auto settle: Capture (settle) payments immediately。默认：开启。如果关闭，付款只会被预授权：订单被设为暂缓处理，您之后可通过订单操作 Capture Datatrans payment 进行扣款，或通过 Cancel Datatrans authorization 释放预授权。

Order status after payment: 付款结算后设置的订单状态。状态会立即设置，不会再有第二次状态变更。

Processing: WooCommerce 默认值（默认）。仅含虚拟可下载商品的订单会变为已完成。

Completed: 每个已付款订单都变为已完成。

On Hold: 每个已付款订单都等待您手动审核。

高级

Logging: Log payment events and API calls 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_datatrans_gateway。错误始终会被记录。不会写入密钥、银行卡数据或顾客数据。默认：关闭。

Delete data on uninstall: Remove the plugin settings when the plugin is deleted。默认：关闭。

结账

顾客选择付款方式（默认为 Datatrans）并下单。插件按订单币种以订单总额创建一笔 Datatrans 交易，以订单 ID 作为参考，并将顾客转到 Datatrans 付款页面。顾客在那里使用您的 Datatrans 账户中启用的任何方式付款，例如银行卡、TWINT 或 PostFinance。如果您的网站使用德语、英语、法语或意大利语，付款页面会以相应语言打开；否则由 Datatrans 选择语言。

付款后，顾客返回您店铺的订单已接收页面。只有在 Datatrans 确认之后，订单才会被标记为已付款：通过 Webhook，或在顾客返回时由服务器端向 Datatrans 状态 API 发出请求。返回地址中带有订单密钥，而返回本身绝不会将订单标记为已付款。

如果顾客在付款页面取消，将被转到 Pay for order 页面，并看到消息 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. 订单仍可付款，顾客可以重试。

如果 Datatrans 无法发起付款，顾客会看到 The payment could not be started. Please try again or choose another payment method. 原因会写入日志。

该付款方式适用于经典结账、结账区块和 Pay for order 页面，并兼容 WooCommerce 高性能订单存储（HPOS）。

本插件仅在 Datatrans 付款页面接受一次性付款。不支持已保存的银行卡或别名、订阅、Lightbox 或 Secure Fields 集成、在设置中选择付款方式，也不支持对预授权进行部分扣款。

订单和退款

订单状态

Pending payment: 顾客已被转到 Datatrans 但尚未付款，在付款页面取消了，或 Datatrans 尚未确认付款。每笔新交易都会连同其 ID 和环境记录在订单备注中。

Processing, Completed or On Hold: 付款已结算。状态遵循 Order status after payment 的设置。订单备注会显示金额、付款方式、Datatrans 交易 ID 和环境（测试或正式）。交易 ID 会保存在订单中。

On hold, authorized: Auto settle 关闭时，付款已预授权但未扣款。打开订单，在订单操作中选择 Capture Datatrans payment 或 Cancel Datatrans authorization。扣款使用订单当前总额，该金额不得高于预授权金额。如果高于预授权金额，或 Datatrans 拒绝扣款或取消，原因会添加到订单备注中。

On hold after payment: Datatrans 报告的金额或币种与订单总额不同（例如付款开始后订单被编辑过），或付款在订单被取消之后才到达。订单备注会对此作出说明。请在 Datatrans Web Admin 中核对该交易，然后履行订单或退还该笔付款。

Failed: 付款失败或被拒绝。顾客可以重试。

Cancelled: 预授权已被释放，通过订单操作或在 Datatrans Web Admin 中完成。

迟到的失败或取消通知绝不会更改已付款订单。如果已付款订单又收到第二笔成功付款，订单不会被更改。备注会提示可能存在重复扣款，并请您在需要时在 Datatrans 中退款。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Datatrans。支持全额和部分退款。退款会发送到付款时所在的环境，因此必须已设置该环境的凭据。重试的退款不会重复入账。如果 Datatrans 不接受退款，WooCommerce 会显示错误，且不会记录任何退款。成功的退款会连同金额和 Datatrans 退款交易 ID 添加到订单备注中。

对于仅预授权的付款，退还全额会取消预授权。在付款被扣款之前，无法进行部分退款。

在 Datatrans Web Admin 中进行的退款不会记录到 WooCommerce。如有需要，请在 WooCommerce 中创建不使用 Refund via Datatrans 的手动退款。

许可证密钥

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

一个密钥只能用于一个域名。将密钥从网站中移除并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，Datatrans 不会在结账时显示给顾客。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，并带有 (unlicensed — visible to admins only) 标记，因此您可以在购买密钥之前先设置并测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会得到确认，退款和扣款也能正常使用。

许可证到期后，插件仍可继续运行，但更新和支持需要续期。状态会在后台自动重新检查。

故障排除

结账时没有出现 Datatrans：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前环境的 Merchant ID 和 API 密码是否已设置：测试模式下检查测试环境字段，否则检查正式环境字段。设置页面会列出缺失的字段。

付款已完成，但订单仍为待付款：Datatrans 无法访问 Webhook URL，且顾客没有返回店铺。请检查网站是否可通过 HTTPS 从互联网访问，以及是否有安全插件或防火墙拦截了对 /wc-api/datatrans_payment_callback/ 的请求。检查设置中的签名密钥是否属于该笔付款所在的环境。开启 Logging，然后查看 WooCommerce > Status > Logs，来源 wcp_datatrans_gateway。

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

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

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

顾客看到 The payment could not be started：Merchant ID 或 API 密码有误，属于另一个环境，或该币种未在您的 Datatrans 账户中启用。开启 Logging 以查看原因。

付款后订单处于暂缓处理：请阅读订单备注。可能是已付金额或币种与订单不同，付款在订单被取消之后才到达，或付款仅被预授权并等待扣款。

无法扣款：订单总额高于预授权金额。扣款使用订单当前总额，因此请将其降低到不超过预授权金额。

退款失败并提示与凭据有关的消息：该笔付款是在另一个环境中进行的，而该环境的凭据尚未设置。请输入后重试。对于已预授权的付款，请退还全额，或先进行扣款。

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

对于开发者，readme 提到了过滤器 wcp_datatrans_gateway_init_request，例如可用来限制 Datatrans 页面上显示的付款方式。

卸载

停用插件会保留所有数据。要将其移除，请在 Plugins 页面中先停用再删除。本插件的许可证密钥和许可证状态始终会被移除。只有在 Delete data on uninstall 已开启时，才会移除网关设置；否则它们会保留，以便日后重新安装。现有订单会保留其付款备注和交易 ID。

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