VibeFox TrustPay for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

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

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

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

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包括 README.txt、OpenCart 3 安装包 wcp_trustpay_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_trustpay_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

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

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

4. 输入测试项目的 Project ID 和 Secret key，若要进行真实付款，还需输入正式项目的相关信息（参见配置）。每笔付款都会发送通知 URL，因此无需在 Merchant Portal 中进行任何设置。

5. 开启 Enable / Disable 并点击 Save。在 Test mode 开启时进行一笔测试付款，然后关闭 Test mode 以接受真实付款。

OpenCart 4

1. 进入后台的 Extensions > Installer，点击 Upload，然后选择文件 wcp_trustpay_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法工作。

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

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

4. 输入许可证密钥和 finby 项目信息的方式与 OpenCart 3 的第 3 至 5 步相同。两个版本的设置页面及其字段完全相同。只有通知 URL 不同（参见配置）。

新安装时，付款方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox TrustPay Gateway > Edit。各部分列于左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，若付款方式已启用但当前模式的 Project ID 或 Secret key 为空，或店铺默认货币不受支持，页面会提示您。在这两种情况下，付款方式都会在结账时隐藏。若没有修改扩展的权限，页面会显示设置但无法保存。

保存时，Title 不能为空且不能超过 128 个字符，Sort order 必须是整数（允许负值），Minimum total 必须是大于或等于 0 的数字，所选的地理区域和订单状态必须存在。否则不会保存任何内容，页面会显示提示。Project ID 只能包含数字：若您保存了其他值，页面会显示 must contain digits only — the previous value was kept.，其他字段仍会保存。

TrustPay / finby

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

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

Description：顾客在 Confirm Order 步骤中确认按钮上方看到的文字。默认：Pay securely by card on the TrustPay / finby payment page。

Sort order：该付款方式在结账时的位置。可留空或输入整数（允许负值）。

Geo zone：仅向付款地址位于所选地理区域内的顾客提供该付款方式。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Minimum total：订单需要达到的结账金额（以店铺默认货币计）才会提供该付款方式。留空表示没有最低金额。

API 凭据

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

Test mode：使用测试项目（不产生真实付款）。新的付款和退款使用测试凭据。订单的退款始终退至订单付款所用的项目。默认：开启。开启期间，顾客会在 Confirm Order 步骤看到 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。

Secret key 会按输入的原样保存，仅去除首尾空格。已保存的 Secret key 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。保存设置还会清除缓存的 API 访问令牌，因此新凭据会立即生效。

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

订单状态

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 finby 通过签名通知确认后，订单才会获得状态。下方每个字段都列出您的 OpenCart 订单状态。OpenCart 没有针对待付款或暂挂的 TrustPay 付款的专用状态，因此两者默认都使用待处理；订单备注和订单选项卡可以区分它们。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此选择。

Order status after payment：已付款订单的状态。默认：处理中。若希望已付款订单立即完成，请选择已完成。该状态只通过一步设置，因此顾客只会收到一封邮件。

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

TrustPay payment on hold：付款仅获得授权（需在 Merchant Portal 中进行扣款），或已付金额或货币与付款请求或订单总额不一致。默认：待处理。

Payment error：finby 拒绝了等待中订单的最近一笔付款。之后确认的付款仍会将订单转为已付款状态。默认：失败。

Cancelled order status：扩展不会设置此状态。处于此状态的订单不会因迟到的付款而重新打开；系统会添加一条备注。默认：已取消。

Refunded order status：在订单页面进行全额退款后设置。默认：已退款。

付款通知

只有在 finby 通过签名通知确认后，订单才会被标记为已付款。扩展会在每笔付款时自动发送通知 URL，因此您无需进行设置。该部分会在 Notification URL 下显示该 URL。在 OpenCart 3 中，它的格式类似 https://your-store/index.php?route=extension/payment/wcp_trustpay_gateway/callback，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_trustpay_gateway/payment/wcp_trustpay_gateway.callback，由您 OpenCart 安装的店铺地址生成。您也可以将其填写为 Merchant Portal 中项目的通知 URL。没有有效签名的通知会被拒绝。店铺处于维护模式时，该 URL 仍然有效（在 OpenCart 4 中，扩展的一个启动操作会放行该通知以及顾客的返回）。

