VibeFox Tranzila for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝安装在更早的 PHP 版本上。

店铺货币：ILS、USD、EUR 或 GBP。对于其他购物车货币，付款方式在结账时会被隐藏。

Tranzila 终端：您需要终端名称。终端密码（TranzilaPW）用于 handshake 以及从订单页面退款。某些终端还需要单独的信用密码（CreditPass）才能退款。终端名称和密码由 Tranzila 提供：请查看您的终端设置，或咨询 Tranzila 支持。Tranzila 没有公开的沙盒环境。测试时，Tranzila 会为您提供单独的测试终端；请将其名称作为终端名称输入。

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

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Tranzila Payment Gateway，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。

4. 输入 Terminal name (supplier)；如果您使用 handshake 或退款，还需输入 Terminal password (TranzilaPW)。

5. 保持 Notifications 开启，并检查 Trusted IP：其中必须列出 Tranzila 发送通知所用的 IP 地址。请与 Tranzila 支持确认该列表。

6. 建议：在 Tranzila 终端中启用 handshake，并在那里允许您服务器的 IP，然后在模块中开启 Handshake。

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

安装时，模块会创建订单状态 Tranzila payment on hold。PrestaShop 会为新的付款模块默认提供所有货币、国家和客户组。您可以在 Payment > Preferences 中进行限制。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，页面会在以下情况提示您：终端名称为空（此时付款方式在结账时隐藏）、通知已禁用或 Trusted IP 为空（已付款订单此时将进入待人工审核状态）、启用了 handshake 但未设置终端密码（无法打开付款页面），以及店铺的默认货币不受支持。保存时，无效的终端名称、Trusted IP 中的无效条目，或不是整数的数字字段不会被保存：页面会显示错误，并保留之前的值。超出允许范围的数字会被保存为最接近的允许值，页面会告知您。

Tranzila

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

Title：顾客在结账时看到的付款方式名称，也是付款页面的标题。它同时也是订单中保存的付款方式名称。默认：Credit Card (Tranzila)。

Description：结账时显示在付款方式下方的文字。默认：Pay securely with your credit card on the Tranzila payment page.

终端

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

Terminal password (TranzilaPW)：终端的 API 密码。用于 handshake 以及从订单页面退款。

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

已保存的密码不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved passwords：勾选某个密码并点击 Save 即可将其删除。空字段会保留已保存的值。

付款页面

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

Payment page language：Tranzila 页面的语言：Site language、希伯来语、英语、俄语、西班牙语、德语、法语或日语。默认：希伯来语。若顾客购物车的语言属于上述语言之一，Site language 会使用该语言；否则使用英语。

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

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

Max installments：顾客在付款页面上可选择的最大分期数（tashlumim），最多 36。0 或 1 表示不分期。默认：0。终端必须已获准处理分期交易。

Handshake：使用 handshake 令牌锁定金额（推荐）。在打开付款页面之前，店铺会向 Tranzila 请求一个与金额绑定的一次性令牌，因此无法在浏览器中修改金额。此功能需要终端密码、Tranzila 终端中已启用 handshake，并且在那里允许您服务器的 IP 地址。默认：关闭。

付款确认

Tranzila 通知不进行签名。只有当通知来自 Trusted IP，且其付款页面令牌、购物车、终端、金额和货币与付款页面一致时，订单才会以已付款状态创建。使用 handshake 时，令牌还必须与付款页面一致。顾客从付款页面返回，永远不会将订单标记为已付款。

Notifications：通过 Tranzila 通知（notify URL）自动确认付款。默认：开启。关闭通知时，从成功的付款页面返回的顾客会创建状态为 Tranzila payment on hold 的订单，您需在核对 Tranzila 终端后手动确认付款。

Notification URL：仅供参考。使用友好 URL 时，它的形式为 https://your-shop/module/wcp_tranzila_payment_gateway/notify，可能带有语言代码。每次付款时都会将该 URL 发送给 Tranzila，因此您无需在 Tranzila 终端中输入它。

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

高级

Debug log：将付款页面、通知和退款事件记录到模块文件夹中的 logs/tranzila_p_debug.log.php。该文件无法通过 Web 打开。即使此选项关闭，警告和错误也始终会被记录。密码、令牌和顾客数据永远不会被写入。默认：关闭。

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

Delete data on uninstall：开启后，卸载模块时会删除设置和日志。Tranzila 交易和退款以及订单状态 Tranzila payment on hold 始终会保留，因为旧订单需要它们。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 Credit Card (Tranzila)），并看到说明及备注 After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the payment. 确认后，顾客会进入您店铺的一个付款页面。在该页面中，Tranzila 付款页面会在 iframe 中打开，显示以购物车货币计价的购物车总额、账单信息以及简短的商品列表。页面显示 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 页面上选择分期数。此时尚未创建订单。

付款成功后，Tranzila 会将顾客带回，整个窗口随之继续。只有当 Tranzila 通过通知确认付款后，订单才会被标记为已付款。如果通知已经到达，顾客会看到标准的订单确认页面，并显示 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 按钮。

如果付款被拒绝或取消，顾客会返回结账页面，并显示 The payment was not completed. You have not been charged — please try again or choose another payment method. 当 Tranzila 返回响应代码时，会附加原因和代码，例如卡已过期。购物车会被保留，不会创建订单。每次打开付款页面时，都会生成一个带有新令牌的新付款页面。

如果付款页面无法打开，例如 handshake 失败，顾客会看到一条简短提示，例如 Could not connect to Tranzila. Please try again in a moment. 以及 Choose another payment method 按钮。技术原因会写入日志。

