VibeFox Barion for OpenCart — 帮助

要求

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

PHP: 8.0 或更高版本。

Barion 店铺：您需要店铺的 POSKey（密钥）以及接收付款的 Barion 钱包的电子邮件地址。两者均可在 Barion 门户中找到：正式环境为 secure.barion.com，测试环境为 secure.test.barion.com，位于 My stores 和您的店铺下。测试和正式环境的凭据不同。

货币：订单货币必须为 HUF、EUR、USD 或 CZK。对于其他货币，结账时会隐藏该支付方式。

可访问的店铺：Barion 在每次付款后都会调用您的店铺，因此网站必须可以从互联网访问，且前面不能有防火墙或基本身份验证。维护模式不会阻止回调：OpenCart 3 允许支付扩展的请求通过，而在 OpenCart 4 中，扩展会为此添加一个启动动作。

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

安装

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

OpenCart 3

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

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

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

4. 输入测试 POSKey 和测试钱包邮箱，保持 Test Mode 开启，开启 Enable/Disable，然后点击 Save。下一个测试订单。

5. 一切正常后，输入正式环境凭据并关闭 Test Mode。

OpenCart 4

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

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

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

4. 输入许可证密钥和 Barion 凭据，并按 OpenCart 3 的步骤 3 至 5 测试付款。两个版本的设置页面及其字段相同，只有回调 URL 不同（参见 Callback URL）。

每次付款时，回调 URL 都会自动发送给 Barion。无需在 Barion 门户中进行任何配置。新安装时，支付方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Barion Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮可保存整个页面。在设置上方，如果当前模式没有 POSKey 或收款人邮箱（此时支付方式会在结账时隐藏），或者店铺的默认货币不受 Barion 支持，页面会发出警告，并列出受支持的货币。测试模式开启时，页面会显示 Test mode is on: payments go to the Barion sandbox (api.test.barion.com), no real money is charged. 如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 必须为 1 到 128 个字符，Sort Order 必须为整数，Total 必须为 0 或更大的数字。如果任一字段有错误，则不会保存任何内容，页面会指出该字段。

Barion

Enable/Disable: Enable Barion Payment 用于开启或关闭该支付方式。默认：关闭。

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

Description: 顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.

Sort Order: Barion 在结账时支付方式中的位置。留空或输入整数。

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

Total: 订单必须达到的结账总额（以店铺默认货币计）才会提供 Barion。留空则对任何金额都提供 Barion。

Barion 店铺凭据

在 Barion 门户中获取您的 POSKey 和钱包邮箱：secure.barion.com（正式）或 secure.test.barion.com（测试），My stores，您的店铺（门户链接见本节）。测试模式只使用测试凭据，正式模式只使用正式凭据。

Test Mode: 使用下方的测试凭据和 Barion 沙盒（api.test.barion.com）。不会扣除真实款项。默认：开启。关闭后即可接受真实付款。开启时，顾客在 Confirm Order 步骤会看到 Test mode: no real payment is taken.

Test POSKey: 您的店铺在 Barion 测试系统（secure.test.barion.com，My stores）中的密钥（POSKey）。

Test Payee Email: 您的 Barion 测试钱包的邮箱地址，用于接收测试付款。

Live POSKey: 您的店铺在 Barion 正式系统（secure.barion.com，My stores）中的密钥（POSKey）。

Live Payee Email: 您的 Barion 钱包的邮箱地址，用于接收付款。

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

Callback URL: Barion 在每次付款后调用的地址。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_barion_gateway/callback，在 OpenCart 4 中则类似 https://your-store/index.php?route=extension/wcp_barion_gateway/payment/wcp_barion_gateway.callback，由您的 OpenCart 安装的店铺地址生成。每次付款时都会发送给 Barion，因此无需配置。它只需可以从互联网访问即可。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Barion 报告付款后（通过回调或顾客返回；状态始终从 Barion 读取），订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment: 付款成功并经过验证后设置的状态。默认：处理中。

Awaiting Barion Payment Status: 顾客已在 Barion 页面完成操作，但 Barion 仍在处理付款。默认：待付款。

Barion Payment On Hold Status: 付款已完成，但金额或货币与订单不符。备注会说明原因；请手动检查该付款。默认：待付款，因为 OpenCart 没有保留状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Payment Failed Status: 等待付款的订单，其 Barion 付款失败。默认：失败。

Payment Canceled Status: 等待付款的订单，其 Barion 付款已取消或过期。默认：已取消。

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

高级

Logging: 将 Barion 请求和回调写入 OpenCart 日志文件夹（storage/logs）中的 barion_p_debug.log.php。该文件无法通过网页打开。密钥和钱包邮箱不会被记录。默认：关闭。关闭时不会写入任何内容，包括错误。

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

Delete Data on Uninstall: 开启时，卸载扩展会删除网关设置和日志。订单及其 Barion 付款数据始终保留。默认：关闭。

导入 / 导出