扩展本身不会向 finby 查询付款状态。如果通知无法送达您的店铺，订单将保持无状态，直到 finby 成功送达通知。finby 会重试通知。

高级

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

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

Delete data on uninstall：开启时，卸载扩展会删除扩展设置和日志。订单数据会保留：订单、TrustPay 付款记录和退款。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。Secret key 不会被导出。

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Card payment (TrustPay)）。只有当顾客的货币属于支持的货币（EUR、CZK、HUF、GBP、PLN、NOK、SEK、DKK、BGN、RON、CHF 和 USD）时，才会提供该方式。在 Confirm Order 步骤中，顾客会看到您的描述以及备注 You will be redirected to the secure TrustPay / finby payment page to pay by card. OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客在 Payment method options 窗口中通过付款方式区块的 Choose 按钮选择付款方式，然后点击结账页面底部的 Confirm Order。

当顾客点击 Confirm Order 时，扩展会在 finby 为订单金额（以订单货币计）创建一个银行卡付款请求。HUF 金额以不含小数的形式发送。顾客的姓名、地址和电子邮件会为 3-D Secure 而发送，OpenCart 订单号会作为参考发送。银行卡付款需要地址：若缺少街道、城市、邮编或国家，顾客会看到 Please enter your billing address (street, city, postcode and country) — it is required for card payments. 在 OpenCart 4 中，默认不要求付款地址，缺失的字段会取自配送地址。顾客会被重定向到 finby 付款页面，并在该页面用银行卡付款。若 finby 支持，页面将以店铺语言打开，否则以英文打开。

付款后，顾客返回您的店铺。只有在 finby 通过签名通知确认后，订单才会被标记为已付款。返回本身绝不会改变付款状态。若通知已经到达，顾客会看到 OpenCart 订单成功页面。若尚未到达，Payment confirmation 页面会显示 TrustPay / finby is confirming your card payment. Your order is confirmed as soon as the payment is confirmed, and you will receive an e-mail — there is no need to pay again. 该页面有 Check again 按钮和 Back to checkout 按钮。当订单处于待处理或暂挂状态时，成功页面会显示 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 拒绝其付款时，顾客会收到关于新订单状态的邮件。如果 finby 拒绝了付款，或未付款的订单已被取消，成功页面会显示 Your card payment was not completed. Please contact us about this order. 在 OpenCart 4 中，顾客从 finby 付款页面返回时，一个简短的中间页面会重新打开您店铺的返回地址，从而保留购物车和顾客登录状态。

若顾客在付款页面取消，会返回结账页面并显示 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. 购物车会保留，顾客可以再次付款。在 OpenCart 4 中，这些提示会显示在结账页面上方。

在 OpenCart 3 中，每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账中的订单。一个购物车只会由一个订单付款：一旦购物车中的某个订单具有 TrustPay 状态，再次确认购物车会直接进入成功页面，而不会发起第二次付款。购物车的任何变化（包括数量变化）都会被视为需要单独付款的新购物车。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。付款取消或失败后，顾客会以新的 finby 付款请求支付同一订单。如果该订单在此期间已被关闭，顾客将返回结账页面，下一次 Confirm Order 会支付一个新订单：在付款被拒绝或未付款订单被取消后，显示 The card payment was not completed. Please try again or choose another payment method.；否则（例如订单已被您取消或退款），显示 Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.

若 finby 无法开始付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到 We could not start the card payment. Please try again in a moment or choose another payment method. 技术原因会写入日志。

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

订单与退款

订单状态

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

付款后的订单状态（默认处理中）：finby 已确认付款，且金额和货币与付款请求及订单总额一致。备注会显示金额、付款请求以及项目（测试或正式）。

TrustPay 付款待处理（默认待处理）：finby 将最近一笔付款报告为待处理。当 finby 确认付款后，订单会转为已付款状态。

TrustPay 付款暂挂（默认待处理）：在两种情况下设置。付款仅获得授权而未扣款：请在 finby Merchant Portal 中扣款或取消，然后更新订单。或者已付金额或货币与付款请求或订单总额不一致：请在发货前检查付款。备注会说明具体情况。款项已收到，因此可以退款。

