VibeFox Flow for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：智利比索（CLP）或美元（USD）。对于其他结账货币，结账时会隐藏该付款方式。使用 CLP 时，请在 System > Localisation > Currencies 中将 CLP 货币的小数位数设为 0，因为 Flow 按整比索收费。

Flow 账户：您需要 Flow 账户的 API Key 和 Secret Key，它们位于 Flow 的 Mis datos, Datos técnicos 下。测试时，请在 sandbox.flow.cl 上创建单独的沙盒账户并使用其密钥。沙盒密钥与正式密钥不同。Flow 账户中无需进行任何设置。

公开网站：店铺的确认、返回和退款 URL 必须可从互联网访问，不能有密码保护或阻止 Flow 的防火墙。店铺的维护模式不会阻止这些 URL。

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

安装

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

OpenCart 3

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

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

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

4. 输入沙盒的 API Key 和 Secret Key，开启 Enable / Disable，点击 Save，然后下一个测试订单。

5. 要接受真实付款，请填写正式密钥，关闭 Sandbox mode，然后点击 Save。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的步骤 3 至 5 输入许可证密钥和 Flow 密钥。两个版本的设置页面及其字段相同。只有 Flow URLs 不同（参见 Flow URLs）；它们会随每笔付款一起发送，因此无需在 Flow 账户中做任何更改。

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

设置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Flow Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当当前模式的密钥为空（此时 Flow 不会在结账时显示）、店铺默认货币不是 CLP 或 USD，以及 CLP 货币设有小数位时，页面都会提示您（请将小数位设为 0，以便价格、总额和退款完全一致）。在沙盒模式下，页面会显示 Sandbox mode — payments go to sandbox.flow.cl, no real money is charged. 如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 必须为 1 至 128 个字符，Sort Order 必须为空或整数，Total 必须为空或不小于 0 的数字，并且所选的地理区域和订单状态必须存在。否则不会保存任何内容，页面会显示需要更正的内容。

Flow.cl

Enable / Disable：Enable Flow.cl payments 用于开启或关闭该付款方式。默认：关闭。

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

Description：在 Confirm Order 步骤中、确认按钮上方显示的付款方式说明。默认：Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.

Sort Order：Flow 在结账时付款方式中的排列位置。留空或输入整数。

Geo Zone：仅对所选地理区域内的付款地址提供 Flow。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的金额（以店铺默认货币计）才会提供 Flow。留空则在任何金额下都提供 Flow。

Flow API 凭据

从您的 Flow 账户（Mis datos, Datos técnicos）复制 API Key 和 Secret Key：正式密钥在 www.flow.cl，沙盒密钥在 sandbox.flow.cl（单独的沙盒账户）。沙盒模式只使用沙盒密钥，正式模式只使用正式密钥。

Sandbox mode：使用 Flow 沙盒（sandbox.flow.cl）和沙盒密钥。沙盒模式下不会扣除真实款项。默认：开启。若要接受真实付款，请将其关闭并填写正式密钥。退款始终使用订单付款时所在的环境。开启期间，顾客在 Confirm Order 步骤会看到 SANDBOX MODE — Payments go to the Flow sandbox. No real charges.

Sandbox API Key：您的 sandbox.flow.cl 账户的 API Key。

Sandbox Secret Key：您的 sandbox.flow.cl 账户的 Secret Key。它用于对每个请求进行签名。

Live API Key：您的 www.flow.cl 账户的 API Key。

Live Secret Key：您的 www.flow.cl 账户的 Secret Key。请妥善保密。

已保存的密钥不会再次显示。该字段将保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。

通知

每次付款和退款时，扩展都会向 Flow 发送三个 URL，因此无需在 Flow 账户中进行任何设置。本部分的 Flow URLs 字段列出这些 URL 供参考。它们根据您 OpenCart 安装的店铺地址生成，格式如下：

在 OpenCart 4 中，方法名称位于点号之后：https://your-store/index.php?route=extension/wcp_flow_gateway/payment/wcp_flow_gateway.confirmation、….back 和 ….refundCallback。

确认信息只包含一个付款令牌。扩展会在它创建的付款中查找该令牌，使用在付款创建环境中签名的请求向 Flow 查询付款状态，并且只采用 Flow 的答复。本店铺未创建的付款会被直接拒绝，不会向 Flow 查询。没有确认信息时，订单会在顾客从 Flow 返回时获得状态。

订单

OpenCart 在 Confirm Order 步骤中创建订单，此时不带状态（缺失订单，«missing order»）。只有在 Flow 报告付款之后（通过确认或顾客返回），订单才会获得状态。状态始终通过签名请求从 Flow 读取。下面每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：经验证的 Flow 付款之后设置的状态。默认：处理中。

Awaiting Flow Payment Status：顾客生成了现金付款券（Servipag、Multicaja 等类似方式）。款项稍后到账，Flow 会确认。默认：待处理。

Flow Payment On Hold Status：已付款，但金额或货币与订单不符，或款项是为已取消的订单到账的。备注会说明原因；请手动核查该付款。默认：待处理，因为 OpenCart 没有「On hold」状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Payment Rejected Status：等待付券付款的订单，其 Flow 付款被拒绝。默认：失败。

