VibeFox Tpay for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。验证通知的 JWS 签名需要 OpenSSL 扩展，并且需要能够对外访问 secure.tpay.com 的 HTTPS。

货币：仅支持波兰兹罗提（PLN）。Tpay 以 PLN 结算，其 Open API 没有货币字段。如果您的店铺没有 PLN，请在 System > Localisation > Currencies 中添加：只有顾客以 PLN 付款时才会显示 Tpay。

店铺的互联网访问：Tpay 会将付款通知发送到您的店铺，因此通知地址必须可以从互联网访问（不能被防火墙或 HTTP 身份验证阻止）。

Tpay 账户：您需要 Tpay 商户后台中的以下信息：Merchant ID（您的 Tpay 账户 ID）、Open API 密钥 Client ID 和 Client secret（Integration，API），以及安全码（Settings，Notifications）。沙盒密钥来自独立的 Tpay 沙盒账户。

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

安装

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

OpenCart 3

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

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

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

4. 输入沙盒密钥和正式密钥（参见配置）。除安全码外，无需在 Tpay 后台进行任何设置：每笔交易都会发送通知地址。

5. 开启 Enable/Disable 并点击 Save。在沙盒模式下测试一笔付款，然后关闭 Sandbox mode，即可接受真实付款。

OpenCart 4

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

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

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

4. 请按照 OpenCart 3 步骤 3 至 5 输入许可证密钥、Tpay 密钥和通知设置。两个版本的设置页面及其字段完全相同，只有通知 URL 不同（参见付款通知）。

全新安装时，付款方式默认关闭，沙盒模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Tpay Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在沙盒模式开启期间，设置上方的页面会显示 Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. 当前模式的密钥不完整时（此时结账时不显示 Tpay）、店铺默认货币不是 PLN 时（只有顾客以 PLN 付款时才显示 Tpay），以及启用 JWS 检查但缺少 OpenSSL PHP 扩展时（此时付款将无法被确认），页面都会发出警告。如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不能为空，且不能超过 128 个字符；Sort Order 必须是整数（允许负值）；Total 必须是大于或等于 0 的数字；订单状态必须存在；否则不会保存任何内容。缺失的密钥不会阻止保存。与 Merchant ID 或 Client ID 一起粘贴的空格会被去除，私密值的首尾空格也会被修剪。

Tpay

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

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

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode：使用 Tpay 沙盒（测试付款，不会扣除真实款项），搭配沙盒密钥和 openapi.sandbox.tpay.com。关闭它即可使用正式密钥接受真实付款。退款始终会退回到订单付款时所在的环境。默认：开启。

Sort Order：Tpay 在结账付款方式中的位置。留空或输入整数（允许负值）。

Geo Zone：仅对所选地理区域内的付款地址提供 Tpay。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

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

正式密钥

在哪里找到：在 Tpay 商户后台（本节链接到该后台）的 Integration，API 下（Open API 密钥：Client ID 和 Secret）；Merchant ID 是您的 Tpay 账户 ID；安全码位于 Settings，Notifications 中。

Merchant ID：您的 Tpay 账户 ID（数字）。Tpay 会在每条通知中发送该值。

Client ID：Open API 的 Client ID。

Client secret：Open API 的 Client secret。

Security code：用于验证 Tpay 通知的 MD5 校验和。

沙盒密钥

沙盒是一个独立的 Tpay 测试账户，拥有自己的密钥（本节链接到 Tpay API 文档）。仅在 Sandbox mode 开启时使用。

Sandbox Merchant ID：沙盒账户的 Merchant ID。

Sandbox Client ID：沙盒账户的 Open API Client ID。

Sandbox Client secret：沙盒账户的 Open API Client secret。

Sandbox Security code：沙盒账户的通知安全码。

已保存的私密值（两个环境的 Client secret 和 Security code）不会再次显示。该字段保持为空，并显示 Saved - leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的私密值，请勾选字段下方的 Clear the saved value，然后点击 Save。

付款通知

