VibeFox Paytrail for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。旧版 PHP 上模块无法安装。
货币：EUR。Paytrail 只接受欧元。购物车使用其他货币时，结账页面会隐藏该付款方式。金额以分为单位发送。
店铺的互联网访问：Paytrail 通过服务器到服务器的回调确认每笔付款，因此店铺应可从互联网访问。即使没有回调，顾客从 Paytrail 返回时订单仍会创建。
Paytrail 账户：您需要商户 ID（Merchant ID）和密钥（Secret key），可在 Paytrail 商户后台（账户或集成信息）中查看。测试无需账户：测试模式使用 Paytrail 公共测试账户。付款方式本身需在您的 Paytrail 账户中启用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只适用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者以后在模块列表中找到 VibeFox Paytrail Gateway 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 若想先试用模块，请开启 Test mode。若要进行真实付款，请关闭它并输入您的 Merchant ID 和 Secret key。无需在 Paytrail 中配置回调 URL。
5. 开启 Enable/Disable 并点击 Save。
安装时，模块会创建两个订单状态：Awaiting Paytrail payment 和 Paytrail payment on hold。PrestaShop 为所有货币、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中加以限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Paytrail Gateway > Configure。每个部分都有各自的 Save 按钮，点击后保存整个页面。开启测试模式时，字段上方会显示 Test mode is active. Payments use the public Paytrail test account — no real money is charged.。在正式模式下，如果缺少 Merchant ID 或 Secret key，或 Merchant ID 为公共测试账户 375917，页面会发出警告。店铺货币不是 EUR 时也会发出警告。在这些情况下，结账页面都不会显示 Paytrail。
保存时，包含数字以外字符的 Merchant ID 不会被保存，并会显示错误 Paytrail merchant ID must contain digits only. The previous value was kept.。Title 不能为空。
Paytrail
Enable/Disable：Enable Paytrail 用于开启或关闭该付款方式。默认：off。
Title：结账时向顾客显示的标题，也是订单中保存的付款方式名称。默认：Paytrail。必填。
Description：结账时在付款方式下方向顾客显示的文字。默认：Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.
API 凭据
您的 Merchant ID 和 Secret key 显示在 Paytrail 商户后台（账户或集成信息）中。该部分包含指向商户后台的链接。仅支持 EUR 付款。
Test mode：新付款使用 Paytrail 公共测试账户（Merchant ID 375917），而不是您自己的凭据。不会扣除真实款项，也无需密钥。顾客会在付款方式下方看到 Test mode: no real payment will be made.。测试账户的 Secret key 是公开的，因此任何人都可以模拟测试模式下的付款。切勿在正式店铺中保持测试模式开启。默认：off。
Merchant ID：您的 Paytrail Merchant ID（仅限数字）。在测试模式关闭时使用。
Secret key：您的 Paytrail Secret key。在测试模式关闭时使用。已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it.。只有在需要更改时才输入新值。
Clear saved secret key：勾选 Secret key 并点击 Save，即可删除已保存的密钥。字段为空时保留已保存的值。
回调和退款始终使用付款时所用模式的凭据，因此在测试与正式模式之间切换不会影响旧订单。
订单
Callback URL：显示 Paytrail 以服务器到服务器方式确认每笔付款的 URL。启用友好 URL 时，格式如 https://your-shop/module/wcp_paytrail_gateway/callback。它会随每笔付款发送，因此无需在 Paytrail 后台进行任何配置，但店铺必须可从互联网访问。
Order status after payment：已付款订单的状态。
待处理付款会保留在 Awaiting Paytrail payment 中。金额不符及其他问题总是进入 Paytrail payment on hold。
高级
Debug log：将 API 请求和回调记录到模块文件夹中的 logs/ptg_debug.log.php。该文件无法通过网页打开。不记录个人数据和密钥。错误和警告始终会被记录。默认：off。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载模块会删除设置和日志。停用模块从不删除任何内容。订单的 Paytrail 交易数据始终保留，因为旧订单的退款需要这些数据。默认：off。
结账
在付款步骤，顾客选择付款方式（默认为 Paytrail）并确认。模块会以欧元为单位，按购物车总额创建 Paytrail 付款，并随之发送订单项目：扣除购物车规则后的商品、运费和礼品包装，每项均附带精确到小数点后一位的增值税率。项目金额之和始终等于付款金额；舍入差额会计入某一项目，或作为 Rounding 项目发送。只有信息完整时才会发送账单和配送地址，过长的值会按 Paytrail 的限制截短。付款页面语言为芬兰语、瑞典语或英语，跟随购物车语言。此时尚未创建订单。
顾客被引导至 Paytrail 付款页面，选择为您的 Paytrail 账户启用的付款方式并付款。随后 Paytrail 会对付款进行两次确认：将顾客带回您的店铺，并以服务器到服务器的方式调用回调 URL。两者都只有在使用该付款尝试的凭据生成的签名有效，且该尝试是为此购物车创建时才会被接受。已付金额会与购物车总额进行比较。只有 Paytrail 以这种方式确认后，订单才会被标记为已付款。模块处理以下 Paytrail 状态：
付款成功后，顾客会看到标准订单确认页面，并显示 Your Paytrail payment has been received.。对于待处理付款，页面会显示 Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again.。如果回调恰好在同一时刻正在记录付款，Payment confirmation 页面会请顾客不要重复付款，并提供 Check again 按钮。
付款被取消或失败后，顾客会返回结账页面，并显示 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.。购物车会被保留。无法验证的返回会显示 Payment verification failed.，且不会更改任何内容。
如果 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 限制时，显示 This order total cannot be paid with Paytrail. Please choose another payment method.
Paytrail 付款无法通过 API 取消。购物车的每次新尝试都是一笔新的 Paytrail 付款。如果顾客还支付了一个仍然开启的旧付款页面，第二笔付款会在订单中被报告为需要退款的重复付款。
即使店铺处于维护模式，回调仍然有效，并且不受店铺国家限制的影响。
顾客在 Paytrail 页面而非您的结账页面上选择付款方式。模块不支持银行卡令牌化或保存银行卡、订阅、店中店、手动账单激活和结算报告。
订单与退款
订单状态
尚无订单：顾客已被引导至 Paytrail 但尚未付款，或 Paytrail 尚未确认付款。此时只存在购物车。
Payment accepted or Delivered：付款已确认。状态遵循 Order status after payment。付款会记录 Paytrail 交易 ID，备注中会显示交易、Paytrail 上使用的付款方式以及金额。
Awaiting Paytrail payment：付款在服务商处待处理（发票或延期付款）。Paytrail 确认付款后，订单转为已付款状态；若付款失败，则转为 Payment error。
Paytrail payment on hold：已付金额与订单总额不符（会记录实际付款金额），付款是在订单取消后到达的，或者店铺处于正式模式时收到了测试付款（无真实款项，也不会记录任何内容）。备注会说明原因。请检查订单，然后处理订单或退还付款。
Payment error：待处理付款失败或被取消。
Refunded：付款已通过模块全额退款。
重复或并发的回调绝不会创建第二个订单或重复备注。如果对已付款购物车的第二次尝试被付款，订单不会改变；Duplicate payment 备注会要求您在 Paytrail 商户后台进行退款。
Paytrail 付款区块
订单页面会显示 Paytrail payment 区块，包括交易 ID、模式（测试付款显示 TEST mode 标记）、付款方式、Paytrail 状态、已付及已退金额、退款表单、退款记录、购物车的付款尝试，以及订单的 Paytrail notes。
退款
在 Paytrail payment 区块中输入金额（会自动填入尚未退还的金额），可选填写订单备注中的退款原因，然后点击 Refund via Paytrail。确认提问 Refund this amount through Paytrail? This cannot be undone.。支持全额和部分退款，仅按金额计算。您需要编辑订单的权限；无需访问模块页面。您最多可以退还 Paytrail 实际收取的金额，因此金额不符之后，上限是顾客实际支付的金额，而非订单总额。退款使用付款时所用模式的凭据，因此对于正式付款，必须已设置正式凭据。Paytrail 确认付款后，退款即可使用。
如果付款方式不支持直接退款，模块会自动发起电子邮件退款：Paytrail 会向顾客发送邮件，请其填写银行账户。这需要订单中有顾客的电子邮件。备注会注明发起的是哪种退款。
退款可以立即完成，也可以稍后处理。Paytrail 之后的确认会以备注形式添加。如果 Paytrail 未能完成退款，备注会说明款项未退还给顾客，此时该退款不再计为已退款；请通过其他方式退款给顾客。如果 Paytrail 立即拒绝退款，区块会显示错误，且不会记录任何退款。全额退款会将订单设为 Refunded。部分退款不会改变状态。
模块不会创建退款单（credit slip）。订单页面上标准的 PrestaShop 退款按钮不会通过 Paytrail 退回款项。在 Paytrail 商户后台进行的退款不会同步回 PrestaShop。
许可证密钥
本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。模块的许可证区块 License — VibeFox Paytrail Gateway 位于 Modules > Module Manager > VibeFox Paytrail Gateway > Configure 页面的最上方，位于设置之上。在 License key 中输入密钥并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: presta-payment-paytrail 这一行，以及 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 账户中释放该名额。
没有有效密钥时，结账页面不会向顾客显示 Paytrail。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已开始的付款仍会通过回调和顾客返回被确认，退款也可正常进行。
许可证到期后，模块仍会继续工作，但更新和支持需要续费。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Paytrail：请检查许可证是否有效，Enable/Disable 是否开启，并且 Test mode 已开启，或者 Merchant ID 和 Secret key 已填写（而非公共测试账户 375917）。检查购物车货币是否为 EUR。在 Payment > Preferences 中，检查模块是否允许用于购物车货币、顾客所在国家和顾客群组。设置页面会对缺少凭据和店铺货币错误发出警告。
付款已完成，但未创建订单：回调无法到达您的店铺，且顾客也没有返回店铺。订单 部分中显示的 Callback URL 必须可从互联网访问（前面不能有基本身份验证或防火墙阻挡）。
回调或返回提示 Payment verification failed.：签名无效，或付款不属于该购物车的付款尝试。不会更改任何内容。请检查 Secret key 是否正确，并且属于该 Merchant ID。
回调返回 Temporarily unavailable：订单正被另一请求同时确认，或订单无法创建（例如模块已停用）。Paytrail 会再次调用。请查看 Log 字段了解原因。
顾客在选择 Paytrail 时看到错误：请查看模块页面上的 Log 字段。例如，Paytrail API error (401) 表示凭据错误。如需更多详情，请开启 Debug log。
Merchant ID 未保存：它必须仅包含数字。请从 Paytrail 商户后台重新复制。
订单为 Paytrail payment on hold：请阅读 Paytrail payment 区块中的备注。原因可能是已付金额不同、取消后付款，或正式模式下的测试付款。
退款失败：请阅读提示信息。This order has no confirmed Paytrail payment. Refund it manually. 表示没有可退款的已确认 Paytrail 付款。The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. 表示该付款是在正式模式下完成的，但未设置正式凭据。Invalid refund amount: at most … 表示金额超过了剩余可退金额。如果付款方式只支持电子邮件退款，订单需要顾客的电子邮件。
开发者钩子：actionWcpPaytrailPaymentRequest 钩子会在付款请求签名并发送之前对其进行修改。
卸载
进入 Modules > Module Manager，打开 VibeFox Paytrail Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果已开启 Delete data on uninstall，设置和日志会被删除。如果关闭，所有设置都会保留，以便日后重新安装。Paytrail 交易和退款，以及订单状态 Awaiting Paytrail payment 和 Paytrail payment on hold 始终会保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。
Paytrail 是其各自所有者的商标。本模块与 Paytrail 无关联，也未获得 Paytrail 的认可。