VibeFox TrustPay for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法启用。

PHP：8.0 或更高版本。

finby（TrustPay）账户：您需要在 finby Merchant Portal 中有一个项目，并获取其 Project ID 和 Secret key。进行测试付款时，需要另一个测试（playground）项目，并拥有其自己的 Project ID 和 Secret key。无需其他密钥：Secret key 既用于获取 API 访问权限，也用于校验付款通知的签名。

可访问的通知 URL：finby 必须能够从互联网访问您的网站。防火墙、维护模式或网站密码保护会阻止付款通知。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_trustpay_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > TrustPay / finby，或在插件页面点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 输入正式项目的 Project ID 和 Secret key；如需测试，再输入测试项目的 Project ID 和 Secret key（参见配置）。

6. 开启 Enable / Disable 并保存。在开启 Test mode 的情况下进行一次测试付款，然后取消勾选 Test mode，即可接受真实付款。

从 1.0 版本升级时，您的 Project ID 和 Secret key 会保留为正式凭据，同时测试模式会被关闭。升级后请检查设置。

配置

所有设置都在同一页面中：WooCommerce > Settings > Payments > TrustPay / finby。当网关已启用，但当前模式的 Project ID 或 Secret key 为空，或店铺货币不受支持时，页面会在字段上方发出警告。在这两种情况下，结账时都会隐藏该付款方式。在付款方式列表中，在当前模式填写 Project ID 和 Secret key 之前，网关会被标记为需要设置。

General

Enable / Disable：Enable TrustPay / finby card payments 用于启用或禁用该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。默认：Card payment (TrustPay)。

Description：结账时显示在付款方式下方的文字。默认：Pay securely by card on the TrustPay / finby payment page.

API credentials

从 finby（TrustPay）Merchant Portal 复制您项目的 Project ID 和 Secret key。该部分包含一个指向 Merchant Portal 的链接。测试付款使用一个单独的测试（playground）项目，并拥有其自己的 Project ID 和 Secret key。该项目不会扣除任何真实款项。

Test mode：Use the test project (no real payments)。新的付款和退款会使用测试凭据。订单的退款始终退回到订单付款时所用的项目。默认：开启。

Live Project ID：您正式项目的数字 Project ID。

Live Secret key：正式项目的 Secret key。用于获取 API 访问令牌并校验付款通知。

Test Project ID：您测试（playground）项目的数字 Project ID。

Test Secret key：测试项目的 Secret key。

Project ID 只能包含数字。如果您保存了其他值，页面会显示错误，并保留之前的值。Secret key 会按您输入的原样保存，只会去除开头和结尾的空格。

Payment notifications

只有在 finby 通过已签名的通知确认付款后，订单才会被标记为已付款。插件会在每次付款时自动发送通知 URL，因此您无需进行设置。该部分会显示 URL，例如 https://your-site/wc-api/trustpay_payment_callback/。您也可以在 Merchant Portal 中将其填写为项目的通知 URL。没有有效签名的通知会被拒绝。

插件不会自行向 finby 查询付款状态。如果某条通知无法到达您的网站，订单将保持在 Pending payment，直到 finby 成功发送该通知。

Advanced

Order status after payment：付款成功后设置的订单状态。状态通过一步完成设置，因此顾客只会收到一封邮件。

Debug logging：Log API requests and notifications 会向日志添加详细信息。即使此选项关闭，错误也始终会被记录。日志位于 WooCommerce > Status > Logs，来源为 wcp_trustpay_gateway，且不包含密钥、令牌、银行卡信息或顾客详细信息。默认：关闭。

Delete data on uninstall：Remove the plugin settings and logs when the plugin is deleted (order data is kept)。默认：关闭。

结账

顾客选择付款方式（默认为 Card payment (TrustPay)）并下单。在测试模式下，结账页面会在描述下方显示 Test mode: no real payment will be taken.

银行卡付款需要账单地址。如果缺少街道、城市、邮政编码或国家，顾客会看到 Please enter your billing address (street, city, postcode and country) — it is required for card payments.

插件会在 finby 为订单总额创建一个以订单货币计价的银行卡付款请求。顾客的姓名、地址和电子邮件会被发送用于 3-D Secure，订单 ID 会作为参考一并发送。顾客会被重定向到 finby 付款页面，并在该页面完成银行卡付款。若 finby 支持，该页面将以您店铺的语言打开，否则以英语打开。订单备注会显示付款请求、金额和项目（测试或正式）。

付款后，顾客会返回您店铺的订单接收页面，购物车会被清空。只有在 finby 通过已签名的通知确认后，订单才会被标记为已付款。返回这一动作本身绝不会改变付款状态。

如果顾客在付款页面取消，或付款页面返回错误，顾客会回到 Pay for order 页面，并显示消息 The card payment was cancelled. You can try again or choose another payment method. 或 The card payment was not completed. Please try again or choose another payment method. 订单中会添加一条备注。顾客可以从该页面重新付款。

如果 finby 无法发起付款，顾客会看到 We could not start the card payment. Please try again in a moment or choose another payment method. 技术原因会被写入日志。

货币：EUR、CZK、HUF、GBP、PLN、NOK、SEK、DKK、BGN、RON、CHF 和 USD。HUF 金额以不带小数的形式发送。在 Pay for order 页面，会检查订单货币。

该付款方式可用于经典结账、结账区块以及 Pay for order 页面。它与 WooCommerce 高性能订单存储（HPOS）兼容。插件附带英语、斯洛伐克语和捷克语翻译。