付款错误（默认失败）：finby 拒绝了等待中订单的最近一笔付款。若 finby 发送了原因，备注中会显示该原因。之后确认的付款仍会将订单转为已付款状态。

已退款订单状态（默认已退款）：付款已通过扩展全额退款。

已取消或已退款的订单不会因迟到的付款而重新打开。备注会提示您恢复订单，或在 Merchant Portal 中退还该笔付款。若某个已付款订单收到第二笔付款，或同一购物车中已有已付款订单的另一订单收到付款，订单不会被更改，备注会提示您在 Merchant Portal 中退还重复付款。finby 报告的拒付和争议会以备注形式添加。

备注是订单历史记录（History）中顾客看不到的条目。备注以店铺的默认语言撰写。

VibeFox TrustPay Gateway tab

在 Sales > Orders 中打开一笔通过 TrustPay 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox TrustPay Gateway 选项卡会显示 Payment request ID、Payment ID、Project（测试付款会带有 Test project 标记）、Status、Requested / paid 和 Paid / refunded 金额、退款表单、退款历史、Payment requests of this order 以及 TrustPay notes。该选项卡仅向有权访问该扩展的用户显示。

退款

在 VibeFox TrustPay Gateway 选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via TrustPay。确认提示 Refund this amount through TrustPay? This cannot be undone. 支持全额和部分退款。您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。退款以 finby 为该付款报告的金额和货币进行，因此在金额出现差异后，您最多只能退还顾客实际支付的金额，而不是订单总额。HUF 退款必须为整数金额。

退款会退至订单付款所用的项目（测试或正式），即使您此后已切换模式。该项目的 Project ID 和 Secret key 必须已设置，且其 Project ID 不能已更改。只有 finby 接受退款时，退款才会被记录。否则选项卡会显示 TrustPay refused the refund: 及原因，且不会记录任何退款。成功的退款会添加到退款历史和备注中。全额退款会将订单设为 Refunded order status，但不通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会改变状态。

Sales > Returns 中的商品退货不会通过 finby 退还资金。在 finby Merchant Portal 中进行的退款不会被记录为退款。若 finby 就此发送通知，该通知会作为备注添加，订单状态不会改变。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox TrustPay Gateway 是 Extensions > Extensions > Payments > VibeFox TrustPay Gateway > Edit 页面中设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及用于重新检查状态的 Check now 按钮、用于输入其他密钥的 Change key 按钮，以及用于从本店移除密钥的 Remove key 按钮。其下方有 Product: opencart-payment-trustpay 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包含英文和俄文）。

若密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。店铺地址变更后，或在账户中释放了一个域名名额后，请点击 Check now。若无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只适用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

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

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

故障排除

Card payment (TrustPay) 没有出现在结账页面：请检查许可证是否有效，Enable / Disable 是否已开启，以及当前模式是否具有 Project ID 和 Secret key：测试模式下为 Test Project ID 和 Test Secret key，正式模式下为 Live Project ID 和 Live Secret key。顾客的货币必须属于支持的货币。若缺少凭据或默认货币不受支持，设置页面会显示警告。另请检查付款地址是否位于所选的 Geo zone 内，以及订单是否达到 Minimum total。

付款已完成，但订单仍无状态：通知未能到达您的店铺。请检查 Notification URL 下显示的 URL 是否可以从互联网访问（没有防火墙、维护登录或 HTTP 身份验证）。finby 会重试通知，订单会在通知到达时获得状态。错误总会写入日志；请查看扩展页面上的 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 时，顾客会看到此消息。请输入并保存。

订单处于暂挂状态：请阅读 VibeFox TrustPay Gateway 选项卡中的备注（参见订单状态）。发货前在 Merchant Portal 中检查付款，然后完成订单或退还付款。

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

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

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox TrustPay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable / Disable、Sort order、Geo zone、Minimum total 以及订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件和缓存的 API 访问令牌也会被删除（在 OpenCart 4 中，还包括其事件以及在维护模式下放行通知和顾客返回的启动操作）。若 Delete data on uninstall 已开启，则其他设置（标题、描述、测试模式、Project ID、Secret key、日志记录）和日志都会被删除。若已关闭，这些设置会保留，供以后重新安装时使用。TrustPay 付款记录和退款始终会保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注。

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

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