VibeFox Barion for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
Barion 店铺：您需要店铺的 POSKey（密钥）以及接收付款的 Barion 钱包电子邮件地址。两者都可在 Barion 门户中找到：正式环境为 secure.barion.com，测试环境为 secure.test.barion.com，位于 My stores 下您的店铺中。测试和正式环境的凭据不同。
币种：购物车币种必须为 HUF、EUR、USD 或 CZK。对于其他币种，结账时会隐藏该付款方式。
可访问的店铺：Barion 会在每笔付款后调用您的店铺，因此网站必须可从互联网访问，前面不能有防火墙或基本身份验证。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Barion Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key，然后点击 Activate（参见“许可证密钥”）。
4. 输入测试 POSKey 和测试钱包电子邮件，保持 Test Mode 开启，开启 Enable/Disable，然后点击 Save。下一步是下一笔测试订单。
5. 一切正常后，输入正式环境的凭据并关闭 Test Mode。
回调 URL 会随每笔付款自动发送给 Barion。无需在 Barion 门户中进行任何设置。
安装时，模块会创建两个订单状态：Awaiting Barion payment 和 Barion payment on hold。PrestaShop 会为所有币种、国家和客户组提供一个新的付款模块。您可以在 Payment > Preferences 中进行限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Barion Gateway > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。在字段上方，如果当前模式没有 POSKey 或收款人电子邮件（此时结账时会隐藏该付款方式），或者您店铺的默认币种不受 Barion 支持，页面会发出警告，并列出受支持的币种。测试模式开启时，页面会显示：测试模式已开启：付款将发送到 Barion 沙盒（api.test.barion.com），不会收取任何真实款项。
Barion
Enable/Disable：Enable Barion Payment 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Barion。必填。
Description：结账时显示在付款方式下方的文字。默认：Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay。
Barion 店铺凭据
在 Barion 门户中获取您的 POSKey 和钱包电子邮件：secure.barion.com（正式）或 secure.test.barion.com（测试），My stores，您的店铺。测试模式仅使用测试凭据，正式模式仅使用正式凭据。
Test Mode：使用下方填写的测试凭据和 Barion 沙盒（api.test.barion.com）。不会收取任何真实款项。默认：开启。关闭它即可接收真实付款。开启期间，顾客会在付款方式下方看到：测试模式：不会进行任何真实付款。
Test POSKey：您的店铺在 Barion 测试系统中的密钥（POSKey）（secure.test.barion.com，My stores）。
Test Payee Email：接收测试付款的 Barion 测试钱包电子邮件地址。
Live POSKey：您的店铺在 Barion 正式系统中的密钥（POSKey）（secure.barion.com，My stores）。
Live Payee Email：接收付款的 Barion 钱包电子邮件地址。
已保存的 POSKey 不会再次显示。该字段保持为空，并显示：已保存 — 留空即可保留。只有在想要更改时才输入新值。
Clear saved POSKeys：勾选某个密钥并点击 Save 即可将其删除。字段留空则保留已保存的值。
Callback URL：Barion 在每笔付款后调用的地址，例如使用友好 URL 时为 https://your-shop/module/wcp_barion_gateway/callback，可能带有语言代码，如 /en/。它会随每笔付款发送给 Barion，因此无需任何配置。它只需可从互联网访问。
订单
Order Status After Payment：付款成功并经验证后设置的订单状态。
仍在 Barion 处理中的付款会保持在 Awaiting Barion payment。金额或币种不一致的情况总是进入 Barion payment on hold。
高级
Logging：将 Barion 的请求和回调写入模块文件夹中的 logs/barion_p_debug.log.php。该文件无法通过网页打开。密钥和钱包电子邮件不会被记录。默认：关闭。关闭期间不写入任何内容，包括错误。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data on Uninstall：开启时，卸载模块会删除模块设置和日志。订单、其 Barion 付款数据和订单状态始终保留。默认：关闭。
结账
在付款步骤，顾客选择付款方式（默认为 Barion），并看到提示：您将被转到安全的 Barion 付款页面。确认后，模块会以购物车币种为购物车总额发起 Barion 付款，并将顾客转到 Barion 付款页面。付款中会列出商品、运费、礼品包装和税款；付款显示为 Cart 并附有购物车编号；顾客的电子邮件会作为提示传递；如果 Barion 支持，页面语言会跟随购物车的语言。此时尚不存在任何订单。
付款后，顾客返回您的店铺，Barion 也会调用回调 URL。这两个请求本身都不会将任何内容标记为已付款：模块会使用发起付款时所用模式的 POSKey 向 Barion 查询付款状态。只有在 Barion 确认付款，并且金额和币种与购物车一致后，订单才会被标记为已付款。返回链接包含购物车的安全密钥，且只检查为该购物车发起的付款。
如果付款成功，订单即被创建，顾客会看到标准的订单确认页面，并显示：您的 Barion 付款已收到。如果付款仍在 Barion 处理中，订单会以 Awaiting Barion payment 状态创建，页面显示：您的付款正在由 Barion 确认。确认后您将收到电子邮件。如果此类付款之后在 Barion 被取消、过期或失败，页面会显示：您的 Barion 付款未完成。请就此订单与我们联系。如果顾客返回时无法连接 Barion，将显示一个付款确认页面，内容同样为“正在确认”，并带有 Check again 按钮；Barion 确认付款后，回调会立即创建订单。
如果付款未完成（已取消、已过期或失败），不会创建订单，购物车会被保留，顾客会返回结账页面，并显示：付款未完成。请重试。顾客可以重试。每次尝试都会被记录，因此较早尝试的迟到付款仍会创建订单，而已过期的较早尝试不会取消较新尝试的订单。
如果无法发起付款，顾客会留在结账页面，并看到简短提示：无法发起 Barion 付款。请重试或选择其他付款方式。、Barion 不支持以该币种付款（购物车币种），或 Barion 无法处理总额为零的订单。在 Logging 开启时，详细信息会写入日志。
即使店铺处于维护模式，回调仍然有效，并且不受店铺国家限制的影响。
模块仅支持即时付款。不支持预留或延迟扣款付款、订阅或定期付款、保存的银行卡、Barion Pixel 或额外的 3-D Secure 数据；3-D Secure 由 Barion 在其付款页面上处理。
订单和退款
订单状态
No order yet：顾客已被转到 Barion 但尚未付款，或 Barion 尚未确认付款。此时只存在购物车。
Awaiting Barion payment：Barion 报告付款仍在处理中。备注中显示 Barion PaymentId、金额，以及在测试模式下的 (test mode)。Barion 确认付款后，订单会变为“付款已接受”。
Payment accepted or Delivered：Barion 已确认付款。状态遵循 Order Status After Payment。付款会记录 Barion 交易 ID，备注中显示金额、PaymentId 和交易。
Barion payment on hold：Barion 报告的金额或币种与订单总额不一致，例如付款发起后购物车被修改。备注中显示两个金额。请在 Barion 门户中核对付款，然后处理订单，或在 Barion 门户中退款。
Canceled：待处理订单的最近一次付款尝试在 Barion 被取消或已过期。
Payment error：待处理订单的最近一次付款尝试失败。
Refunded：付款已通过模块全额退款。
如果订单在被取消或失败之后，该订单的某笔付款仍然成功，订单会变为已付款。已付款或已退款的订单绝不会被之后的回调更改。如果已付款订单又有另一笔付款成功，备注会提醒您在 Barion 门户中核对，若为重复付款则予以退款。备注是订单页面上的私人消息。
Barion 付款区块
订单页面会显示一个 Barion payment 区块，其中包括 PaymentId、Barion 交易、付款状态、已付和已退金额、测试付款的 Test mode 标记以及退款记录。
退款
在 Barion payment 区块中输入金额（未退款的金额会自动填入），可选填原因，然后点击 Refund via Barion。确认提示 通过 Barion 退还此金额？此操作无法撤销。支持全额和部分退款。您需要有编辑订单的权限。原因会作为备注发送给 Barion。HUF 退款必须为整数金额。退款会通过付款时所用的模式（测试或正式）发送，因此该模式的 POSKey 必须已设置。如果 Barion 未接受或未确认退款，区块会显示错误，且不会记录退款。成功的退款会添加到退款记录和备注中，并附上 Barion 交易和状态。全额退款会将订单设为 Refunded。部分退款不会更改状态。
只有在 Barion 确认付款且订单由其付款后，才能进行退款。金额或币种不一致的付款无法从 PrestaShop 退款，请在 Barion 门户中退款。模块不会创建退款凭单，订单页面上标准的 PrestaShop 退款按钮也不会通过 Barion 退还款项。
许可证密钥
该模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。位于 Modules > Module Manager > VibeFox Barion Gateway > Configure 页面顶部、设置上方的第一个区块是许可证区块 License — VibeFox Barion Gateway。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏部分字符的形式显示密钥，并显示状态（例如许可证有效期至的日期以及您的域名），还有以下按钮：Check now（再次检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺中移除该密钥）。其下方是 Product: presta-payment-barion 这一行，以及用于打开您 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Barion。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时对其进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可以正常进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 Barion：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式是否已设置 POSKey 和收款人电子邮件（如果缺少，设置页面会显示警告），以及购物车币种是否为 HUF、EUR、USD 或 CZK。在 Payment > Preferences 中，检查该模块是否允许用于购物车币种、顾客所在国家和顾客所属的客户组。
付款已成功，但未创建订单：订单会在 Barion 调用回调 URL 或顾客返回您的店铺时创建。请确保网站可从互联网访问（回调 URL 前面不能有防火墙或基本身份验证）。请检查付款时所用模式的 POSKey 是否正确，因为模块会使用它向 Barion 查询付款状态。开启 Logging 即可查看回调。
回调返回 Busy, retry：订单正好在顾客返回时被处理，或者订单无法创建（例如模块已被禁用）。Barion 会再次调用。开启 Logging 即可查看原因。
回调返回 API error：店铺无法从 Barion 读取付款状态，或者付款时所用模式的 POSKey 未设置。请检查该 POSKey。
回调返回 Order not found：该 PaymentId 并非由本店铺发起。针对其他店铺或测试系统的 Barion 调用会被忽略。
顾客看到“付款验证失败”：返回链接与购物车不匹配，例如它在另一个浏览器会话中打开或被修改过。付款状态仍会由回调确认。
顾客在选择 Barion 时看到错误：开启 Logging，并查看模块页面上的 Log 字段。错误的 POSKey 或收款人电子邮件会导致 无法发起 Barion 付款。
订单处于 Barion payment on hold：阅读订单上的金额不一致备注，在 Barion 门户中核对付款，然后处理订单或在 Barion 门户中退款。
为什么无法退款 10.50 HUF？：Barion 对 HUF 不使用小数。请输入整数金额。
退款提示该订单模式的 Barion POSKey 未配置：付款是在测试或正式模式下完成的，而该模式的 POSKey 为空。请输入后重试。
卸载
前往 Modules > Module Manager，打开 VibeFox Barion Gateway 旁边的菜单，然后选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 Barion 付款数据以及 Awaiting Barion payment 和 Barion payment on hold 订单状态始终保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Barion 是其各自所有者的商标。本模块与 Barion 没有关联，也未获得 Barion 的认可。