VibeFox Paytrail for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：EUR。Paytrail 仅接受欧元。对于其他货币的订单，结账时会隐藏该付款方式。金额以分为单位发送。

店铺的互联网访问：Paytrail 通过服务器对服务器的回调（callback）确认每笔付款，因此店铺应可从互联网访问。没有回调时，顾客从 Paytrail 返回后，订单仍会被确认。

Paytrail 账户：您需要商户 ID（merchant ID）和密钥，它们显示在 Paytrail Merchant Panel 中（账户或集成详情）。测试时无需账户：测试模式使用 Paytrail 的公共测试账户。付款方式本身需要在您的 Paytrail 账户中启用。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包括 README.txt、OpenCart 3 安装包 wcp_paytrail_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_paytrail_gateway.ocmod.zip。只安装与您 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

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

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

4. 若要先试用扩展，请开启 Test mode。进行真实付款时，请关闭它并填入您的 Merchant ID 和 Secret key。无需在 Paytrail 中配置任何回调 URL。

5. 开启 Enable/Disable，然后点击 Save。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_paytrail_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中读取扩展代码，重命名后的安装包无法使用。

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

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

4. 按照 OpenCart 3 的第 3–5 步输入许可证密钥和 Paytrail 设置。设置页面及其字段在两个版本中相同。仅回调 URL 不同（参见「订单」）。

新安装时，付款方式默认关闭，测试模式默认关闭。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Paytrail Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。开启测试模式时，设置上方会显示测试模式已激活。付款使用 Paytrail 的公共测试账户，不会扣除真实资金。 在正式模式下，如果缺少商户 ID 或密钥，或商户 ID 为公共测试账户 375917，页面会发出警告；在这些情况下，结账时不会显示 Paytrail。如果店铺默认货币不是 EUR，页面也会发出警告：此时只有顾客使用 EUR 付款时才会显示 Paytrail。如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能为空，也不能超过 128 个字符；Sort Order 必须是整数（允许负数）；Total 必须是大于或等于 0 的数字；地区（geo zone）和订单状态必须存在；否则不会保存任何内容。包含数字以外字符的商户 ID 不会被保存，并会显示错误Paytrail 商户 ID 只能包含数字。已保留原值。，而其他设置仍会保存。

Paytrail

本节开头有一段关于 Paytrail 付款页面的简短说明，以及订单仅在 Paytrail 确认付款后才获得状态的规则。

Enable/Disable：Enable Paytrail 用于开启或关闭该付款方式。默认：关闭。

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

Description：在 Confirm Order 步骤中、确认按钮上方、Paytrail 图标旁边显示给顾客的文字。默认：Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

Sort Order：Paytrail 在结账付款方式中的排列位置。可留空或输入整数。

Geo Zone：仅向所选地区（geo zone）内的付款地址提供 Paytrail。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。

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

API 凭据

您的商户 ID 和密钥显示在 Paytrail Merchant Panel 中（账户或集成详情）。本节包含指向 Paytrail 的链接。仅支持 EUR 付款。

Test mode：新付款使用 Paytrail 的公共测试账户（商户 ID 375917），而不是您自己的凭据。不会扣除真实资金，也无需密钥。顾客在 Confirm Order 步骤会看到测试模式：不会进行真实付款。 测试账户的密钥是公开的，因此任何人都可能模拟测试模式下的付款。切勿在正式店铺中保持测试模式开启。默认：关闭。

Merchant ID：您的 Paytrail 商户 ID（仅限数字）。在测试模式关闭时使用。与密钥不同，保存后它会显示在页面上。

Secret key：您的 Paytrail 密钥。在测试模式关闭时使用。已保存的密钥不会再次显示。该字段保持为空，并显示已保存——留空即保留原值。 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear saved secret key，然后点击 Save。

回调和退款始终使用付款时所在模式的凭据，因此在测试和正式之间切换不会影响旧订单。

订单

OpenCart 在 Confirm Order 步骤创建订单时不设置状态（缺失订单，即 missing order）。只有在 Paytrail 确认付款后，订单才会获得状态。下方每个状态字段都列出您的 OpenCart 订单状态。

Callback URL：显示 Paytrail 以服务器对服务器方式确认每笔付款所用的 URL。在 OpenCart 3 中格式为 https://your-store/index.php?route=extension/payment/wcp_paytrail_gateway/callback，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_paytrail_gateway/payment/wcp_paytrail_gateway.callback。它会随每笔付款一起发送，因此无需在 Paytrail 后台进行配置，但店铺必须可从互联网访问。

Order status after payment：已付款订单的状态。默认：Processing。如果希望每笔已付款订单都立即完成，请选择 Complete。

Awaiting payment status：Paytrail 将付款报告为待处理或延迟（发票或分期付款正在等待服务商批准）。当 Paytrail 确认或拒绝付款时，订单会自动更新。默认：Pending。

Payment on hold status：付款需要您关注（参见「订单状态」）。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Payment failed status：等待中的 Paytrail 付款失败时设置。默认：Failed。

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

高级