Export: Download JSON 将设置保存为 JSON 文件。POSKey 不会被导出。

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

结账

在 Payment Method 步骤，顾客选择支付方式（默认为 Barion）。在 Confirm Order 步骤，顾客会看到您的描述以及备注 You will be redirected to the secure Barion payment page. OpenCart 在此步骤创建订单，仍无状态。当顾客点击 Confirm Order 时，扩展会以订单货币为订单总额发起 Barion 付款，并将顾客转到 Barion 付款页面。商品、运费、其他订单费用和税费会列在付款信息中；OpenCart 订单号作为订单号传递，顾客的邮箱作为提示传递；如果 Barion 支持，付款页面语言会跟随顾客的语言（匈牙利语、德语、法语、西班牙语、捷克语、斯洛伐克语、斯洛文尼亚语、希腊语，其他情况为英语）。在 OpenCart 4 中，顾客通过支付方式区块的 Choose 按钮，在 Payment method options 窗口中选择支付方式，并点击结账页面底部的 Confirm Order。

付款后，顾客会返回您的店铺，Barion 也会调用回调 URL。这两个请求本身都不会将任何内容标记为已付款：扩展会使用发起付款时所用模式的 POSKey 向 Barion 查询付款状态。只有在 Barion 确认后，并且金额和货币与订单一致时，订单才会被标记为已付款。返回链接包含付款尝试的随机令牌，并且只检查为该订单发起的付款。之后，订单会以标准的 OpenCart 方式获得状态，并发送常规的订单邮件，同时更新库存。在 OpenCart 4 中，Barion 将顾客送回时浏览器不会发送店铺会话，因此扩展会先显示一个短暂的页面，由店铺重新打开同一返回地址：顾客会保留购物车和登录状态。

如果付款成功，顾客会看到 OpenCart 订单成功页面。如果 Barion 中付款仍在处理，订单会获得 Awaiting Barion Payment Status 状态，成功页面会显示 Your payment is being confirmed by Barion. You will receive an e-mail as soon as it is confirmed. 如果顾客返回时无法连接 Barion，或者付款已完成但尚未应用，则会显示 Payment confirmation 页面，其中包含相同的文字和 Check again 按钮；一旦 Barion 确认付款，回调就会设置订单状态。

如果付款未完成（已取消、已过期或失败），订单将保持无状态，购物车会被保留，顾客会返回结账页面，并显示 Payment was not completed. Please try again. 如果返回链接与订单不匹配，则显示 Payment verification failed. 在 OpenCart 4 中，这些消息会显示在结账页面上方。在 OpenCart 3 中，每次新的尝试都会创建一个新的 OpenCart 订单；OpenCart 4 则在结账期间保留一个订单并更新它，因此新的尝试是同一订单的新 Barion 付款。Barion 无法取消已发起的付款，因此在新的付款之前，扩展会在 Barion 中检查该购物车之前未结的付款：如果其中某笔已付款或仍在处理中，则确认其订单，顾客会直接进入成功页面，无需再次付款。如果同一购物车（同一次访问中的相同商品）的另一笔订单已付款，顾客同样会直接进入成功页面，无需新的付款；完成一次购买后的新购买即为新的购物车。同一订单之前某次尝试的延迟付款仍会确认该订单，而过期的早期尝试不会取消订单。如果顾客为同一购物车支付了两个订单（两个标签页），第二笔付款不会确认其订单：已付款的订单会收到备注，说明已收到同一购物车的第二笔付款，以便您在 Barion 门户中退款。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单期间未付款就已被关闭（例如其待付款在 Barion 中被取消，或您取消了订单），下一次点击 Confirm Order 会将顾客送回结账页面，并显示 Payment was not completed. Please try again.，然后结账流程会根据购物车创建一个新订单。如果该订单已有状态，且购物车此后有所变动（其他商品或数量），则订单会退出结账流程，变动后的购物车会获得新订单及其自己的付款。

如果无法发起付款，顾客会停留在 Confirm Order 步骤，按钮上方会显示简短提示：The Barion payment could not be started. Please try again or choose another payment method.、Barion does not support payments in 订单货币、Barion payment is not available at the moment. Please choose another payment method. 或 Barion cannot process an order with a zero total. 当 Logging 开启时，详细信息会写入日志。

该扩展仅支持即时付款。它不支持预授权或延迟捕获付款、订阅或定期付款、已保存的银行卡、Barion Pixel 或额外的 3-D Secure 数据；3-D Secure 由 Barion 在其付款页面上处理。

订单与退款

订单状态

无状态（缺失订单）：顾客已被转到 Barion，但尚未付款，付款未完成，或 Barion 尚未确认付款。在 Sales > Orders 中，只有将 Order Status 筛选条件设为 Missing Orders，才会显示此类订单。

Awaiting Barion Payment Status（默认 Pending）：Barion 报告付款仍在处理中。备注会显示 Barion PaymentId、金额，以及在测试模式下的 (test mode)。当 Barion 确认付款后，订单会转为已付款状态。

