VibeFox Paytrail for WooCommerce — 帮助
系统要求
WordPress: 6.0 或更高版本。
WooCommerce: 7.0 或更高版本，已安装并启用。缺少 WooCommerce 时插件将拒绝激活。
PHP: 8.0 或更高版本。
店铺货币：EUR。Paytrail 仅接受欧元。对于任何其他货币，该付款方式在结账时均会隐藏。金额以分（cents）为单位发送。
网站的互联网访问权限：Paytrail 通过服务器到服务器的回调确认每笔付款，因此网站必须能够从互联网访问。即使没有回调，当顾客从 Paytrail 返回时订单仍会被确认。
Paytrail 账户：您需要 Paytrail Merchant Panel（账户或集成详情）中显示的 Merchant ID 和 Secret key。测试无需自有账户：测试模式使用 Paytrail 的公共测试账户。付款方式本身在您的 Paytrail 账户中启用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中前往 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_paytrail_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Paytrail > Manage，或在插件页面上的插件名称下方点击 Settings。
4. 在页面顶部的许可证模块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 若要先试用插件，请勾选 Test mode。对于真实付款，请取消勾选并输入您的 Merchant ID 和 Secret key。无需在 Paytrail 中配置回调 URL。
6. 开启 Enable/Disable 并保存。
配置
所有设置均位于一个页面：WooCommerce > Settings > Payments > Paytrail。测试模式开启时，页面在字段上方显示 Test mode is active.。在正式模式下，如果缺少 Merchant ID 或 Secret key，以及店铺货币不是 EUR 时，系统会向您发出警告。在这两种情况下，Paytrail 都不会在结账时显示。在付款方式列表中，只要正式模式缺少凭据，Paytrail 就会被标记为需要设置。
保存时，包含除数字以外任何字符的 Merchant ID 都不会被保存：系统会显示错误并保留之前的值。
General
Enable/Disable: Enable Paytrail 用于开启或关闭付款方式。默认：关闭。
Title: 结账时向顾客显示的标题。默认：Paytrail。
Description: 结账时向顾客显示的说明文字。默认：Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.
API credentials
您的 Merchant ID 和 Secret key 显示在 Paytrail Merchant Panel（账户或集成详情）中。仅支持 EUR 付款。
Test mode: Use the Paytrail test account。新付款使用 Paytrail 公共测试账户（Merchant ID 375917）而非您自己的凭据。不会收取真实资金。顾客在结账时会看到 Test mode: no real payment will be made.。测试账户的 Secret key 是公开的，因此任何人都可以为在测试模式下创建的订单模拟付款。切勿在正式运营的店铺中保持开启测试模式。默认：关闭。
Merchant ID: 您的 Paytrail 商户 ID（仅限数字）。在测试模式关闭时使用。
Secret key: 您的 Paytrail 密钥。在测试模式关闭时使用。
回调和退款始终使用创建付款时所用模式的凭据，因此在测试和正式模式之间切换不会影响旧订单。
Orders
此部分显示回调 URL，类似于 https://your-site/wc-api/ptg_paytrail/。Paytrail 通过此 URL 进行服务器到服务器的每笔付款确认。它会随每笔付款一同发送，因此无需在 Paytrail 后台进行任何配置，但网站必须能够从互联网访问。
Order status after payment: 已付款订单的状态。状态一步设置到位，因此顾客仅收到一组电子邮件。
Advanced
Debug log: Log API requests and callbacks。写入 WooCommerce > Status > Logs，来源 wcp_paytrail_gateway，不含个人数据或密钥。错误始终会被记录。默认：关闭。
Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted。停用插件绝不会删除任何内容。若没有 Paytrail 交易数据，将无法再从 WooCommerce 对旧订单进行退款。默认：关闭。
结账
顾客选择付款方式（默认为 Paytrail）并下单。插件将针对订单总额（以欧元为单位）创建一笔 Paytrail 付款，并随之发送订单项目行：商品、运费和费用，每项均带有精确到小数点后一位的增值税税率。项目行总额始终等于付款金额；四舍五入差异将被计入某一行或作为 Rounding 行发送。账单和配送地址仅在完整时才会发送，超长值将被截断至 Paytrail 的限制以内。付款页面语言为芬兰语、瑞典语或英语，遵循店铺的语言区域设置。
顾客被引导至 Paytrail 付款页面，选择为您 Paytrail 账户启用的付款方式并完成付款。Paytrail 随后通过两种途径确认付款：将顾客送回您的店铺，并通过服务器到服务器调用回调 URL。两者仅在具有使用该付款尝试凭据生成的有效签名、且仅针对为该订单创建的尝试时才被接受。已付金额将与订单总额进行比对。只有在 Paytrail 以这种方式确认后，订单才会被标记为已付款。插件处理以下 Paytrail 状态：
付款成功后，顾客将看到订单收到页面。付款取消或失败后，顾客将前往 Pay for order 页面，并看到提示 The Paytrail payment was cancelled or failed. You can try again or choose another payment method.。如果付款尚未完成，提示为 The Paytrail payment has not been completed yet. You can try again or choose another payment method.。
如果 Paytrail 无法启动付款，顾客将看到一条简短提示，例如 Could not connect to Paytrail. Please try again in a moment.、Paytrail is temporarily unavailable. Please choose another payment method.（凭据错误）或 Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method.。技术原因将添加到订单备注和日志中。超过 Paytrail 最大限额的订单无法使用 Paytrail 进行支付。
Paytrail 付款无法通过 API 取消。如果顾客发起了新付款，随后又对先前仍处于打开状态的旧付款页面进行了支付，则第二笔付款将在订单备注中报告为待退款的重复付款。
该付款方式适用于经典结账、结账区块和 Pay for order 页面。它与 WooCommerce 高性能订单存储（HPOS）兼容。
顾客在 Paytrail 页面上选择具体的付款方式，而不是在您的结账流程中选择。该插件不具备卡令牌化或保存卡功能，不支持 WooCommerce Subscriptions、店中店、手动账单激活和结算报告。
订单与退款
订单状态
Pending payment: Paytrail 付款已创建，顾客尚未付款。订单备注显示 Paytrail 交易 ID、金额和模式。
Processing or Completed: 付款已确认。状态遵循 Order status after payment 设置。订单备注显示交易、在 Paytrail 使用的付款方式以及金额。交易 ID 即为 Paytrail 交易 ID。
On hold: 付款在服务商处处于待处理状态（账单或延期付款）、已付款金额与订单总额不符、付款在订单取消后到达，或者在正式模式下收到了测试付款（非真实资金）。订单备注会说明原因。请检查订单，然后继续处理或退还付款。
Failed: 最近一次付款尝试失败或已被顾客取消。顾客可以重新付款。
重复或并发的回调绝不会产生重复的备注、重复扣减库存或重复发送电子邮件。如果已付款订单的第二次尝试被支付，订单不会被再次修改；一条 Duplicate payment 备注会提示您在 Paytrail Merchant Panel 中办理退款。
退款
打开订单，点击 Refund，输入金额并点击 Refund via Paytrail（该按钮显示您的 Title）。支持全额和部分退款，仅限金额（无退款商品明细行）。该按钮仅对具有已确认 Paytrail 付款的订单可用。退款使用创建付款时所用模式的凭据，因此对于正式付款，必须设置正式环境凭据。
如果付款方式不支持直接退款，插件会自动发起电子邮件退款：Paytrail 会向顾客发送电子邮件以填写银行账户。这需要订单中包含账单电子邮件。订单备注会注明发起了哪种类型的退款。
退款可以立即完成，也可以稍后处理。Paytrail 随后的确认会作为备注添加。如果 Paytrail 无法完成退款，备注会说明款项未退还给顾客：请通过其他方式退款并在 WooCommerce 中删除该退款记录。如果 Paytrail 直接拒绝退款，WooCommerce 会显示错误且不会记录退款。
在 Paytrail Merchant Panel 中进行的退款不会同步回 WooCommerce。
许可证密钥
插件使用来自 vibefox.net 的 VibeFox 许可证密钥运行。许可证模块位于 WooCommerce > Settings > Payments > Paytrail 的顶部。将密钥粘贴到 License key 中并点击 Activate。该模块显示状态，例如许可证有效期至哪一天以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从本站移除密钥。链接 Manage licenses and domains in your account 可打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从网站移除密钥并不会释放其域名槽位。请在您的 vibefox.net 账户中释放槽位。
若没有有效密钥，Paytrail 不会在结账时向顾客显示。如果仍然发起了付款，顾客将看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍能看到标记为 (unlicensed — visible to admins only) 的付款方式，以便您在购买密钥前配置和测试插件。提醒会显示在插件页面和 WooCommerce 页面上。现有订单不受影响：已发起的付款仍会得到确认，退款功能正常运行。
许可证过期后，插件将继续运行，但更新和支持需要续订。系统会在后台自动重新检查状态。
故障排除
Paytrail 未在结账时显示：检查许可证是否有效，Enable/Disable 是否开启，以及 Test mode 是否开启或 Merchant ID 和 Secret key 是否已填写。检查店铺货币（或 Pay for order 页面上的订单货币）是否为 EUR。设置页面会针对每种问题显示警告。
付款已成功，但订单仍为 Pending payment：回调无法访问您的网站，且顾客未返回店铺。Orders 部分显示的回调 URL 必须能够从互联网访问（无维护模式、基本 HTTP 身份验证或防火墙阻拦）。
回调或返回响应 Payment verification failed.：签名无效，或该付款不属于该订单的某次付款尝试。订单未作更改。请检查 Secret key 是否正确并与 Merchant ID 匹配。
付款未创建：订单备注和日志中会显示 Paytrail 错误，例如凭据错误时显示 Paytrail API error (401): …。开启 Debug log 并查看 WooCommerce > Status > Logs，来源 wcp_paytrail_gateway。
Merchant ID 未保存：必须仅包含数字。请从 Paytrail Merchant Panel 重新复制。
订单状态为 On hold：请阅读订单备注。原因可能是待处理或延期付款、付款金额不符、订单取消后收到付款或在正式模式下收到测试付款。
退款失败：请阅读提示信息。This order has no confirmed Paytrail payment. Refund it manually. 表示没有可退款的已确认 Paytrail 付款。关于缺少正式凭据的提示表示付款是在正式模式下进行的，而尚未设置正式凭据。如果付款方式仅支持电子邮件退款，则订单必须包含账单电子邮件。
开发者钩子：ptg_payment_request 过滤器可在付款请求被签名和发送前对其进行修改；ptg_icon 过滤器可更改结账图标。
许可证模块显示错误：请按照模块中的提示进行操作。例如，如果密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放槽位并点击 Check now。如果网站地址发生变更，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将按最后已知的状态继续运行。
卸载
停用插件会保留所有数据。若要完全移除，请在 Plugins 页面停用并删除它。此插件的许可证密钥和许可证状态将始终被移除。仅在启用了 Delete data on uninstall 的情况下，网关设置、此插件的日志以及订单中存储的 Paytrail 数据（付款尝试、交易数据、退款记录）才会被删除。否则它们将被保留以备日后重新安装。现有订单会保留其付款备注和交易 ID；若没有 Paytrail 数据，旧订单将无法再从 WooCommerce 进行退款。
Paytrail 是其各自所有者的商标。本插件与 Paytrail 无关联，也未获得 Paytrail 认可。