VibeFox Tranzila for OpenCart — 帮助

系统要求

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

PHP: 8.0 或更高版本。

货币: ILS、USD、EUR 或 GBP。对于其他客户货币，结账时会隐藏该付款方式。

Tranzila 终端: 您需要终端名称。握手（handshake）以及从订单页面退款时需要终端密码（TranzilaPW）。部分终端在退款时还需要单独的信用密码（CreditPass）。终端名称和密码由 Tranzila 提供：请查看您的终端设置，或联系 Tranzila 支持。测试时，Tranzila 会提供一个单独的测试终端；请将其名称作为终端名称填写。

真实访客 IP: 付款通知会根据 Tranzila 服务器的 IP 地址进行校验。如果您的商店位于 Cloudflare 等代理或 CDN 之后，Web 服务器必须将真实访客 IP 传递给 PHP（REMOTE_ADDR）。

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

安装

下载文件是一个 zip 压缩包，包含适用于两个 OpenCart 版本的安装包。请解压到您的计算机上。压缩包包含 README.txt、OpenCart 3 安装包 wcp_tranzila_payment_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_tranzila_payment_gateway.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

4. 填写 Terminal name (supplier)；如果使用握手或退款，还需填写 Terminal password (TranzilaPW)。

5. 保持 Notifications 开启，并检查 Trusted IP：其中必须列出 Tranzila 发送通知的 IP 地址。请与 Tranzila 支持确认该列表。通知 URL 会随每笔付款一起发送，因此无需将其复制到任何地方。

6. 推荐：在 Tranzila 终端中启用握手，在其中允许您服务器的 IP，然后在扩展中开启 Handshake。

7. 开启 Enable/Disable，点击 Save，并使用 Tranzila 测试终端测试一笔付款。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至第 7 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。

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

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Tranzila Payment Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会在以下情况向您发出警告：终端名称为空（此时结账时会隐藏该付款方式）；通知已禁用或 Trusted IP 为空（已付款订单会因此被搁置等待人工审核）；握手已开启但未设置终端密码（无法打开付款页面）；以及商店的默认货币不受支持。如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，页面绝不会一次性拒绝全部内容。空的或超过 128 个字符的 Title、无效的终端名称、Trusted IP 中的无效条目、不是整数的数字字段，或无效的 Sort Order、Total、Geo Zone 或订单状态都不会被保存：页面会在设置上方的红色区块中显示提示信息，并且该字段会重新显示之前的值。超出允许范围的数字会以最接近的允许值保存，页面会告知您，例如 5000 超出 400–1500 的范围，已保存为 1500。其他所有字段都会正常保存。

Tranzila

Enable/Disable: Enable Tranzila Payment Gateway 用于开启或关闭该付款方式。默认值：off。

Title: 客户在结账时看到的付款方式名称，也是付款页面的标题。它还会作为付款方式名称保存在订单中，因此为必填项，最多 128 个字符。默认值：Credit Card (Tranzila)。

Description: 客户在 Confirm Order 步骤中、确认按钮上方看到的文字。默认值：Pay securely with your credit card on the Tranzila payment page。

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

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

Total: 订单在商店默认货币下需达到的结账总额，达到后才会提供 Tranzila。留空则对任何金额都提供 Tranzila。

终端

Terminal name (supplier): 您的 Tranzila 终端名称，例如 myshop。仅允许字母、数字、“-”和“_”。在填写之前，结账时不会显示该付款方式。测试时，请填写您的 Tranzila 测试终端名称。

Terminal password (TranzilaPW): 终端的 API 密码。握手以及从订单页面退款时需要。

Refund password (CreditPass): 仅当您的终端要求信用（退款）交易使用单独密码时填写。否则请留空。

已保存的密码不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密码，请勾选字段下方的 Clear saved password on save，然后点击 Save。

付款页面

Payment page version: 在 iframe 中显示的 Tranzila 页面。

Payment page language: Tranzila 页面的语言：Site language、希伯来语、英语、俄语、西班牙语、德语、法语或日语。默认值：Hebrew。Site language 在客户的商店语言属于上述语言之一时使用该语言，否则使用英语。

iFrame width (px): 300 至 1200。默认值：600。在小屏幕上，框架的宽度永远不会超过页面。

iFrame height (px): 400 至 1500。默认值：650。