Order Status After Payment（默认 Processing）：Barion 已确认付款。备注会显示金额、PaymentId 和 Barion 交易。

Barion Payment On Hold Status（默认 Pending）：Barion 报告的金额或货币与订单总额不同。备注会同时显示两个金额。请在 Barion 门户中检查该付款，然后处理订单或在 Barion 门户中退款。

Payment Canceled Status（默认 Canceled）：等待付款订单的最近一次付款尝试已在 Barion 中被取消或过期。

Payment Failed Status（默认 Failed）：等待付款订单的最近一次付款尝试失败。

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

如果订单在被取消或失败后，其某笔付款仍然成功，订单将变为已付款。已付款或已退款的订单不会因后续回调而改变。如果已付款的订单又有另一笔付款成功，备注会提醒您在 Barion 门户中检查，如果是重复付款则予以退款。备注是订单 History 中的条目，顾客看不到。

VibeFox Barion Gateway 标签页

在 Sales > Orders 中打开一个通过 Barion 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Barion Gateway 标签页会显示 PaymentId（测试付款会附带 Test mode 标签）、Barion Transaction、付款 Status、Paid / refunded 金额、退款表单、退款记录以及该订单的 Barion notes。该标签页显示给有权访问该扩展的用户。

退款

在 VibeFox Barion Gateway 标签页中输入金额（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Barion。确认提示 Refund this amount through Barion? This cannot be undone. 全额和部分退款均受支持。您需要修改该扩展的权限（在 System > Users > User Groups 中设置）。退款原因会作为备注发送给 Barion。HUF 退款必须为整数金额。退款会以付款时所用的模式（测试或正式）发送，因此该模式的 POSKey 必须已设置。如果 Barion 未接受或未确认退款，标签页会显示错误，且不会记录退款。成功的退款会连同 Barion 交易和状态一起添加到退款记录和备注中。全额退款会将订单设为 Refunded Status，且不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。

一旦 Barion 确认付款且订单已通过它付款，即可进行退款。金额或货币不一致的付款无法从 OpenCart 退款；请在 Barion 门户中退款。Sales > Returns 中的商品退货不会通过 Barion 退回款项。

许可证密钥

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

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

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

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

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

故障排除

结账时没有显示 Barion：请检查许可证是否有效，Enable/Disable 是否已开启，当前模式是否有 POSKey 和收款人邮箱（设置页面会在缺少时显示警告），以及订单货币是否为 HUF、EUR、USD 或 CZK。另外，请检查付款地址是否位于所选的 Geo Zone 内，以及订单金额是否达到设置中的 Total。

付款已完成，但订单仍无状态：订单会在 Barion 调用回调 URL 或顾客返回您的店铺时获得状态。请确保网站可从互联网访问（回调 URL 前面不能有防火墙或基本身份验证）。请检查付款时所用模式的 POSKey 是否正确，因为扩展会用它向 Barion 查询付款状态。开启 Logging 以查看回调。

回调返回 Busy, retry：订单恰好在顾客返回时正在处理，或无法设置订单状态。Barion 会再次调用。开启 Logging 查看原因。

回调返回 API error：店铺无法从 Barion 读取付款状态，或付款时所用模式的 POSKey 未设置。请检查该 POSKey。

回调返回 Order not found：该 PaymentId 并非由本店铺发起。针对其他店铺或测试系统的 Barion 调用会被忽略。

顾客看到 Payment verification failed.：返回链接与订单不匹配，例如被修改过。付款状态仍会通过回调确认。

顾客在 Confirm Order 后看到错误：开启 Logging，并查看扩展页面上的 Log 字段。错误的 POSKey 或收款人邮箱会导致 The Barion payment could not be started. This payment method is not available. Please reload the checkout page. 表示结账会话已与订单不再匹配，或支付方式已在此期间被关闭：顾客需要重新加载结账页面。

订单处于保留状态：请阅读 VibeFox Barion Gateway 标签页中的差异备注，在 Barion 门户中检查付款，然后处理订单或在 Barion 门户中退款。

为什么无法退款 10.50 HUF：Barion 处理 HUF 时不使用小数。请输入整数金额。

标签页中没有退款表单：标签页会说明原因：付款尚未确认、已全额退款、您的用户组没有修改扩展的权限，或该付款模式的 POSKey 未设置。

面向开发人员：该扩展会触发 OpenCart 事件 wcp_barion_supported_currencies（货币列表）和 wcp_barion_payment_request（付款请求和订单，在发送给 Barion 之前）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Barion Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装后会恢复为默认值。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除其事件以及在维护模式下放行回调的启动动作）。如果 Delete Data on Uninstall 开启，则其余网关设置（标题、描述、测试模式、POSKey、收款人邮箱、日志记录）和日志会被删除。如果关闭，它们会被保留，以便日后重新安装。Barion 的付款和退款记录始终会被保留，因此之前已付款的订单即使在重新安装后仍可退款。现有订单会保留其付款备注。

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

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