VibeFox TrustPay for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。在较旧的 PHP 版本上，模块会拒绝安装。

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

可访问的通知 URL：finby 必须能够从互联网访问您的店铺。店铺前面的防火墙、维护登录或 HTTP 身份验证会阻止付款通知。

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

安装

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

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

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

4. 输入测试项目的 Project ID 和 Secret key；如需进行真实付款，还要输入正式项目的 Project ID 和 Secret key（参见配置）。

5. 开启 Enable / Disable 并点击 Save。在开启 Test mode 的情况下进行一次测试付款，然后关闭 Test mode，即可接受真实付款。

安装时，模块会创建两个订单状态：Awaiting TrustPay payment 和 TrustPay payment on hold。PrestaShop 会将新的付款模块与安装时已启用的国家/地区关联。对于之后添加的国家/地区，请在 Payment > Preferences 中勾选该模块。您还可以在那里按货币和顾客群组限制该模块。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox TrustPay Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果模块已启用但当前模式的 Project ID 或 Secret key 为空，或者店铺的默认货币不受支持，页面会向您发出警告。在这两种情况下，付款方式都会在结账时隐藏。

TrustPay / finby

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Card payment (TrustPay)。必填。

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

API 凭据

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

Test mode：使用测试项目（不产生真实付款）。新的付款和退款使用测试凭据。订单的退款始终退回到订单付款时所用的项目。默认：on。开启期间，顾客会在付款方式下方看到 Test mode: no real payment will be taken.

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

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

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

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

Project ID 只能包含数字。如果您保存了其他值，页面会显示 must contain digits only — the previous value was kept.，同时其他字段仍会保存。Secret key 会按您输入的内容原样保存，仅去除开头和结尾的空格。已保存的 Secret key 不会再次显示。该字段会保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。保存设置还会清除缓存的 API 访问令牌，因此新凭据会立即生效。

Clear saved secrets：勾选一个 Secret key 并点击 Save 即可将其删除。空字段会保留已保存的值。

付款通知

只有在 finby 通过已签名的通知确认付款后，订单才会被标记为已付款。模块会在每次付款时自动发送通知 URL，因此您无需进行设置。该部分会在 Notification URL 下显示此 URL。如果启用了友好 URL，它的形式为 https://your-shop/module/wcp_trustpay_gateway/callback，前面可能带有语言代码。您也可以在 Merchant Portal 中将其填写为您项目的通知 URL。没有有效签名的通知会被拒绝。

模块不会自行向 finby 查询付款状态。如果某个通知无法到达您的店铺，在 finby 重新投递之前不会创建订单。finby 会重试通知。

高级

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

Debug logging：将 API 请求和通知记录到模块文件夹中的 logs/trustpay_p_debug.log.php。该文件无法通过网页打开。即使关闭此选项，错误仍会始终被记录。日志不包含密钥、令牌、银行卡数据或顾客信息。默认：off。

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

Delete data on uninstall：开启后，卸载模块时会删除模块设置和日志。订单数据会保留：订单、TrustPay 付款记录和退款，以及订单状态。默认：off。

结账

在付款步骤中，顾客选择付款方式（默认为 Card payment (TrustPay)）并确认订单。付款方式仅在受支持的货币下提供：EUR、CZK、HUF、GBP、PLN、NOK、SEK、DKK、BGN、RON、CHF 和 USD。HUF 金额以不带小数的形式发送。

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

模块会在 finby 上为购物车总额创建一个银行卡付款请求，金额以购物车货币计。顾客的姓名、地址和电子邮件会为 3-D Secure 而发送，购物车编号会作为参考一并发送。此时尚不存在订单。顾客会被重定向到 finby 付款页面，并在那里用银行卡付款。如果 finby 支持购物车语言，页面将以该语言显示，否则以英语显示。

付款后，顾客返回您的店铺。只有在 finby 通过已签名的通知确认后，订单才会被标记为已付款。返回这一动作本身绝不会改变付款状态。如果通知已经到达，顾客会看到标准的订单确认页面。如果尚未到达，则会显示 Payment confirmation 页面，说明 finby 正在确认银行卡付款，并且一经确认就会创建订单。该页面有一个 Check again 按钮和一个 Back to checkout 按钮。当订单处于 Awaiting TrustPay payment 或 TrustPay payment on hold 状态时，确认页面会显示 Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. 如果 finby 拒绝了付款，或未付款的订单已被取消，则会显示 Your card payment was not completed. Please contact us about this order.