Max installments: 客户可在付款页面上选择的最大分期数（tashlumim），最多 36 期。0 或 1 表示不分期。默认值：0。终端必须被允许处理分期。

Handshake: 使用握手令牌锁定金额（推荐）。在打开付款页面之前，商店会向 Tranzila 请求一个与金额绑定的一次性令牌，因此金额无法在浏览器中被修改。这需要终端密码、在 Tranzila 终端中启用握手，并允许您服务器的 IP 地址。默认值：off。

付款确认

Tranzila 通知不进行签名。只有当通知来自 Trusted IP，并且其付款页面令牌、订单、终端、金额和货币都与付款页面一致时，订单才会获得已付款状态。启用握手时，令牌也必须一致。客户从付款页面返回，绝不会将订单标记为已付款。

Notifications: 通过 Tranzila 通知（通知 URL）自动确认付款。默认值：on。关闭通知时，从成功的付款页面返回的客户会使订单进入 On hold status，您需在核对 Tranzila 终端后手动确认付款。

Notification URL: 仅供参考。在 OpenCart 3 中其格式类似：https://your-store/index.php?route=extension/payment/wcp_tranzila_payment_gateway/notify；在 OpenCart 4 中为：https://your-store/index.php?route=extension/wcp_tranzila_payment_gateway/payment/wcp_tranzila_payment_gateway.notify，根据您 OpenCart 安装的商店地址生成。该 URL 会随每笔付款发送给 Tranzila，因此您无需在 Tranzila 终端中输入它。商店处于维护模式时同样可用（在 OpenCart 4 中，扩展的一个启动操作会允许通知和客户返回通过）。

Trusted IP: 发送通知的 Tranzila 服务器的 IP 地址或 CIDR 范围，以逗号分隔。默认值：80.244.170.7。请与 Tranzila 支持确认当前列表。来自其他地址的通知会被拒绝。如果该字段为空，则无法验证通知：报告为成功的付款会使订单进入 On hold status 等待人工审核，报告为拒绝的付款则不会产生任何变化。

订单

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（缺失订单）。只有经过验证的 Tranzila 通知才会使订单获得状态。OpenCart 没有 On hold 状态，因此会使用您在此处选择的状态，并附带订单备注说明原因。以下每个字段都列出您的 OpenCart 订单状态。

Order status after payment: 付款已通过经验证的通知确认（金额、货币、终端和令牌均一致）。默认值：Processing。

On hold status: 付款需要您的审核：金额、货币或握手令牌不一致；无法验证通知（没有 Trusted IP）；或者通知已关闭，且客户从成功的付款页面返回。默认值：Pending。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

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

Cancelled order status: 扩展不会设置该状态。处于此状态的订单若之后被付款，会重新打开并附带备注，提醒您检查库存。默认值：Canceled。

Payment error status: 扩展不会设置该状态。处于此状态的订单会由之后获批的 Tranzila 付款完成支付。默认值：Failed。

高级

Debug log: 将付款页面、通知和退款事件记录到 OpenCart 日志文件夹（storage/logs；在 OpenCart 4 中为 system/storage/logs）中的 tranzila_p_debug.log.php。该文件无法通过网页打开；达到 5 MB 时，会被移动到 tranzila_p_debug.old.log.php。即使此选项关闭，警告和错误也始终会被记录。密码、令牌和客户数据绝不会被写入。默认值：off。

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

Delete data on uninstall: 开启后，卸载扩展时会删除设置和日志。Tranzila 交易和退款始终保留，因为旧订单需要它们。默认值：off。

导入 / 导出

Export: Download JSON 将设置保存为 JSON 文件。密码不会被导出。

Import: 粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的密码会被保留。

结账

在 Payment Method 步骤，客户选择付款方式（默认为 Credit Card (Tranzila)）。在 Confirm Order 步骤，客户会看到您的说明以及提示 After you confirm, you will enter your card details on the secure Tranzila payment page. The order is confirmed once Tranzila confirms the payment. OpenCart 在此步骤创建订单，此时仍没有状态。当客户点击 Confirm Order 后，会进入您商店的一个付款页面。那里会在 iframe 中打开 Tranzila 付款页面，显示订单币种的订单总额、账单信息以及简短的商品列表。页面上写着 Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". 框架下方有 Choose another payment method 链接。如果允许分期，客户会在 Tranzila 页面上选择期数。在 OpenCart 4 中，客户在付款方式区块中点击 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