Debug log：将 API 请求和回调记录到 OpenCart 日志文件夹（storage/logs）中的 ptg_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会移动为 ptg_debug.old.log.php。个人数据和密钥不会被记录。错误和警告始终会被记录。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展会删除网关设置和日志。关闭扩展绝不会删除任何内容。订单的 Paytrail 交易数据始终保留，因为旧订单的退款需要这些数据。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。商户 ID 和密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的商户 ID 和密钥会保留。

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 Paytrail）。在 Confirm Order 步骤，顾客会看到 Paytrail 图标和您的说明。OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过付款方式区块的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。当顾客点击 Confirm Order 时，扩展会以欧元为订单总额创建一笔 Paytrail 付款，并以订单号作为参考，同时随付款发送订单明细：商品（包括其选项和税费）、已购买的礼品卡、运费和其他费用。优惠券、店铺余额、奖励积分和已使用的礼品卡会分摊到各明细行。明细行之和始终等于付款金额；舍入差额会计入某一行，或作为一行 Rounding 发送。顾客的联系方式会被发送；账单和配送地址仅在信息完整时才会发送。付款页面语言为芬兰语、瑞典语或英语，视顾客的语言而定。

顾客会被带到 Paytrail 付款页面，选择您 Paytrail 账户中已启用的付款方式并付款。Paytrail 随后会确认付款两次：将顾客带回您的店铺，并以服务器对服务器的方式调用回调 URL。只有使用该次付款尝试的凭据生成的有效签名，并且该尝试是为此订单创建时，两次确认才会被接受。付款金额会与订单总额进行比较。只有当 Paytrail 以这种方式确认付款后，订单才会被标记为已付款，并以标准的 OpenCart 方式获得状态，发送常规订单邮件并更新库存。扩展会处理以下 Paytrail 状态：

付款成功后，顾客会看到 OpenCart 订单成功页面，并显示您的 Paytrail 付款已收到。 对于待处理的付款，页面会显示您的 Paytrail 付款正在等待付款服务商确认。订单将自动更新，请勿重复付款。 如果回调恰好在同一时刻记录付款，Payment confirmation 页面会请顾客不要重复付款，并提供 Check again 选项。

付款取消或失败后，顾客会返回结账页面，并显示Paytrail 付款已取消或失败。您可以重试，或选择其他付款方式。 如果付款尚未完成，消息为Paytrail 付款尚未完成。您可以重试，或选择其他付款方式。 购物车会被保留。在 OpenCart 4 中，这些消息显示在结账页面上方。无法验证的返回会显示 Payment Error 页面，内容为 Payment verification failed.，并且不会更改任何内容。

如果 Paytrail 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短消息，例如无法连接到 Paytrail。请稍后重试。、Paytrail 暂时不可用。请选择其他付款方式。（凭据错误），或Paytrail 无法发起付款。请检查您的账单信息后重试，或选择其他付款方式。 技术原因会写入日志。订单总额超出 Paytrail 限额时，会显示此订单金额无法通过 Paytrail 支付。请选择其他付款方式。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则更新结账中的订单（新的尝试会支付同一订单）。如果购物车已通过另一个订单付款，顾客会直接进入成功页面，不会发起新的付款。Paytrail 付款无法通过 API 取消，因此较早的付款页面仍可付款。如果顾客也支付了该页面，第二笔付款会在已付款订单上记录为需要退款的重复付款，另一个订单则保持无状态。购物车的任何变动（包括新的数量）都视为需要单独付款的新购物车。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在此期间未付款即被关闭（例如您取消了它），顾客会被送回结账页面，并显示消息 您之前的订单已取消或已退款。请重新确认订单，以新订单付款。 如果其等待中的付款失败，消息为 Paytrail 付款已取消或失败。您可以重试，或选择其他付款方式。 下一次 Confirm Order 将为新订单付款。如果该订单此前已为较早的购物车付款，而购物车之后发生了变化，顾客会被带回结账页面，下一次 Confirm Order 将为当前购物车的新订单付款。已关闭的订单绝不会显示为已付款。

即使店铺处于维护模式，回调也能正常工作，因为 OpenCart 会放行付款扩展的请求（在 OpenCart 4 中，扩展会为此添加自己的启动动作，该动作同时允许顾客从 Paytrail 返回）。

顾客在 Paytrail 页面选择付款方式，而不是在您的结账页面。该扩展不支持银行卡令牌化或保存银行卡、订阅、shop-in-shop、手动发票激活或结算报告。

订单与退款

订单状态

无状态（缺失订单）：顾客已被带到 Paytrail，但尚未付款、付款失败，或 Paytrail 尚未确认付款。在 Sales > Orders 中，这类订单只有在 Order Status 筛选条件设为 Missing Orders 时才会显示。

Order status after payment（默认 Processing）：付款已确认。备注会显示 Paytrail 交易、在 Paytrail 中使用的付款方式和金额；测试付款会附带 TEST mode — no real money.

Awaiting payment status（默认 Pending）：付款在服务商处待处理（发票或延迟付款）。Paytrail 确认付款时，订单转为已付款状态；付款失败时，则转为失败状态。