插件仅接受银行卡付款，并且是在 finby 页面上一步完成的购买。它不支持银行转账或其他 finby 付款方式，不支持 Apple Pay 或 Google Pay 按钮，不支持保存银行卡，不支持订阅或定期付款，不支持分开的授权与扣款，也不支持状态轮询。

订单与退款

订单状态

Pending payment：顾客已被发送到 finby，但尚未付款，或通知尚未到达。

Processing or Completed：finby 已确认付款，且金额和货币与付款请求及订单总额一致。状态遵循 Order status after payment。订单备注会显示金额、付款请求和项目。交易 ID 即 finby 付款请求 ID。

On hold：在三种情况下设置。付款在 finby 仍处于待定状态，订单正在等待最终结果。付款仅获得授权，尚未扣款：请在 finby Merchant Portal 中扣款或取消，然后更新订单。或者付款金额或货币与付款请求或订单总额不一致，例如订单在顾客被发送到付款页面后被编辑过：请在发货前核实付款。订单备注会说明具体情况。

Failed：finby 拒绝了该订单的最近一次付款。finby 发送原因时，备注会显示该原因。顾客可以从 Pay for order 重新付款。

已取消或已退款的订单绝不会因迟到的付款而重新打开。备注会提示您在 Merchant Portal 中恢复订单或退款。如果已付款的订单又收到第二笔付款，订单不会改变，备注会提示您在 Merchant Portal 中退还重复付款。finby 报告的拒付（chargeback）和争议会以备注形式添加。

Refunds

打开订单，点击 Refund，输入金额，然后点击 Refund via Card payment (TrustPay)（按钮会显示您的 Title）。支持全额和部分退款。退款会退回到订单付款时所用的项目（测试或正式），即使您此后已切换模式，因此必须设置该模式的 Project ID 和 Secret key。HUF 退款必须为整数金额。

只有 finby 接受退款时，才会记录该退款。否则，WooCommerce 会显示 TrustPay refused the refund: 及原因，并且不会创建退款。成功的退款会添加到订单备注中。

在 finby Merchant Portal 中进行的退款不会被记录为 WooCommerce 退款。如果 finby 就此发送通知，该通知会作为订单备注添加，且订单状态不会改变。

许可证密钥

插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > TrustPay / finby 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时，以及您的域名。使用 Check now 可再次检查状态，Change key 用于输入其他密钥，Remove key 用于将密钥从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥不会释放域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，该付款方式不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可以正常进行。

许可证到期后，插件会继续运行，但更新和支持需要续订。状态会在后台自动重新检查。

故障排除

Card payment (TrustPay) 未出现在结账页面：请检查许可证是否有效，Enable / Disable 是否开启，以及当前模式是否已填写 Project ID 和 Secret key：测试模式下为 Test Project ID 和 Test Secret key，正式模式下为 Live Project ID 和 Live Secret key。店铺货币，或 Pay for order 页面上的订单货币，必须是受支持的货币之一。设置页面在这两种情况下都会显示警告。开发者可以使用过滤器 trustpay_p_supported_currencies 修改货币列表。

付款已完成，但订单仍为 Pending payment：通知未能到达您的店铺。请检查 https://your-site/wc-api/trustpay_payment_callback/ 能否从互联网访问（没有防火墙、维护模式或密码保护）。finby 会重试通知。请查看 WooCommerce > Status > Logs，来源为 wcp_trustpay_gateway。

日志显示 Notification rejected: invalid signature or unknown project：通知来自一个 Project ID 不在设置中的项目，或该项目的 Secret key 错误。店铺会回复 Invalid signature，订单不会被修改。请检查付款时所用模式的 Project ID 和 Secret key。

日志显示 Notification ignored：该通知所属的付款请求并非本店铺为该订单创建，或者属于与发起付款时不同的项目。订单不会被修改。

通知收到 Busy, retry later 的回复：订单在同一时刻正被另一条通知更新。finby 会重试。

顾客看到 We could not start the card payment：请打开日志。Project ID 或 Secret key 错误时，会显示 finby 拒绝了项目凭据的消息。请确认测试凭据填写在测试字段中，正式凭据填写在正式字段中。

银行卡付款暂不可用：当当前模式没有 Project ID 或 Secret key 时，顾客会看到此消息。请填写并保存。

订单显示 On hold，并带有金额/货币不一致的备注：该通知是真实的，但付款金额或货币与付款请求或订单总额不一致。请在发货前于 Merchant Portal 中核实付款，然后完成订单或退款。

退款失败，并提示项目相关信息：订单是通过测试或正式项目付款的，但该模式的 Project ID 或 Secret key 未设置，或者现在保存的是另一个 Project ID。请输入该项目的凭据，或在 finby Merchant Portal 中退款。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会继续使用上次已知的状态运行。

卸载

停用插件会保留所有数据。若要删除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态，以及缓存的 API 访问令牌，始终会被删除。网关设置和插件日志（日志文件，包括较早的轮转文件，以及数据库中的日志记录）仅在 Delete data on uninstall 开启时才会被删除。否则它们会保留，供之后重新安装使用。订单数据会被保留：现有订单会保留其付款备注、付款请求 ID 和交易 ID。

TrustPay 和 finby 是其各自所有者的商标。本插件与 TrustPay 或 finby 无关，也未获得其认可或背书。