Notification URL：Tpay 会将付款确认发送到此处显示的地址。在 OpenCart 3 中，该地址形如 https://your-store/index.php?route=extension/payment/wcp_tpay_payment/notify，在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_tpay_payment/payment/wcp_tpay_payment.notify，由您的 OpenCart 安装的店铺前台地址生成。该地址会随每笔交易自动发送；除安全码外，无需在 Tpay 后台进行任何设置。只有收到校验和与签名均有效、且金额匹配的通知后（或顾客返回时金额匹配的状态查询后），订单才会获得状态。Tpay 会重复发送通知，直到您的店铺接受为止。维护模式不会阻止该地址（在 OpenCart 4 中，扩展会为通知和顾客返回添加一个启动操作）。

JWS signature：还会使用 Tpay 证书验证通知的 X-JWS-Signature（推荐）。需要 PHP 的 OpenSSL 扩展以及对 secure.tpay.com 的 HTTPS 访问。证书会缓存一天。MD5 校验和始终会被验证。默认：开启。

订单

OpenCart 在 Confirm Order 步骤创建订单，此时不带状态（即缺失订单）。只有在 Tpay 确认付款（通过通知或状态查询）后，订单才会获得状态。下方每个字段都列出您的 OpenCart 订单状态。

Paid Order Status：付款确认后的状态。默认：处理中。

On Hold (Review) Status：付款需要您审核（参见订单状态）。默认：待处理，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Order Status：扩展从不设置此状态。对处于此状态的订单发起的付款会将订单转入审核，而不会悄悄地重新打开它。默认：已取消。

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

高级

Debug log：记录付款事件：仅记录技术事件（不含密钥和顾客数据），写入 OpenCart 日志文件夹（storage/logs）中的 wc_tp_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会转存为旧副本。默认：关闭。关闭时不会写入任何内容，包括错误；因此在查找问题原因之前，请先开启它。

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

Delete data on uninstall：开启后，卸载扩展会删除网关设置和日志。订单及其 Tpay 付款数据始终保留。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。Client secret 和 Security code 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 Client secret 和 Security code 会保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Tpay）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to the secure Tpay page to complete the payment. 在沙盒模式下，还会显示 Sandbox mode - no real money is charged. OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

顾客点击 Confirm Order 后，扩展会以 PLN 为订单总额创建一笔 Tpay 交易，描述为 Order # 加订单号，并传递顾客的姓名、电子邮件、付款地址和电话号码，然后将顾客转到 Tpay 付款页面。该页面会根据订单语言显示为波兰语、英语或乌克兰语（其他语言显示英语）。在那里，顾客可以选择 BLIK、银行转账、银行卡，或您 Tpay 账户中已启用的其他方式，然后完成付款。

只有在 Tpay 确认后，订单才会被标记为已付款。Tpay 会向您的店铺发送通知；扩展会使用付款发起环境的密钥，用安全码和 Merchant ID（以及启用时的 JWS 签名）验证 MD5 校验和，然后检查金额：金额必须等于此次付款尝试所请求的金额以及订单总额，且实付金额不得低于此金额。没有有效校验和或签名的通知会被拒绝。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。

付款后，顾客返回您的店铺。仅仅返回不会将任何内容标记为已付款。如果通知尚未到达，扩展会向 Tpay API 查询交易状态（最多每 10 秒一次），并执行相同的检查。付款确认后，顾客会看到 OpenCart 的订单成功页面。在确认之前，Payment confirmation 页面会显示 Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again:，并带有 Refresh 按钮和一个返回结账页面的 Pay again 按钮。通知一到达就会设置订单状态。如果订单转入审核，成功页面还会显示 Your payment is being verified. We will contact you as soon as it is confirmed.