Payment Annulled Status：等待付券付款的订单，其 Flow 付款被撤销（annulled）。默认：已取消。

Refunded Status：在订单页面将付款全额退款后设置。默认：已退款。

高级

Debug log：将 API 调用和通知写入 OpenCart 日志文件夹（storage/logs）中的 flw_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移动到 flw_p_debug.old.log.php。密钥、签名和顾客数据绝不会被记录。即使该选项关闭，错误也始终会被记录。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展时会删除其设置和日志。订单中保存的 Flow 数据会保留。默认：关闭。

导入 / 导出

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

Import：粘贴先前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥会保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Flow）。在 Confirm Order 步骤中，顾客会看到您的说明以及提示 You will be redirected to Flow to complete the payment. OpenCart 在此步骤创建订单，仍然不带状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会以订单货币为该订单总额创建一笔 Flow 付款，主题为 Order # 加上订单号和店铺名称，并将顾客引导至 Flow 付款页面。顾客的电子邮件地址会传递给 Flow。在那里，顾客选择您 Flow 账户中已启用的付款方式。订单会添加备注 Flow payment started，其中包含金额、Flow 订单号和环境。

付款后，顾客返回您的店铺。只有在 Flow 确认之后，订单才会被标记为已付款：通过确认信息，或在顾客返回时通过签名的状态请求。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的下单成功页面。如果顾客生成了 Servipag 或 Multicaja 付款券，订单会获得 Awaiting Flow Payment Status，页面还会显示 Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. 如果金额不符，页面会显示 Your Flow payment was received and is being reviewed by the store.

如果顾客返回时无法连接 Flow，或者此时另一个请求正在确认订单，则会显示 Payment confirmation 页面，其中包含 We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly — please do not pay again.，以及 Check again 按钮和 Back to checkout 按钮。

如果付款被拒绝，顾客会返回结账页面，并看到 Your Flow payment was rejected. Please try again or choose another payment method. 订单保持无状态。如果顾客在未付款的情况下离开了 Flow 页面，提示为 The Flow payment was not completed. You can try again or choose another payment method. 如果无法将返回信息与任何付款对应，提示为 We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. 购物车会保留。在 OpenCart 4 中，这些提示会显示在结账页面上方。

顾客可以重试。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账中的订单，因此新的尝试会用新的 Flow 付款支付同一订单。Flow 无法取消已经发起的付款。因此，在发起新付款之前，系统会向 Flow 检查该订单以及同一购物车在最近两天内其他订单的未完成 Flow 付款。如果其中某笔已付款或已生成付款券，顾客会被带到成功页面，而不是再次付款。如果同一购物车的另一个订单已通过 Flow 付款，也不会发起新付款。如果同一购物车被重复付款（例如在两个浏览器标签页中），则只有第一笔付款会为其订单设置状态：另一个订单保持无状态，已付款的订单会收到一条备注，提醒您在 Flow 账户中退还第二笔付款。

OpenCart 4 会将订单保留在结账流程中，直到显示成功页面为止。如果该订单在此期间未付款即被关闭（例如您取消了它），顾客会被送回结账页面，并看到 The Flow payment was not completed. You can try again or choose another payment method.；下一次点击 Confirm Order 将为购物车支付一个新订单。如果该订单已付款或已有付款券，但之后购物车发生了变化（包括数量改变），顾客会被送回结账页面，下一次点击 Confirm Order 将以新订单支付新的购物车。已付款的订单绝不会在另一个购物车中显示为已付款。

如果 Flow 无法发起付款，顾客会停留在 Confirm Order 步骤，并看到一条简短提示，例如 Could not connect to Flow. Please try again in a moment. 详细信息记录在日志中。

该扩展仅支持一次性付款。它不支持保存银行卡、订阅、定期扣款或付款链接，也不会预先选择任何 Flow 付款方式。如果顾客在订单已付款后又支付了一笔旧的 Flow 付款，订单会收到一条备注，提醒您在 Flow 中退还重复付款。

订单与退款

订单状态

无状态（missing order）：顾客已被转到 Flow 但尚未付款，付款被拒绝或未完成，或 Flow 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：Flow 报告付款已完成，且金额和货币一致。备注会显示金额和 Flow 订单号。

Awaiting Flow Payment Status（默认 Pending）：顾客生成了现金付款券。备注会注明付款券的类型。Flow 确认付款后，订单会转为 Order Status After Payment。

Flow Payment On Hold Status（默认 Pending）：Flow 报告的金额或货币与订单总额不同，或者有付款到达了一个已取消的订单。Flow 收取的付款会被记录，备注会说明情况。请核查订单，然后发货或退还该付款。

Payment Rejected Status（默认 Failed）：Flow 拒绝了一个等待中订单的付券付款。

Payment Annulled Status（默认 Canceled）：等待中订单的付券付款已在 Flow 中被撤销。

Refunded Status（默认 Refunded）：付款已通过该扩展全额退款。

如果已付款的订单又收到另一笔付款，订单不会被更改。备注会请您在 Flow 账户中退还重复付款。已退款的订单永远不会重新打开。