每次显示付款页面都会是一次新的付款尝试，并拥有各自的令牌（以及握手令牌）。刷新页面会为同一客户会话中的订单打开新的尝试；在其他浏览器中打开的付款页面链接会将客户带回结账页面。

付款成功后，Tranzila 会将客户送回，整个窗口随之继续。只有在 Tranzila 通过通知确认付款后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规的订单邮件、更新库存。当处于搁置状态的订单之后被付款时，客户会收到有关订单新状态的邮件。如果通知已经到达，客户会看到 OpenCart 订单成功页面，并显示 Your payment with Tranzila has been received. 如果订单因审核而处于搁置状态，页面会显示 Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed. 如果通知尚未到达，Payment confirmation 页面会显示 Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again.，并带有 Check again 和 Back to checkout 按钮。

如果付款被拒绝或取消，客户会带着 The payment was not completed. You have not been charged — please try again or choose another payment method. 消息返回结账页面。当 Tranzila 返回响应代码时，会附加原因和代码，例如卡已过期。购物车会被保留，订单仍保持无状态。在 OpenCart 4 中，此消息显示在结账页面上方。OpenCart 3 在每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则会更新结账中的订单；已被其中某个订单付款的购物车不会被再次扣款。对购物车的任何更改（包括新的数量）都视为需要单独付款的新购物车。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。付款被拒绝后，客户会使用新的付款尝试再次为同一订单付款。如果该订单期间已被关闭（例如您取消了它），或者它是为之后已更改的购物车付款的，客户会被带回结账页面，并显示 This order can no longer be paid. Please confirm your order again.，下一次 Confirm Order 会支付一个新订单。

如果付款页面无法打开，例如握手失败，客户会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 Could not connect to Tranzila. Please try again in a moment. 技术原因会写入日志。

该扩展仅处理在 Tranzila 页面上完成的一次性银行卡付款。它不支持保存的银行卡或令牌、订阅、单独的授权和扣款（J5）、自有的 Bit、Apple Pay 或 Google Pay 按钮（您的 Tranzila 付款页面提供的任何方式都会显示在 iframe 中），也不支持 Tranzila 发票。

订单与退款

订单状态

无状态（缺失订单）: 客户已被转到付款页面，但尚未付款、付款被拒绝，或 Tranzila 通知尚未到达。在 Sales > Orders 中，只有将 Order Status 筛选条件设为 Missing Orders，才会显示此类订单。在 OpenCart 4.1 中，此类订单还可能具有 Voided 状态（OpenCart 在再次显示确认步骤时设置该状态）；扩展会将其视为无状态订单。

付款后的订单状态（默认 Processing）: 付款已通过经验证的通知确认。备注会显示金额、Tranzila 交易（index）、授权编号，以及分期期数（如有）。

On hold status（默认 Pending）: 付款已被报告，但未被自动接受：金额、货币或握手令牌不一致；由于 Trusted IP 为空，无法验证通知；或者通知已关闭，且客户从成功的付款页面返回。备注会说明原因。请在 Tranzila 终端中核对付款，并手动更改状态。

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

如果为处于搁置、已取消或付款错误状态的订单收到付款，该订单会获得 Order status after payment；已取消的订单还会收到一条备注，提醒您在发货前检查库存。如果为已付款或已退款的订单，或为已付款购物车中的另一订单收到第二笔付款，订单不会被更改。已付款订单上的备注会提醒您检查该订单，并在 Tranzila 终端中退还重复付款。同一交易的重复通知会被忽略。

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

VibeFox Tranzila Payment Gateway 选项卡

在 Sales > Orders 中打开一个通过 Tranzila 付款的订单。在订单页面底部，History 和 Additional 旁边的 VibeFox Tranzila Payment Gateway 选项卡会显示 Transaction (index)、Authorization、Terminal、Status、Paid / refunded 金额、Installments 期数、退款表单、退款记录、所有 Payment pages of the cart 及其结果，以及订单的 Tranzila notes。该选项卡对有权访问扩展的用户可见。

退款