如果 Tpay 报告付款失败，顾客会返回结账页面，并看到 Tpay reports that the payment did not go through. Please try again or choose another payment method. 如果付款在 Tpay 页面上失败，Tpay 会将顾客送回结账页面。两种情况下购物车都会保留。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单。OpenCart 4 则为结账保留一个订单并对其进行更新，因此 Pay again 会为同一订单启动一次新的尝试。每次付款尝试都有各自的参考号。顾客再次付款时，该订单和同一购物车中其他订单之前未付款的 Tpay 交易会在 Tpay 处被取消；但通过较早链接已经完成的付款仍会被接受。如果同一购物车的另一个订单已经付款，顾客会进入成功页面，而不会发起新的付款。

在 OpenCart 4 中，如果结账所用的订单在此期间被店铺关闭，或订单已付款但之后购物车发生了变化（包括新的数量），顾客会被带回结账页面，并看到 Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order. 对于店铺在付款前已取消的订单，提示为 Order #… was cancelled by the store before the payment was completed. No Tpay payment was received for it. Please place a new order or contact us. 下一次 Confirm Order 将为一个新订单付款。在 OpenCart 4 中，这些提示、付款失败的提示以及 We could not match this payment to an order. If you were charged, please contact us. 都会显示在结账页面上方。

如果 Tpay 无法发起付款，顾客会停留在 Confirm Order 步骤，并看到 The Tpay payment could not be started. Please try again or choose another payment method.，原因会记录在日志中（前提是开启了 Debug log）。其他消息：Tpay accepts payments in Polish złoty (PLN) only. Please choose another payment method. 和 The order total must be greater than zero.

该扩展仅以 PLN 运行。店铺中没有银行或 BLIK 代码选择（顾客在 Tpay 页面上选择），不支持保存银行卡、订阅，店铺中也没有 Apple Pay 或 Google Pay 按钮，也没有分期付款计算器。

订单与退款

订单状态

无状态（缺失订单）：顾客已被转到 Tpay 但尚未付款，或 Tpay 尚未确认付款。付款失败也会使订单保持无状态。在 Sales > Orders 中，只有将 Order Status 筛选器设置为 Missing Orders 时才会显示此类订单。

Paid Order Status (default Processing)：Tpay 已确认付款。备注会显示 Tpay 交易标题（TR-...）、已付金额、确认是通过通知还是状态查询完成的、环境，以及任何超额付款。

On Hold (Review) Status (default Pending)：已收到付款，但订单货币不是 PLN，付款金额与所请求的金额或订单总额不一致（例如付款开始后订单被修改），仅支付了部分金额，或付款是针对处于 Cancelled Order Status 的订单收到的。备注会说明原因。请在 Tpay 后台检查付款，然后完成或退款该订单。如果顾客之后通过另一次尝试支付了正确金额，订单会转入 Paid Order Status。

Refunded Status (default Refunded)：付款已通过扩展全额退款。

如果 Tpay 报告某个已付款或已退款订单又有另一笔付款，订单不会被修改；备注会提醒您，如有需要，请在 Tpay 后台退还多出的付款。属于同一购物车中另一个已付款订单的付款，会使该订单保持无状态，并记录在已付款订单上。对于已有状态的订单发生的失败付款、拒付（chargeback）和未知的 Tpay 状态，只会添加备注。

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

VibeFox Tpay Payment 标签页

在 Sales > Orders 中打开一个通过 Tpay 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox Tpay Payment 标签页会显示 Tpay transaction 标题和 Transaction ID、付款参考号（CRC）、Environment（沙盒付款显示 Sandbox 标签）、付款的 Status 以及确认方式、已付金额、Order total / refunded、与订单总额不同时显示的 Refundable (paid through Tpay)、退款表单、退款记录、订单的 Payment attempts（已取消的链接会标注 link cancelled）以及 Payment notes。该标签页显示给有权访问该扩展的用户。

退款

在标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional, kept in the note)，然后点击 Refund via Tpay。确认提示 Refund this amount through Tpay? This cannot be undone.。对于通过 Tpay 收到付款的订单（包括审核中的订单），支持全额和部分退款。您需要修改扩展的权限（在 System > Users > User Groups 中设置）。您最多可以退还付款交易所收取的金额，且不超过订单总额。退款会发送到订单付款时所在的环境（沙盒或正式），因此该环境的密钥必须已设置。只有 Tpay 确认后，退款才算完成；被 Tpay 拒绝或未确认的退款会显示为错误，且不会被记录。成功的退款会连同您输入的原因一起添加到退款记录和备注中（该原因不会发送给 Tpay）。全额退款会将订单设置为 Refunded Status，且不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会改变状态。

