VibeFox Tranzila for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce，插件无法启用。
PHP：8.0 或更高版本。
店铺货币：ILS、USD、EUR 或 GBP。对于其他货币，结账时会隐藏该付款方式。
Tranzila 终端：您需要终端名称。终端密码（TranzilaPW）用于 handshake 以及从 WooCommerce 退款。某些终端在退款时还需要单独的信用密码（CreditPass）。终端名称和密码由 Tranzila 提供：请查看您的终端设置或咨询 Tranzila 支持。Tranzila 没有公开的沙盒环境。如需测试，Tranzila 会为您提供单独的测试终端；请将其名称作为终端名称填写。
真实访客 IP：付款通知会根据 Tranzila 服务器的 IP 地址进行核对。如果您的网站位于 Cloudflare 等代理或 CDN 之后，Web 服务器必须将真实访客 IP 传递给 PHP（REMOTE_ADDR）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_tranzila_payment_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Tranzila > Manage，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 填写 Terminal name (supplier)；如果使用 handshake 或退款，还需填写 Terminal password (TranzilaPW)。
6. 保持 Notifications 开启，并检查 Trusted IP：其中必须列出 Tranzila 发送通知所用的 IP 地址。请与 Tranzila 支持确认该列表。
7. 建议：在 Tranzila 终端中启用 handshake，并在那里允许您服务器的 IP 地址，然后在插件中开启 Handshake。
8. 开启 Enable/Disable，并使用 Tranzila 测试终端测试一笔付款。
配置
所有设置都在同一页面：WooCommerce > Settings > Payments > Tranzila。在字段上方，页面会在以下情况发出提醒：终端名称为空（此时结账时会隐藏该付款方式）、通知已禁用或 Trusted IP 为空（此时已付款订单会被置于待人工审核状态）、handshake 已开启但未设置终端密码（付款页面无法打开），以及店铺货币不受支持。保存时，无效的终端名称或无效的 Trusted IP 条目不会被保存：页面会显示错误，并保留之前的值。超出允许范围的数字会被修正为最接近的允许值。
General
Enable/Disable：Enable Tranzila Payment Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。默认：Credit Card (Tranzila)。
Description：结账时显示在付款方式下方的文字。默认：Pay securely with your credit card on the Tranzila payment page.
Terminal
Terminal name (supplier)：您的 Tranzila 终端名称，例如 myshop。仅允许字母、数字、“-”和“_”。在填写之前，结账时不会显示该付款方式。测试时，请填写您的 Tranzila 测试终端名称。
Terminal password (TranzilaPW)：终端的 API 密码。用于 handshake 以及从 WooCommerce 退款。
Refund password (CreditPass)：仅当您的终端要求为信用（退款）交易设置单独密码时才填写。否则请留空。
Payment page
Payment page version：iframe 中显示的 Tranzila 页面。
Payment page language：Tranzila 页面的语言：Site language、Hebrew、English、Russian、Spanish、German、French 或 Japanese。默认：Hebrew。Site language 在访客的 WordPress 语言为上述语言之一时使用该语言，否则使用 English。
iFrame width (px)：300 至 1200。默认：600。在小屏幕上，框架宽度永远不会超过页面宽度。
iFrame height (px)：400 至 1500。默认：650。
Max installments：顾客在付款页面上可以选择的最大分期数（tashlumim），最多 36 期。0 或 1 表示不分期。默认：0。终端必须已获准处理分期交易。
Handshake：Lock the amount with a handshake token (recommended)。在打开付款页面之前，商店会向 Tranzila 请求一个与订单金额绑定的一次性令牌，因此金额无法在浏览器中被修改。此功能需要终端密码、Tranzila 终端中已启用 handshake，并且您服务器的 IP 地址已在该终端中获准。默认：关闭。
Payment confirmation
Tranzila 的通知未经签名。只有当通知来自 Trusted IP，且其订单密钥、终端、金额和货币与订单一致时，订单才会被标记为已付款。开启 handshake 时，令牌还必须与订单的付款页面相匹配。顾客从付款页面返回，永远不会将订单标记为已付款。
Notifications：Confirm payments automatically with Tranzila notifications (notify URL)。默认：开启。通知 URL 会随每笔付款一起发送给 Tranzila，因此您无需在 Tranzila 终端中填写它。其格式为 https://your-site/wc-api/tranzila_p_callback/，并显示在该字段下方。关闭通知后，从成功付款页面返回的顾客订单会被置于待处理状态，您需要在 Tranzila 终端中核实后手动确认付款。
Trusted IP：发送通知的 Tranzila 服务器的 IP 地址或 CIDR 范围，以逗号分隔。默认：80.244.170.7。请与 Tranzila 支持确认当前列表。来自其他地址的通知会被拒绝。如果该字段为空，则无法验证通知：报告为成功的付款会使订单被置于待人工审核状态，报告为拒绝的付款则不会改变订单。
Advanced
Debug log：Log payment page, notification and refund events 会记录到 WooCommerce > Status > Logs，来源为 wcp_tranzila_payment_gateway。即使此选项关闭，错误也始终会被记录。密码、令牌和顾客数据从不写入日志。默认：关闭。
Delete data on uninstall：Delete the settings, logs and Tranzila order data when the plugin is deleted。默认：关闭。
结账
顾客选择付款方式（默认为 Credit Card (Tranzila)）并点击 Continue to 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 is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. 如果订单正在等待审核，页面会显示 Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed.
如果付款被拒绝或取消，顾客会返回订单付款页面，并显示 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 链接。技术原因会写入日志。
该付款方式适用于经典结账、结账区块以及 Pay for order 页面。在 Pay for order 页面上，如果订单货币受支持，则会提供该付款方式。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅在 Tranzila 页面上接受一次性银行卡付款。它不支持保存的银行卡或令牌、订阅、分别授权与扣款（J5）、自有的 Bit、Apple Pay 或 Google Pay 按钮（Tranzila 付款页面提供的任何方式都会显示在 iframe 内），也不支持 Tranzila 发票。
订单与退款
Order statuses
Pending payment：顾客已被引导至付款页面但尚未付款，或 Tranzila 通知尚未到达。
Processing or Completed：付款已通过经验证的通知确认。WooCommerce 会设置为 Processing；对于无需发货的订单则设置为 Completed。订单备注会显示金额、Tranzila 交易以及授权号；如有分期，还会显示分期数。交易 ID 为 Tranzila 交易索引。
On hold：已收到付款，但未被自动接受：金额、货币或 handshake 令牌与订单不符；由于 Trusted IP 为空，无法验证通知；或者通知已关闭且顾客从成功的付款页面返回。订单备注会说明原因。请在 Tranzila 终端中核对付款，并手动更改状态。
Failed：Tranzila 报告了待付款订单的付款被拒绝。备注会显示响应代码及其含义。已付款的订单绝不会被设置为 Failed。
如果已取消的订单收到付款，该订单会被重新打开，并附上备注提醒您在发货前检查库存。如果顾客在 Pay for order 页面切换了付款方式，但在仍然打开的 Tranzila 页面中完成付款，则订单的付款方式会被设回 Tranzila。如果已付款、已完成或已退款的订单又收到了第二笔付款，订单不会发生变化。备注会提醒您核查，并在 Tranzila 终端中退还重复付款。同一笔交易的重复通知会被忽略。
Refunds
打开订单，点击 Refund，输入金额，然后点击 Refund via Credit Card (Tranzila)（按钮会显示付款方式的标题）。支持全额和部分退款。退款以对原始付款的 Tranzila 信用交易方式进行。当终端密码已设置，且订单具有已确认且带有授权号的 Tranzila 交易时，该按钮可用。退款成功后，会以 Tranzila 信用交易的形式添加到订单备注中。
如果 Tranzila 不接受退款，WooCommerce 会显示错误，例如 Tranzila declined the refund 及代码，并且不会记录任何退款。使用的终端与当前设置中的终端不同（例如测试终端）所付款的订单，无法从 WooCommerce 退款；请在该 Tranzila 终端中退款。在 Tranzila 终端中完成的退款不会通知店铺。如有需要，可在 WooCommerce 中创建手动退款，而不使用 Tranzila 按钮。
许可证密钥
该插件需要从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Tranzila 的顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入另一个密钥，使用 Remove key 将其从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效密钥，结账时不会向顾客显示 Tranzila。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成插件的设置和测试。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也照常可用。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Tranzila does not appear at checkout：请检查许可证是否有效、Enable/Disable 是否开启、Terminal name (supplier) 是否已填写，以及店铺货币（在 Pay for order 页面上为订单货币）是否为 ILS、USD、EUR 或 GBP。如果缺少终端名称或货币不受支持，设置页面会显示警告。
The payment went through, but the order stays Pending payment：通知未到达或被拒绝。请检查 Notifications 是否开启，以及 Trusted IP 是否列出了 Tranzila 发送通知所用的地址。错误始终会记录在 WooCommerce > Status > Logs，来源为 wcp_tranzila_payment_gateway。如果提示某 IP 不在 Trusted IP 列表中，则说明需要修正 Trusted IP 设置或代理配置：在代理或 CDN 之后，Web 服务器必须将真实访客 IP 传递给 PHP。
Notification answers Forbidden：通知来自不在 Trusted IP 中的 IP 地址。
Notification answers Bad request or Not found：通知中的订单、订单密钥、终端或交易索引与本店铺的任何订单都不匹配。
Notification answers Accepted for manual review：Trusted IP 为空，因此无法验证通知。成功的付款会使订单被置于待处理状态。请填写 Trusted IP 以自动确认付款。
Notification answers Busy, retry：订单在同一时刻正被另一个请求处理，因此该通知未被应用。请在 Tranzila 终端中核对付款；如果订单仍在等待付款且付款在那里已获批准，请手动更改状态。
Some paid orders are On hold：请阅读订单备注。金额、货币或 handshake 令牌不匹配，或者无法验证通知（Trusted IP 为空或通知已关闭）。请在 Tranzila 终端中核对付款，并手动更改状态。
The payment page does not open with the handshake on：请检查终端名称和终端密码，确认 Tranzila 终端中已启用 handshake，并确认您服务器的 IP 地址已在该终端中获准。日志会显示原因。
Refunds fail：退款需要 Terminal password (TranzilaPW)。某些终端还需要单独的信用密码；请将其填写在 Refund password (CreditPass) 中。使用其他终端付款的订单必须在该终端中退款。
Other currencies：插件支持 ILS、USD、EUR 和 GBP。开发者可以使用 tranzila_p_currency_map 过滤器调整该列表。
The license block shows an error：请按照该区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件将沿用上一次已知的状态继续运行。
卸载
停用插件会保留所有数据。要彻底移除，请先停用，然后在 Plugins 页面将其删除。该插件的许可证密钥和许可证状态始终会被删除。网关设置、订单上保存的 Tranzila 数据以及插件日志（包括轮换的日志文件）仅在开启 Delete data on uninstall 时才会被删除；否则它们会保留，以便日后重新安装时使用。现有订单会保留其付款备注和交易 ID。
Tranzila 是其各自所有者的商标。本插件与 Tranzila 没有关联，也未获得 Tranzila 的认可。