VibeFox Datatrans for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在较旧的 PHP 版本上。
Datatrans 账户：您需要 Merchant ID、服务器对服务器的 API 密码，以及建议配置的用于 Webhook 的 HMAC-SHA256 签名密钥。测试环境凭据从 Datatrans 测试环境 Web Admin（admin.sandbox.datatrans.com）获取，正式环境凭据从正式环境 Web Admin（admin.datatrans.com）获取。测试环境和正式环境是两个独立的 Datatrans 账户，拥有不同的 Merchant ID 和密钥。
可访问的店铺：Datatrans 从其自身服务器发送 Webhook，因此您的店铺必须能够从互联网访问。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Datatrans Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见「许可证密钥」）。
4. 输入 Datatrans 测试环境 Web Admin 中的测试凭据（参见配置）。
5. 开启 Enable/Disable，然后点击 Save。在测试模式下进行一次测试付款。一切正常后，输入正式环境凭据并关闭 Sandbox mode。
安装时，模块会创建订单状态 Datatrans payment on hold。PrestaShop 默认为所有币种、国家和客户群组启用新的付款模块。您可以在 Payment > Preferences 中限制这些范围；Datatrans 仅会在此处允许的币种下显示。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Datatrans Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。如果已启用付款方式，但当前环境缺少 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.
Datatrans
Enable/Disable：Enable Datatrans Payment 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Datatrans。必填。
Description：结账时显示在付款方式下方的文字。默认：Pay securely via Datatrans.
Sandbox mode：使用 Datatrans 测试环境：测试付款，不收取真实款项。此开关会同时切换 Datatrans 服务器以及新付款所用的凭据。默认：开启。关闭它即可接受真实付款。开启期间，顾客会在付款方式下方看到 Sandbox mode: no real payment is taken. 无论此开关处于何种状态，退款和扣款始终使用付款时所在的环境。
测试环境凭据
请从 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 重新核对。
已保存的密码和签名密钥不会再次显示。字段会保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。签名密钥必须是 Datatrans 发放的十六进制字符串。其他任何值都不会被保存：页面会显示错误并保留之前的值，其他设置仍会保存。
Clear saved secrets：勾选某个密码或签名密钥，然后点击 Save 即可将其删除。字段留空则保留已保存的值。
Webhook URL
此部分显示您店铺的 Webhook URL。启用友好 URL 时，其格式类似 https://your-shop/module/wcp_datatrans_gateway/webhook，前面可能带有语言代码，例如 /en/。模块会在每笔交易中将此 URL 发送给 Datatrans，因此您无需在任何地方手动输入。您也可以将其填入 Datatrans Web Admin 的 Webhook 设置中，以接收在那里进行的扣款和取消的更新；请完全按照设置页面显示的内容复制。在 Datatrans Web Admin 中进行的退款不会反映在订单中。
Webhook 会报告交易的状态。模块会根据以下状态采取相应操作：
设置了 HMAC 签名密钥后，每个 Webhook 都会通过其 Datatrans-Signature 请求头，使用付款所在环境的签名密钥进行验证。没有有效签名的 Webhook 会被拒绝。若未配置签名密钥，模块不会信任 Webhook 的内容，而是通过 Datatrans 状态 API 核对每个 Webhook。若没有 Webhook，只有顾客在付款后返回店铺时才会创建订单。
付款处理
Auto settle：立即扣款（结算）。若关闭，付款仅会获得授权：订单会进入 Datatrans payment on hold 状态，您之后可以通过订单的 Datatrans 区块中的 Capture Datatrans payment 进行扣款，或通过 Cancel Datatrans authorization 释放授权。默认：开启。
Order status after payment：付款结算后的订单状态。
仅授权的付款以及金额或币种不一致的情况，始终会进入 Datatrans payment on hold 状态。
高级
Logging：将付款事件和 API 调用写入模块文件夹中的 logs/datatrans_p_debug.log.php。该文件无法通过网页打开。即使此开关关闭，错误也始终会被记录。不会写入任何密钥、银行卡数据或顾客数据。默认：关闭。
Log：显示日志的大小和最新条目，并提供清空日志的按钮。
Delete data on uninstall：开启后，卸载模块时会删除模块设置和日志。订单中的 Datatrans 付款记录（交易、退款）以及订单状态始终会保留。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Datatrans），并看到提示 You will be redirected to the Datatrans payment page to complete the payment securely. 确认后，模块会按购物车币种以购物车总额创建 Datatrans 交易，并将顾客转到 Datatrans 付款页面。如果店铺语言为德语、英语、法语或意大利语之一，该页面会以相应语言打开。顾客可在此使用您 Datatrans 账户中启用的任何方式付款。此时尚未创建订单。
付款后，顾客会返回您的店铺。只有在 Datatrans 确认付款后，订单才会被标记为已付款：通过 Webhook，或在顾客返回时由服务器向 Datatrans 状态 API 发起请求来确认。返回地址包含购物车的安全密钥，而返回本身绝不会创建订单。随后订单被创建，顾客会看到标准的订单确认页面，并显示 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 按钮；Webhook 一到达即会创建订单。
如果顾客在 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. 购物车会被保留。重新尝试会创建新的 Datatrans 交易；先前尝试的延迟付款仍会被识别。
如果 Datatrans 无法发起付款，顾客会停留在结账页面，并看到 The payment could not be started. Please try again or choose another payment method. 技术原因会写入日志。
即使店铺处于维护模式，Webhook 仍可正常工作，并且不受店铺国家限制的影响。
模块仅在 Datatrans 付款页面上接受一次性付款。店铺中不支持已保存的银行卡或别名、订阅、Lightbox 或 Secure Fields、在设置中选择付款方式，也不支持对预授权进行部分扣款。
订单和退款
订单状态
尚无订单：顾客已被转到 Datatrans，但尚未付款、付款失败或已取消，或 Datatrans 尚未确认。此时只存在购物车。
Payment accepted、Delivered 或 Datatrans payment on hold：付款已结算。状态取决于 Order status after payment。付款会以 Datatrans 交易 ID 记录，备注会显示金额、付款方式、环境以及确认方式（Webhook 或返回）。
授权后的 Datatrans payment on hold：Auto settle 已关闭，付款仅获得授权。请在订单区块中扣款或取消。
付款后的 Datatrans payment on hold：Datatrans 报告的金额或币种与购物车总额不一致（例如，付款开始后购物车被修改），或者付款是在订单被取消之后到达的。备注会对此加以说明。请在 Datatrans Web Admin 中核对该交易，然后完成订单或退还付款。
Canceled：授权已在订单区块或 Datatrans Web Admin 中释放。
Refunded：付款已通过模块全额退款。
如果对已付款或已授权的购物车又收到一笔付款，订单不会改变。备注会提醒您核实，并在 Datatrans 中退还重复的付款。失败或已取消的交易绝不会降低已付款订单的状态。
Datatrans payment 区块
订单页面会显示一个 Datatrans payment 区块，其中包含交易 ID、Datatrans 状态、付款方式、金额、已付和已退款金额、测试付款的 Sandbox 标记、退款记录以及订单的 Datatrans notes。该区块中的操作需要编辑订单的权限；无需访问模块页面。
扣款和取消
对于仅授权的付款，该区块会显示 Capture Datatrans payment 和 Cancel Datatrans authorization。扣款会按当前订单总额结算付款，且金额不得超过已授权金额；之后订单会变为 Order status after payment 所设置的状态。取消会释放授权，并将订单设为 Canceled。两项操作都会发往付款所在的环境。如果 Datatrans 拒绝，该区块会显示错误，并添加一条备注。
退款
在 Datatrans payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Datatrans。确认提示 Refund this amount through Datatrans? This cannot be undone. 支持全额和部分退款，上限为 Datatrans 实际扣除的金额减去之前的退款。退款会发送到付款所在的环境，因此该环境的 Merchant ID 和 API 密码必须已配置。重试的退款不会被重复入账。如果 Datatrans 不接受退款，该区块会显示错误，且不会记录任何退款。成功的退款会连同 Datatrans 退款交易 ID 一起添加到记录和备注中。全额退款会将订单设为 Refunded；部分退款不会改变状态。
对于仅授权的付款，尚未扣除任何款项：只能"退款"全额，这会取消授权。退款要等 Datatrans 结算付款后才可进行；金额不一致的授权在结算之前无法退款。
模块不会生成退款单（credit slip）。订单页面上 PrestaShop 的标准退款按钮不会通过 Datatrans 退还款项。在 Datatrans Web Admin 中进行的退款不会记录在 PrestaShop 中。
许可证密钥
模块需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Datatrans Gateway 位于 Modules > Module Manager > VibeFox Datatrans Gateway > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示已打码的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于将该密钥从本店铺中移除。其下方有一行 Product: presta-payment-datatrans 和链接 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 账户中释放该名额。
没有有效的密钥时，顾客在结账时将看不到 Datatrans。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 前台店铺无法识别您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。已有订单不受影响：已发起的付款仍会被确认，退款也照常进行。
许可证到期后，模块仍会继续工作，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
Datatrans does not appear at checkout：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前环境是否已配置 Merchant ID 和 API 密码：测试模式下检查测试环境字段，否则检查正式环境字段。设置页面会列出缺失的字段。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家以及顾客所属群组。
The payment went through, but no order was created：Datatrans 无法访问 Webhook URL，且顾客也没有返回店铺。请检查店铺是否可以从互联网访问，防火墙是否阻止了发往 Webhook URL 的请求。请检查设置中的签名密钥是否属于付款所在的环境。查看模块页面上的 Log 字段。
Webhook answers Invalid signature：设置中的 HMAC 签名密钥与 Datatrans Web Admin 中的不一致，或者属于另一个环境。请重新复制该密钥。
Webhook answers Not configured or Verification failed：Webhook 需要通过 Datatrans 状态 API 进行核对，但该环境的凭据缺失，或 Datatrans 没有响应。Datatrans 会重试该 Webhook。
Webhook answers Busy, retry：订单正被另一个请求同时确认，或订单无法创建（例如模块已被禁用）。Datatrans 会重试该 Webhook。日志会显示原因。
The webhook URL shows Method not allowed in the browser：这是正常现象。该 URL 只接受来自 Datatrans 的请求。
The HMAC sign key is not saved：密钥必须是十六进制字符串。请从 Datatrans Web Admin 重新复制。
The customer sees Datatrans payments are not configured yet：当前环境的 Merchant ID 或 API 密码缺失。
The customer sees The payment could not be started：请查看 Log 字段。常见原因是 Merchant ID 或 API 密码错误，或者使用了错误环境的凭据。
Order is Datatrans payment on hold after payment：请阅读订单区块中的 Datatrans notes（参见订单状态），然后完成订单或退还付款。
Capture is refused：订单总额高于已授权金额。Datatrans 不能结算超过授权金额的部分。
Refund or capture fails with a message about missing credentials：该付款是在另一个环境中进行的，而该环境的 Merchant ID 或 API 密码尚未设置。请输入后重试。
卸载
进入 Modules > Module Manager，打开 VibeFox Datatrans Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Datatrans 交易和退款以及 Datatrans payment on hold 订单状态始终会保留，因此之前已付款的订单在重新安装后仍可退款或扣款。现有订单会保留其付款备注和交易 ID。
Datatrans 是其各自所有者的商标。本模块与 Datatrans 没有隶属关系，也未获得 Datatrans 的认可。