Sales > Returns 中的商品退货不会通过 Tpay 退回款项。在 Tpay 商户后台进行的退款不会自动添加到 OpenCart 中。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Tpay Payment 位于 Extensions > Extensions > Payments > VibeFox Tpay Payment > Edit 的最上方，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期至何时以及您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店移除密钥。其下方有 Product: opencart-payment-tpay 一行，以及打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包含英文和俄文）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。在店铺地址更改之后，或在您的账户中释放了一个域名名额之后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最近一次已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

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

许可证到期后，扩展仍会继续工作，但更新和支持需要续期。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会移除许可证密钥和许可证状态。

故障排除

Tpay 未在结账时显示：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的四个密钥（Merchant ID、Client ID、Client secret、Security code）是否都已填写。检查顾客是否以 PLN 付款，付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。设置页面会对缺失的密钥和非 PLN 的店铺货币显示警告。

付款已成功，但订单仍无状态：Tpay 无法送达通知，或通知被拒绝。请开启 Debug log，并查看扩展页面上的 Log 字段。常见原因包括：付款环境对应的安全码或 Merchant ID 错误、通知地址被阻止（防火墙、HTTP 身份验证），或服务器缺少 OpenSSL 或无法对外进行 JWS 检查所需的 HTTPS 访问。顾客付款后返回店铺时，订单也会获得状态。

Notification answered FALSE - invalid checksum：设置中的 Merchant ID 或安全码与该付款所用的 Tpay 账户（沙盒或正式）不匹配。

Notification answered FALSE - invalid JWS signature：无法验证签名，例如缺少 OpenSSL，或无法下载 Tpay 证书。请修复服务器，或在必要时关闭 JWS signature；MD5 校验和仍会被检查。

Notification answered FALSE - busy, retry later 或 FALSE - order could not be updated：购物车在同一时刻正被另一个请求处理，或无法设置订单状态。Tpay 会自动重复发送通知。请开启 Debug log 以查看原因。

通知 URL 显示 FALSE - POST only in the browser：这是正常现象。该 URL 只接受来自 Tpay 的通知。

订单处于审核状态：请阅读 VibeFox Tpay Payment 标签页中的备注（参见订单状态），在 Tpay 后台检查付款，然后完成订单或退还付款。

顾客看到 The Tpay payment could not be started：当前模式的密钥有误，或 Tpay 拒绝了请求。请开启 Debug log；日志会显示 Tpay 的错误。

顾客看到 This payment method is not available：结账会话已与订单不匹配，或付款方式在此期间被关闭或失去了密钥。顾客需要重新加载结账页面。

顾客看到 We could not match this payment to an order：返回链接不属于该订单。如果顾客已被扣款，通知仍会设置订单状态；请检查 Tpay 后台。

退款失败：如果消息提示缺少密钥，请输入订单付款所在环境的密钥。如果消息提示金额过高，最多只能退还所显示的金额。如果 Tpay 未确认退款，请在重试前到 Tpay 商户后台检查该交易。如果标签页显示 Tpay transaction ID not found.，说明该订单没有可退款的已确认 Tpay 付款。

面向开发者：在创建 Tpay 交易之前，扩展会触发 OpenCart 事件 wc_tp_transaction_data，并附带交易数据、订单和环境信息。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Tpay Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件（在 OpenCart 4 中还包括其事件和启动操作），以及缓存的 Tpay 访问令牌和证书，也始终会被移除。如果 Delete data on uninstall 已开启，其他网关设置（标题、说明、沙盒模式、密钥、JWS 签名、调试日志开关）和日志也会被删除。如果关闭，这些设置会保留，供以后重新安装时使用。Tpay 交易和退款始终会保留，因此即使重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注。

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

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