在 VibeFox Tranzila Payment Gateway 选项卡中输入 Amount（会自动填入尚未退还的金额），可选填写 Reason (optional)，然后点击 Refund via Tranzila。确认询问 Refund this amount via Tranzila? This cannot be undone. 支持全额和部分退款。您需要有修改订单的权限（在 System > Users > User Groups 中的 sale/order）。退款会以 Tranzila 信用交易的形式针对原始付款进行，并在收取该付款的终端上执行，金额和货币与 Tranzila 实际扣款时一致。因此，在出现金额或货币不一致的情况后，您最多只能退还客户实际支付的金额，而不是订单总额。

只有在设置了终端密码且订单有已确认的 Tranzila 交易时，表单才可用。否则，选项卡会说明原因，例如 Refunds need the terminal password (TranzilaPW) in the gateway settings. 如果订单是在与当前设置不同的终端（例如测试终端）上付款的，则无法从订单页面退款；请在该 Tranzila 终端中退款。

如果 Tranzila 不接受退款，选项卡会显示错误，例如 Tranzila declined the refund，并附带代码及其含义，且不会记录任何退款。成功的退款会以 Tranzila 信用交易的形式添加到退款记录和备注中。全额退款会将订单设为 Refunded status，不会通知客户，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。

Sales > Returns 中的商品退货不会通过 Tranzila 退回款项。在 Tranzila 终端中进行的退款不会通知商店。如有需要，请手动更新订单。

许可证密钥

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

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

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

故障排除

Tranzila 未在结账时显示: 请检查许可证是否有效、Enable/Disable 是否已开启、Terminal name (supplier) 是否已填写，以及客户的货币是否为 ILS、USD、EUR 或 GBP。当终端名称缺失或默认货币不受支持时，设置页面会显示警告。另外，请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态: 通知未到达或被拒绝。请检查 Notifications 是否开启，以及 Trusted IP 是否列出了 Tranzila 发送通知的地址。错误会始终写入日志；请查看扩展页面上的 Log 字段。提示某个 IP 不在 Trusted IP 列表中，意味着需要修正 Trusted IP 设置或您的代理配置：在代理或 CDN 之后，Web 服务器必须将真实访客 IP 传递给 PHP。对于商店位于受信任反向代理之后的开发者，扩展会触发 OpenCart 事件 wcp_tranzila_payment_gateway/remote_ip 来设置 IP。

通知返回 Forbidden: 它来自不在 Trusted IP 中的 IP 地址。

通知返回 Bad request 或 Not found: 通知中的订单、付款页面令牌、终端或交易索引与本商店的任何付款页面都不匹配。

通知返回 Accepted for manual review: Trusted IP 为空，因此无法验证通知。成功的付款会使订单进入搁置状态。请填写 Trusted IP 以自动确认付款。

通知返回 Busy, retry: 购物车在同一时刻正被另一个请求处理，或无法设置订单状态。日志会显示原因。请在 Tranzila 终端中核对该付款。

部分订单处于搁置状态: 请阅读 VibeFox Tranzila Payment Gateway 选项卡中的备注。金额、货币或握手令牌不一致，或者无法验证通知（Trusted IP 为空，或通知已禁用）。请在 Tranzila 终端中核对付款，并手动更改状态。

开启握手后付款页面无法打开: 请检查终端名称和终端密码，检查 Tranzila 终端中是否已启用握手，并检查您服务器的 IP 地址是否已在那里允许。日志会显示原因。

退款失败: 退款需要 Terminal password (TranzilaPW)。有些终端还要求单独的信用密码；请将其填写到 Refund password (CreditPass) 中。在其他终端上付款的订单必须在该终端中退款。如果 Tranzila 的回复出乎意料，选项卡会说明退款未被确认：在重试之前，请先检查 Tranzila 终端。如果没有修改订单的权限，选项卡会显示 You do not have permission to refund orders.

其他货币: 该扩展仅支持 ILS、USD、EUR 和 GBP。

对于开发者：在显示付款页面之前，扩展会触发 OpenCart 事件 wcp_tranzila_payment_gateway/payment_page_params，其中包含付款页面和订单的字段。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Tranzila Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件和启动操作，后者允许通知和客户返回在维护模式下通过）。如果开启了 Delete data on uninstall，则其他设置（标题、描述、终端、密码、付款页面、付款确认、日志记录）和日志会被删除；如果关闭，这些内容会保留，以便之后重新安装时使用。Tranzila 交易和退款始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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