如果顾客在付款页面取消，他会回到结账页面，并看到 The card payment was cancelled. You can try again or choose another payment method. 如果付款页面返回错误，或 finby 已经拒绝了付款，则显示 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. 技术原因会被写入日志。

即使店铺处于维护模式，通知仍然有效，并且不受店铺国家/地区限制的阻挡。

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

订单与退款

订单状态

No order yet：顾客已被转到 finby 但尚未付款，或通知尚未到达。此时只存在购物车。

Payment accepted or Delivered：finby 已确认付款，且金额和货币与付款请求及购物车总额一致。状态遵循 Order status after payment。付款会以 finby 付款请求 ID 作为交易 ID 记录，备注中会显示金额、付款请求以及项目（测试或正式）。

Awaiting TrustPay payment：finby 报告最近一笔付款待处理。订单会在 finby 确认付款后转为已付款状态。

TrustPay payment on hold：在两种情况下设置。付款仅获得授权，尚未扣款：请在 finby Merchant Portal 中扣款或取消，然后更新订单。或者，付款的金额或货币与付款请求或购物车总额不一致，例如顾客被转到付款页面后购物车又被修改：请在发货前核实付款。备注会说明具体情况。

Payment error：finby 拒绝了一个待处理订单的最近一笔付款。finby 发送原因时，备注会显示该原因。之后确认的付款仍会将订单转为已付款状态。

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

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

TrustPay / finby 付款区块

订单页面会显示 TrustPay / finby payment 区块，其中包括付款请求 ID、finby 付款 ID、项目、付款状态、请求金额和已付金额、已退款金额、测试付款的 Test project 标记、退款记录，以及该订单的 TrustPay notes。

退款

在 TrustPay / finby payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via TrustPay。确认提示 Refund this amount through TrustPay? This cannot be undone. 支持全额和部分退款。您需要具有编辑订单的权限；不需要访问模块页面。退款以 finby 为该付款报告的金额和货币进行，因此在金额不一致的情况下，您可以退款的上限是顾客实际支付的金额，而不是订单总额。HUF 退款必须为整数金额。

退款会退回到订单付款时所用的项目（测试或正式），即使您此后已切换过模式。该项目的 Project ID 和 Secret key 必须已设置，并且其 Project ID 不能已被更改。只有在 finby 接受退款后，退款才会被记录。否则，该区块会显示 TrustPay refused the refund: 及原因，并且不会记录任何退款。成功的退款会添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会改变状态。

模块不会创建退款单（credit slip）。订单页面上 PrestaShop 的标准退款按钮不会通过 finby 退回资金。在 finby Merchant Portal 中进行的退款不会被记录为退款。如果 finby 就此发送通知，该通知会作为备注添加，订单状态不会改变。

许可证密钥

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

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

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

故障排除

Card payment (TrustPay) 未出现在结账页面：请检查许可证是否有效、Enable / Disable 是否已开启，以及当前模式是否已设置 Project ID 和 Secret key：测试模式下为 Test Project ID 和 Test Secret key，正式模式下为 Live Project ID 和 Live Secret key。购物车货币必须是受支持的货币之一。当凭据缺失或默认货币不受支持时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车货币、顾客所在国家/地区以及顾客群组。

付款已完成，但未创建订单：通知未能到达您的店铺。请检查 Notification URL 下显示的 URL 能否从互联网访问（没有防火墙、维护登录或 HTTP 身份验证）。finby 会重试通知，订单会在通知到达时创建。请开启 Debug logging，并查看模块页面上的 Log 字段。

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

日志显示 Notification ignored：该通知对应的付款请求并非本店铺为该购物车创建的，或属于与付款发起时不同的项目或模式。不会进行任何更改。

通知收到的回复为 Busy, retry later 或 Temporary error：购物车在同一时刻正被另一条通知更新，或订单无法创建（例如模块已停用）。finby 会重试。日志会显示原因。

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

Card payment is temporarily unavailable：当当前模式没有 Project ID 或 Secret key 时，顾客会看到此消息。请输入它们并保存。

订单处于 TrustPay payment on hold：请阅读 TrustPay / finby payment 区块中的备注（参见订单状态）。在发货前，请在 Merchant Portal 中核实付款，然后完成订单或退还付款。

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

Invalid refund amount: at most … can be refunded：金额超过了已付金额减去通过模块已完成的退款。

卸载

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

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