即使店铺处于维护模式，通知仍会正常工作，并且不会被店铺的国家限制阻止。Classic 和 Hummingbird 主题使用相同的付款页面。

模块仅在 Tranzila 页面上接受一次性银行卡付款。它不支持保存的银行卡或令牌、订阅、分别授权与扣款（J5）、自有的 Bit、Apple Pay 或 Google Pay 按钮（Tranzila 付款页面提供的任何方式都会显示在 iframe 内），也不支持 Tranzila 发票。

订单与退款

订单状态

No order yet：顾客已被引导至付款页面但尚未付款，付款被拒绝，或 Tranzila 通知尚未到达。此时仅存在购物车。

Payment accepted：付款已通过经验证的通知确认。该付款会以 Tranzila 交易索引作为交易 ID 记录，备注中会显示金额、交易、授权号码，以及分期数（如有）。

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

Refunded：付款已通过模块全额退款。

如果针对已取消订单的付款到达，该订单会再次设为 Payment accepted，并附带备注，提醒您在发货前核对库存。如果针对已付款或已退款订单的第二笔付款到达，订单不会被更改。备注会要求您核对该笔付款，并在 Tranzila 终端中退还重复的款项。同一笔交易的重复通知将被忽略。

Tranzila 付款区块

订单页面会显示 Tranzila payment 区块，其中包括交易索引、授权号码、终端、状态、已付和已退金额、分期数、退款历史、所有 Payment pages of the cart 及其结果，以及订单的 Tranzila notes。

退款

在 Tranzila payment 区块中输入金额（会自动填入尚未退款的金额），可选填原因，然后点击 Refund via Tranzila。确认提示 Refund this amount via Tranzila? This cannot be undone. 支持全额和部分退款。您需要具有编辑订单的权限；无需访问模块页面。退款以原始付款的 Tranzila 信用交易形式进行，通过收款的终端，金额和货币为 Tranzila 实际扣款的金额和货币。因此，在出现金额或货币不一致的情况后，您最多只能退还顾客实际支付的金额，而非订单总额。

当设置了终端密码，并且订单具有带授权号码的已确认 Tranzila 交易时，表单才可用。否则该区块会说明原因，例如 Refunds need the terminal password (TranzilaPW) in the gateway settings. 如果订单是在当前设置之外的其他终端（例如测试终端）上付款的，则无法从订单页面退款；请在该 Tranzila 终端中退款。

如果 Tranzila 不接受退款，该区块会显示错误，例如 Tranzila declined the refund，并附带代码及其含义，并且不会记录任何退款。成功的退款会连同 Tranzila 信用交易一起添加到退款历史和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。

模块不会创建信用单（credit slips）。订单页面上标准的 PrestaShop 退款按钮不会通过 Tranzila 退回款项。在 Tranzila 终端中进行的退款不会报告给店铺。如有需要，请手动更新订单。

许可证密钥

模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。位于 Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure 设置上方的第一个区块是许可证区块 License — VibeFox Tranzila Payment Gateway。将密钥输入 License key 并点击 Activate。之后，该区块会显示已隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除该密钥。它们下方是一行 Product: presta-payment-tranzila 和链接 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 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Tranzila。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会通过 Tranzila 通知和返回店铺的方式确认，退款也可以正常进行。

许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Tranzila：请检查许可证是否有效，Enable/Disable 是否已开启，Terminal name (supplier) 是否已填写，以及购物车货币是否为 ILS、USD、EUR 或 GBP。如果终端名称缺失或默认货币不受支持，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于购物车货币、顾客所在国家和顾客所在客户组。

付款已成功，但未创建订单：通知未到达或被拒绝。请检查 Notifications 是否已开启，以及 Trusted IP 是否列出了 Tranzila 发送通知的地址。错误始终会写入日志；请查看模块页面上的 Log 字段。提示某 IP 不在 Trusted IP 列表中，意味着需要修正 Trusted IP 设置或您的代理配置：位于代理或 CDN 之后时，Web 服务器必须将访客的真实 IP 传递给 PHP。店铺位于受信任的反向代理之后的开发人员，可以使用 actionTranzilaPRemoteIp 钩子设置 IP。

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

通知返回 Bad request 或 Not found：通知中的购物车、付款页面令牌、终端或交易索引与本店铺的任何付款页面都不匹配。

通知返回 Accepted for manual review：Trusted IP 为空，因此无法验证通知。成功的付款会创建处于待处理状态的订单。请填写 Trusted IP 以自动确认付款。

通知返回 Busy, retry：购物车在同一时刻正被另一请求处理，或者无法创建订单（例如模块已禁用）。日志会显示原因。请在 Tranzila 终端中核对付款；如果该付款在终端中已获批准但未创建订单，请联系顾客或手动创建订单。

部分订单处于 Tranzila payment on hold 状态：请阅读 Tranzila payment 区块中的备注。金额、货币或 handshake 令牌不一致，或通知无法验证（Trusted IP 为空或通知已禁用）。请在 Tranzila 终端中核对该付款，并手动更改状态。

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

退款失败：退款需要 Terminal password (TranzilaPW)。某些终端还要求单独的信用密码；请在 Refund password (CreditPass) 中输入。在其他终端上付款的订单必须在该终端退款。如果 Tranzila 的响应出乎意料，该区块会提示退款未获确认：请先检查 Tranzila 终端，再尝试重新操作。

其他货币：模块仅支持 ILS、USD、EUR 和 GBP。

卸载

进入 Modules > Module Manager，打开 VibeFox Tranzila Payment Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Tranzila 交易和退款以及订单状态 Tranzila payment on hold 始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。

Tranzila 是其各自所有者的商标。本模块与 Tranzila 没有关联，也未获得 Tranzila 的认可。