备注是订单 History 中的条目，顾客看不到。

VibeFox Flow Gateway 选项卡

在 Sales > Orders 中打开一笔使用 Flow 付款的订单。在订单页面底部，History 和 Additional 旁边的 VibeFox Flow Gateway 选项卡会显示 Flow order 编号及付款方式，沙盒付款会带有 Sandbox 标签，并显示 commerceOrder 参考号（以及尝试次数）、付款的 Status、Paid / refunded 金额、退款表单、退款历史以及该订单的 Flow notes。该选项卡对有权访问该扩展的用户可见。

退款

在该选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Flow。确认提问 Refund this amount via Flow? Flow e-mails the customer to complete the refund. 支持全额和部分退款。您需要修改该扩展的权限（在 System > Users > User Groups 中设置）。退款金额以 Flow 实际扣款的金额为限，因此在金额不符的情况下，您最多只能退还顾客实付的金额，而不是订单总额。CLP 退款必须为整数金额。退款会发送到付款时所在的环境（沙盒或正式），因此该环境的密钥必须已填写，并且顾客需要有效的电子邮件地址。如果 Flow 拒绝退款，该选项卡会显示错误，且不会记录任何退款。成功的请求会添加到退款历史和备注中，并附上 Flow 退款编号和状态。全额退款会将订单设为 Refunded Status，且不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。Flow 确认付款后即可进行退款。

Flow 报告的退款后续状态变化会添加到备注中。如果 Flow 之后拒绝或取消了退款，备注会说明款项未退还给顾客，且该金额可以再次退款。Sales > Returns 中的商品退货不会通过 Flow 退还款项。在 Flow 后台创建的退款不会导入 OpenCart。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Flow Gateway 是 Extensions > Extensions > Payments > VibeFox Flow Gateway > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮挡的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（将密钥从本店铺移除）。其下方是 Product: opencart-payment-flow 一行和 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 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Flow。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍会在店铺中看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前进行设置和测试。在 OpenCart 4 中此预览不可用：店铺无法看到管理员的登录状态，因此没有有效密钥时，该付款方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也照常可用。

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

故障排除

结账时不显示 Flow：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式的密钥是否已填写（沙盒模式下为沙盒密钥，正式模式下为正式密钥），以及结账货币是否为 CLP 或 USD。还要检查付款地址是否位于所选的 Geo Zone 内，以及订单金额是否达到设置中的 Total。

付款已完成，但订单仍无状态：Flow 的确认信息没有到达您的店铺，且顾客也没有返回。请检查 Flow URLs 中显示的确认 URL 能否从互联网打开，且未被密码保护或防火墙阻止。开启 Debug log，并查看扩展页面上的 Log 字段。

确认信息返回 Payment does not belong to the order：该令牌不是本店铺创建的付款，或 Flow 为它报告了另一个参考号。不会进行任何更改。

确认信息返回 Gateway not configured：该付款所在环境的密钥为空。请重新输入。Flow 会重试确认。

确认信息返回 Flow API unavailable or Busy, retry：向 Flow 发出的状态请求失败，或者该订单在同一时刻正在被另一个请求确认。Flow 会重试确认。

顾客看到 Flow payments are not available at the moment：密钥缺失，或 Flow 拒绝了它们。请检查当前模式的 API Key 和 Secret Key。

顾客看到 This payment method is not available. Please reload the checkout page.：结账会话已与订单不再匹配，或付款方式在此期间已被关闭。顾客需要重新加载结账页面。

顾客看到 A valid billing email is required for Flow payments：Flow 需要顾客的电子邮件地址。

顾客看到 The order total is too small to be paid with Flow：订单总额在订单货币下会被舍入为零。

顾客已付款，但订单处于等待或挂起状态：请阅读 VibeFox Flow Gateway 选项卡中的备注。顾客生成的现金付款券尚未付款，或 Flow 报告的金额或货币与订单不符。带小数的 CLP 总额会被舍入为整比索，因此请将 CLP 的小数位数设为 0。

选项卡中没有退款表单：该选项卡会说明原因：付款尚未确认、已全额退款、您的用户组没有修改该扩展的权限，或付款所在环境的密钥为空。

退款失败，并显示与沙盒或正式密钥有关的信息：订单是在该环境中付款的，而其密钥为空。请输入密钥后重试。

退款失败，显示 Flow accepts CLP refunds in whole units only：请输入整数金额。

对于开发人员，该扩展会触发 OpenCart 事件 wc_flw_supported_currencies（提供该付款方式的货币）和 wc_flw_payment_subject（发送给 Flow 的付款主题）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Flow Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除扩展自己的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件以及在维护模式下允许 Flow URLs 通过的启动操作）。如果 Delete data on uninstall 已开启，其他设置（标题、说明、沙盒模式、密钥、调试日志开关）和日志都会被删除。如果关闭，这些内容会保留，以便日后重新安装时使用。Flow 的付款和退款记录始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

Flow 是其各自所有者的商标。本扩展与 Flow 没有关联，也未获得 Flow 的认可。