VibeFox Flow for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块不会在较旧的 PHP 版本上安装。
币种：智利比索（CLP）或美元（USD）。对于使用其他币种的购物车，结账时会隐藏该付款方式。对于 CLP，请在 International > Localization > Currencies 中将 CLP 币种的精度设置为 0，因为 Flow 按整数比索收费。
Flow 账户：您需要 Flow 账户的 API Key 和 Secret Key，可在 Flow 的 Mis datos, Datos técnicos 下找到。测试时，请在 sandbox.flow.cl 上创建单独的沙盒账户并使用其密钥。沙盒密钥与正式密钥不同。Flow 账户中无需进行任何配置。
公开网站：商店的确认、返回和退款 URL 必须可从互联网访问，不能有密码保护或阻止 Flow 的防火墙。商店的维护模式不会阻止它们。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Flow Gateway 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 输入沙盒 API Key 和 Secret Key，开启 Enable / Disable，点击 Save，并创建一个测试订单。
5. 要接受真实付款，请填写正式环境密钥并关闭 Sandbox mode。
安装时，模块会创建两个订单状态：Awaiting Flow payment 和 Flow payment on hold。PrestaShop 会为所有币种、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中限制它们。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Flow Gateway > Configure。每个包含字段的部分都有自己的 Save 按钮，会保存整个页面。在字段上方，如果当前模式的密钥为空（此时结账中会隐藏 Flow）、商店的默认币种不是 CLP 或 USD，或者 CLP 币种带有小数位，页面会发出提醒（请将其精度设置为 0，以确保价格、总额和退款完全一致）。在沙盒模式下，页面会显示 Sandbox mode — payments go to sandbox.flow.cl, no real money is charged.
Flow.cl
Enable / Disable：Enable Flow.cl payments 用于开启或关闭该付款方式。默认：off。
Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Flow。必填。
Description：结账时付款方式下方显示的文本。默认：Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.
Flow API 凭据
从您的 Flow 账户（Mis datos, Datos técnicos）复制 API Key 和 Secret Key：正式密钥在 www.flow.cl，沙盒密钥在 sandbox.flow.cl（单独的沙盒账户）。
Sandbox mode：使用 Flow 沙盒（sandbox.flow.cl）和沙盒密钥。沙盒模式下不会扣除真实款项。默认：on。关闭它并填写正式密钥即可接受真实付款。退款始终使用订单付款时所在的环境。
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 saved keys：勾选某个密钥并点击 Save 即可将其删除。字段为空则保留已保存的值。
通知
模块会在每次付款和退款时向 Flow 发送三个 URL，因此无需在 Flow 账户中配置任何内容。本部分的 Flow URLs 字段会列出这些 URL。启用友好 URL 时，它们的格式如下：
确认只包含一个付款令牌。模块会在它创建的付款中查找该令牌，通过在付款创建时所在环境中发送带签名的请求向 Flow 查询付款状态，并且只采用 Flow 的回复。本商店未创建的付款会被直接拒绝，不会向 Flow 查询。如果没有确认，订单会在顾客从 Flow 返回时创建。
高级
Debug log：将 API 调用和通知写入模块文件夹中的 logs/flw_p_debug.log.php。该文件无法通过网页打开。密钥和顾客数据绝不会被记录。即使关闭，错误也始终会被记录。默认：off。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载模块会删除其设置和日志。订单上保存的 Flow 数据会保留。默认：off。
结账
在付款步骤中，顾客选择付款方式（默认为 Flow）并看到说明。在沙盒模式下，页面会显示 SANDBOX MODE — 付款将进入 Flow 沙盒，不会产生真实扣款。确认后，模块会按购物车币种为购物车总额创建一笔 Flow 付款，主题为 Cart # 加上购物车编号和商店名称，然后将顾客转到 Flow 付款页面。顾客的电子邮件地址会传递给 Flow。顾客在那里选择您 Flow 账户中已启用的付款方式。此时还不存在订单。
付款后，顾客返回您的商店。只有在 Flow 确认后，订单才会被标记为已付款：通过确认，或在顾客返回时通过带签名的状态请求。随后创建订单，顾客会看到标准的订单确认页面，显示 Your payment with Flow has been received. 如果顾客生成了 Servipag 或 Multicaja 凭证，订单会以 Awaiting Flow payment 状态创建，页面显示 Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. 如果凭证订单的付款之后失败或被取消，页面显示 Your Flow payment was not completed. Please contact us about this order. 如果金额不匹配，页面显示 Your Flow payment was received and is being reviewed by the shop.
如果顾客返回时无法连接 Flow，或者此时另一个请求正在创建订单，Payment confirmation 页面会请顾客不要再次付款，并提供 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. 购物车会被保留，每次新的尝试都会创建一笔新的、与购物车绑定的 Flow 付款。
如果 Flow 无法启动付款，顾客会留在结账页面，并看到简短提示，例如 Could not connect to Flow. Please try again in a moment. 详细信息记录在日志中。
如果购物车中的优惠券在付款与确认之间失效，PrestaShop 会将其从订单中移除。由于顾客是按优惠后的价格付款的，订单会进入 Flow payment on hold 状态并附带备注。
模块仅接受一次性付款。不支持保存银行卡、订阅、定期扣款或付款链接，也不会预先选定 Flow 付款方式。Flow 无法取消已创建的付款链接：如果顾客在购物车已付款后支付旧链接，订单会获得一条备注，提示您在 Flow 中退还重复付款。
订单与退款
订单状态
No order yet：顾客已被转到 Flow 但尚未付款，或 Flow 尚未确认付款。此时只存在购物车。
Payment accepted：Flow 报告付款已完成，且金额和币种一致。付款以 Flow 订单号作为交易 ID 记录，备注中显示金额、Flow 订单号和付款方式。
Awaiting Flow payment：顾客生成了 Servipag 或 Multicaja 付款凭证。Flow 确认付款后，订单会变为 Payment accepted。
Flow payment on hold：Flow 报告的金额或币种与订单总额不同（例如付款开始后购物车被修改）、优惠券被移除，或收到了已取消订单的付款。Flow 收取的付款会被记录，备注会说明情况。请检查订单，然后发货或退款。
Payment error：Flow 拒绝了等待中订单的凭证付款。
Canceled：等待中订单的凭证付款已在 Flow 中作废。
Refunded：付款已通过模块全额退款。
如果已付款的订单又收到另一笔付款，订单不会被更改。备注会提示您在 Flow 账户中退还重复付款。已退款的订单绝不会重新开启。
Flow 付款区块
订单页面会显示 Flow payment 区块，其中包括 Flow 订单号和付款方式、commerceOrder 参考号、付款状态、已付和已退金额、沙盒付款的 Sandbox 标记、退款记录以及订单的 Flow notes。
退款
在 Flow payment 区块中输入金额（会自动填入尚未退款的金额），可选填原因，然后点击 Refund via Flow。确认提示 Refund this amount via Flow? Flow e-mails the customer to complete the refund. 支持全额和部分退款。您需要具有编辑订单的权限。退款金额受 Flow 实际扣款金额的限制，因此金额不一致后，您最多只能退还顾客已付的金额，而不是订单总额。CLP 退款必须为整数金额。退款会发送到付款时所在的环境（沙盒或正式），因此该环境的密钥必须已设置，并且顾客需要有效的电子邮件地址。如果 Flow 拒绝退款，区块会显示错误，并且不会记录任何退款。成功的请求会添加到退款记录和备注中，并附带 Flow 退款号和状态。全额退款会将订单设为 Refunded。部分退款不会更改状态。Flow 确认付款后即可办理退款。
Flow 报告的后续退款状态变更会添加到备注中。如果 Flow 之后拒绝或取消退款，备注会说明款项未退还给顾客，并且该金额可以再次退款。模块不会生成退款凭证（credit slip）。订单页面上标准的 PrestaShop 退款按钮不会通过 Flow 退款。在 Flow 控制面板中创建的退款不会导入 PrestaShop。
许可证密钥
模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Flow Gateway 是 Modules > Module Manager > VibeFox Flow Gateway > Configure 页面中位于设置上方的第一个区块。将密钥输入 License key，然后点击 Activate。之后，该区块会显示遮蔽后的密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮 Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此商店移除密钥）。它们下方是 Product: presta-payment-flow 这一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。商店地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥只能用于一个域名：即主商店的域名，多店铺设置中也是如此。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Flow。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。提醒会出现在 Modules > Module Manager 的 Alerts 选项卡中。现有订单不受影响：已开始的付款仍会被确认，退款也照常工作。
许可证过期后，模块仍会继续运行，但更新和支持需要续期。在您于后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
结账时看不到 Flow：请检查许可证是否有效、Enable / Disable 是否开启、当前模式的密钥是否已填写（沙盒模式使用沙盒密钥，正式模式使用正式密钥），以及购物车币种是否为 CLP 或 USD。在 Payment > Preferences 中，检查模块是否允许用于购物车币种、顾客所在国家和顾客群组。
已付款，但没有创建订单：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。
顾客看到 A valid billing email is required for Flow payments：Flow 需要顾客的电子邮件地址。
顾客看到 The order total is too small to be paid with Flow：购物车总额按购物车币种四舍五入后为零。
顾客已付款，但订单为 Awaiting Flow payment 或 Flow payment on hold：请阅读 Flow payment 区块中的备注。顾客生成了尚未付款的现金凭证，或者 Flow 报告的金额或币种与订单不符。带小数的 CLP 总额会四舍五入为整数比索，因此请将 CLP 精度设置为 0。
退款失败，并显示有关沙盒或正式密钥的消息：订单是在该环境中付款的，而该环境的密钥为空。请输入密钥后重试。
退款失败，显示 Flow accepts CLP refunds in whole units only：请输入整数金额。
对于开发者，README 列出了以下钩子：actionWcpFlowSupportedCurrencies（提供该付款方式的币种）和 actionWcpFlowPaymentSubject（发送给 Flow 的付款主题）。
卸载
进入 Modules > Module Manager，打开 VibeFox Flow Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Flow 付款和退款记录，以及 Awaiting Flow payment 和 Flow payment on hold 订单状态始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Flow 是其各自所有者的商标。本模块与 Flow 无关联，也未获得 Flow 的认可。