Payment on hold status（默认 Pending）：实付金额与订单总额不符（会记录实际付款金额），付款是在订单已被设为其他状态（例如已取消）之后到达的，或者扩展处于正式模式时收到了测试付款（没有真实资金，也无需退款）。备注会说明原因。请检查订单，然后处理订单或退还付款。

Payment failed status（默认 Failed）：等待中的 Paytrail 付款失败或已取消。

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

重复或并发的回调只会被应用一次，不会产生重复备注。已付款、已退款或已完成的订单，不会因后续回调而重新打开。如果已付款订单或购物车的第二次尝试被付款，订单不会被修改；Duplicate payment 备注会提示您在 Paytrail Merchant Panel 中退还该笔付款。

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

VibeFox Paytrail Gateway 选项卡

在 Sales > Orders 中打开一个通过 Paytrail 付款的订单。在订单页面底部，与 History 和 Additional 并列，VibeFox Paytrail Gateway 选项卡会列出该订单的付款尝试（日期、Paytrail 交易和标记，测试付款带有 Test 标签、金额、付款方式、Paytrail 状态和结果）、Paid / refunded 金额、退款表单、退款历史以及订单的 Paytrail notes。该选项卡对有权访问扩展的用户可见。

退款

在 VibeFox Paytrail Gateway 选项卡中，输入 Amount（会自动填入尚未退款的金额），可选填写订单备注中的原因，然后点击 Refund via Paytrail。确认提示通过 Paytrail 退还此金额？此操作无法撤销。支持全额和部分退款，仅按金额计。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。您最多只能退还 Paytrail 实际扣取的金额，因此在金额不一致的情况下，上限是顾客实际支付的金额，而不是订单总额。退款使用付款时所在模式的凭据，因此对于正式付款，必须设置正式凭据。Paytrail 确认付款后，退款功能即可使用。

如果付款方式不支持直接退款，扩展会自动发起电子邮件退款：Paytrail 会向顾客发送邮件，请其输入银行账户。这需要订单中有顾客的电子邮件。备注会说明已发起的退款类型。

退款可以立即完成，也可以稍后处理。Paytrail 之后的确认会以备注形式添加。如果 Paytrail 无法完成退款，备注会说明款项并未退还给顾客，该退款不再计为已退款；请通过其他方式退还顾客。如果 Paytrail 立即拒绝退款，选项卡会显示错误，并且不会记录任何退款。全额退款会将订单设为 Refunded status，不会通知顾客，也不会把商品退回库存，与手动更改状态一样。部分退款不会改变状态。

在 Sales > Returns 中的商品退货不会通过 Paytrail 退款。在 Paytrail Merchant Panel 中进行的退款不会同步回 OpenCart。

许可证密钥

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

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

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

故障排除

结账时不显示 Paytrail：请检查许可证是否有效，Enable/Disable 是否开启，并且 Test mode 已开启，或 Merchant ID 和 Secret key 已填写（且不是公共测试账户 375917）。请检查顾客是否使用 EUR 付款、付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。如果缺少凭据或店铺货币不是 EUR，设置页面会显示警告。

付款已完成，但订单仍无状态：回调无法到达您的店铺，而且顾客也没有返回店铺。Orders 部分显示的 Callback URL 必须可从互联网访问（不能有基础身份验证或防火墙阻挡）。

回调或返回提示 Payment verification failed.：签名无效，或该付款不属于此订单的任何付款尝试。不会做任何更改。请检查 Secret key 是否正确，以及是否属于该 Merchant ID。

回调返回 Temporarily unavailable：订单在同一时刻正被另一请求确认，或无法设置订单状态。Paytrail 会再次调用。请查看 Log 字段了解原因。

顾客在 Confirm Order 之后看到错误：请查看扩展页面上的 Log 字段。例如，Paytrail API error (401) 表示凭据错误。开启 Debug log 可获得更多详情。This payment method is not available. Please reload the checkout page. 表示付款方式期间已被关闭，或结账页面已与订单不一致。

商户 ID 无法保存：它只能包含数字。请从 Paytrail Merchant Panel 重新复制。

订单处于 on hold 状态：请阅读 VibeFox Paytrail Gateway 选项卡中的备注。原因可能是付款金额不同、状态更改后收到付款，或正式模式下收到测试付款。

退款失败：请阅读消息内容。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 … 表示金额超过了剩余可退金额。This payment method supports only e-mail refunds, but the order has no billing e-mail. 表示订单需要顾客的电子邮件。

对开发者：在付款请求被签名并发送之前，扩展会触发 OpenCart 事件 ptg_payment_request，并附带请求和订单。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Paytrail Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态（重新安装时会恢复为默认值）。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中同时删除其事件以及在维护模式下允许回调和顾客返回的启动动作）。如果 Delete data on uninstall 已开启，则其余网关设置（标题、说明、测试模式、商户 ID、密钥、日志记录）和日志会被删除。如果已关闭，这些设置会保留，供以后重新安装时使用。Paytrail 交易和退款总会被保留，因此之前付款的订单在重新安装后仍可退款。已有订单会保留其付款备注。

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

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