VibeFox Paysera for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

Paysera 项目：您需要 Paysera 项目的项目 ID 和项目密码（签名密钥）。顾客看到的付款方式是在该项目中启用的方式。无需在 Paysera 中为回调进行任何配置：其 URL 会随每个付款请求一起发送。

可访问的店铺：订单的状态来自 Paysera 回调，因此您的店铺必须能从互联网访问，不能位于登录、基本认证或防火墙之后。即使店铺处于维护模式，回调仍然有效。

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

安装

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

OpenCart 3

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

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

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

4. 输入您 Paysera 账户中的 Project ID 和 Project password（参见配置）。

5. 可选：在 Paysera 项目中启用 Allow test payments，并在扩展中启用 Test payments，即可在不扣款的情况下测试整个流程。开始销售前请关闭。

6. 开启 Enable/Disable，然后点击 Save。

OpenCart 4

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

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

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

4. 请按 OpenCart 3 的步骤 3 至 6 输入许可证密钥、项目 ID 和密码以及测试设置。两个版本的设置页面及其字段相同。只有回调 URL 不同（参见 Paysera 项目）。

新安装时，付款方式默认关闭，测试付款默认关闭，环境默认为 Production。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果缺少 Project ID 或 Project password 中的任何一个，页面会显示 Paysera is hidden at checkout until the project ID and the project password are entered.；当测试付款或沙盒开启时，页面会显示 Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. 若没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 必须为 1 至 128 个字符，Project ID 只能包含数字，Sort Order 必须为整数，Total 必须为 0 或更大的数字，且订单状态必须存在。如果任何检查未通过，则不会保存任何内容，页面会列出错误。

Paysera

Enable/Disable：Enable Paysera Payment 用于开启或关闭该付款方式。默认：关闭。

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

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely via Paysera。

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

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

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

Paysera 项目

您可以在 Paysera 账户中，依次进入 Projects and activities、您的项目、General project settings，找到项目 ID 和项目密码。该部分包含 Paysera 账户的链接。

Callback URL：Paysera 用于确认每笔付款的地址。OpenCart 3 中的格式类似 https://your-store/index.php?route=extension/payment/wcp_paysera_payment/callback，OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_paysera_payment/payment/wcp_paysera_payment.callback，根据您 OpenCart 安装的店铺地址生成。它会随每笔付款自动发送，因此无需在 Paysera 中进行任何设置，但它必须能从互联网访问。订单只会从这些已签名或已加密的回调中获得状态。

Project ID：您的 Paysera 项目的数字 ID。只接受数字：输入任何其他值都会显示错误 Project ID must contain digits only: the numeric ID of your Paysera project.，且不会保存任何内容。

Project password：项目密码（签名密钥）。它用于签名付款请求并验证 Paysera 回调。已保存的密码不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的密码，请勾选字段下方的 Clear saved password (tick and save; an empty field keeps the saved value)，然后点击 Save。

测试

Test payments：以测试模式发送付款，因此不会扣除任何款项。Paysera 会返回一笔成功的测试付款，但不会向顾客扣款。请先在 Paysera 项目设置中启用 Allow test payments。该选项开启时，测试付款会将订单标记为已付款；关闭时，测试付款会使订单进入 On hold 状态。默认：关闭。开启时，顾客在 Confirm Order 步骤会看到 TEST MODE — no money will be charged.

Environment：顾客被引导至的环境。普通的 Paysera 项目请保持 Production，测试付款也是如此。默认：Production。

订单

OpenCart 在 Confirm Order 步骤创建订单时不带状态（即缺失订单）。订单只有在收到 Paysera 回调后才会获得状态。被取消或未执行的付款会使订单保持无状态，顾客可以再次付款。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：Paysera 以预期的金额和货币确认付款后设置的状态。默认：Processing。

Awaiting Payment Status：银行已接受付款指令，但尚未执行。Paysera 确认付款后，订单会被标记为已付款。默认：Pending。

On Hold Status：在 Test payments 关闭时收到的 TEST 付款、金额或货币不符，或顾客取消后的付款。订单不会被标记为已付款；备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Order Status：扩展从不设置此状态，只会读取它：对于处于此状态的订单，收到的付款不会重新打开订单，只会添加一条备注。默认：Canceled。

高级

Debug log：将付款事件写入 OpenCart 日志文件夹（storage/logs）中的 wc_psr_debug.log.php。该文件无法通过网页打开。错误和警告始终会被写入；其他步骤仅在此选项开启时写入。密码和顾客数据绝不会被写入。默认：关闭。

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

Delete data：开启后，卸载扩展时会删除扩展设置和日志。订单数据（订单、Paysera 付款记录）始终保留。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。项目密码不会被导出。

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Paysera）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to the Paysera payment window (bank links, cards and other Paysera methods) to complete the payment. OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过 Payment method options 窗口中付款方式区块的 Choose 按钮选择付款方式，并在结账页面底部点击 Confirm Order。当顾客点击 Confirm Order 时，扩展会创建一个已签名的付款请求，其中包含订单号、以订单货币最小单位表示的订单总额、顾客的姓名、电子邮件和账单地址，以及店铺页面的语言（立陶宛语、拉脱维亚语、爱沙尼亚语、俄语、德语、波兰语，其他情况下为英语）。顾客被转到 Paysera 付款窗口，并在那里选择银行、银行卡或其他方式。

Paysera 通过服务器对服务器的回调确认付款。只有当 Paysera 通过已签名的回调确认付款后，订单才会被标记为已付款；顾客返回店铺绝不会为订单付款。然后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。顾客在回调之后返回时，会看到 OpenCart 的订单成功页面。如果银行已接受付款指令但尚未执行，订单会获得 Awaiting Payment Status，页面会显示 Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. 对于处于 On hold 状态的订单，页面会显示 Your payment is being reviewed. We will contact you if anything else is needed.

如果顾客在回调之前返回，会出现一个 Payment confirmation 页面，说明订单会在 Paysera 确认付款后立即得到确认，并提供 Check again 和 Back to checkout 按钮。

如果顾客在 Paysera 窗口中取消，将返回结账页面，并显示 The Paysera payment was cancelled. You can try again or choose another payment method. 如果 Paysera 报告付款未执行，则显示 The payment was not completed. You can try again or choose another payment method. 两种情况下购物车都会保留。在 OpenCart 4 中，这些消息显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，而 OpenCart 4 会更新结账中的订单（新的尝试会支付同一订单）；如果同一购物车的另一个订单已付款、待付款或处于 On hold 状态，新的尝试会直接进入成功页面，而不会产生第二笔付款。购物车的任何变化（包括数量变化）都视为需要单独付款的新购物车。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在此期间已被关闭（例如您取消了一个等待银行付款的订单），顾客会被带回结账页面，并显示 Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. 下一次 Confirm Order 会为新订单付款。如果该订单此前已为旧购物车付款，且购物车之后发生了变化，顾客会被带回结账页面，下一次 Confirm Order 会为当前购物车的新订单付款。已关闭的订单绝不会显示为已付款。

如果无法发起付款，顾客会停留在 Confirm Order 步骤，并显示 Paysera payments are temporarily unavailable. Please choose another payment method.；如果订单总额无效，则显示 This order cannot be paid via Paysera. 原因会写入日志。

即使店铺处于维护模式，回调仍然有效，因为 OpenCart 允许付款扩展的请求通过（在 OpenCart 4 中，扩展为此添加了自己的启动操作，该操作同时也允许顾客从 Paysera 返回）。

本扩展不支持从管理后台退款，不支持在结账页面选择银行或付款方式，不支持订阅、保存卡以及 Paysera 配送或快递服务。

订单

订单状态

无状态（缺失订单）：顾客已被转到 Paysera，但回调尚未到达；或顾客已取消；或付款未执行。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时才会显示此类订单。

Order Status After Payment（默认 Processing）：Paysera 已以匹配的金额和货币确认付款。备注中会显示请求和付款方式；测试付款会标注为 (TEST — no money charged)。

Awaiting Payment Status（默认 Pending）：Paysera 已接受付款指令，但银行尚未执行。Paysera 确认付款后，订单会转为 Order Status After Payment。

On Hold Status（默认 Pending）：付款需要人工审核。付款的金额或货币与订单总额不符；Test payments 关闭时收到了 TEST 付款（未收取任何款项）；或顾客取消后付款被确认。备注会说明情况，订单选项卡会提示您在 Paysera 账户中核对付款，然后将订单设为已付款状态，或取消订单并在 Paysera 中退款。之后对同一订单收到的正确付款会将其标记为已付款。

Cancelled Order Status（默认 Canceled）：对已取消订单的后续付款确认不会更改其状态。备注会要求您恢复订单（将其设为已付款状态），或在 Paysera 中退款。如果订单的付款方式已不再是 Paysera，确认的付款只会添加一条备注。

如果已付款订单，或已付款购物车中的另一个订单又收到了一笔成功付款，已付款订单不会被更改，并且备注会要求您在 Paysera 账户中退还重复付款。其他 Paysera 状态（付款未执行、附加信息）只会添加备注。备注是订单 History 中的条目，顾客看不到。

VibeFox Paysera Payment 选项卡

在 Sales > Orders 中打开一笔通过 Paysera 付款的订单。在订单页面底部、History 和 Additional 旁边，VibeFox Paysera Payment 选项卡会显示 Paysera order ID（订单号和尝试次数）、Paysera request ID、Environment 以及 TEST payment 标记、付款的 Status、Requested / paid 金额、Payment method 和扩展的 Notes。对于处于 On hold 状态的订单，它会显示需要核对的内容。该选项卡仅显示信息，并且只显示给有权访问本扩展的用户。

退款

不支持从管理后台退款：Paysera 付款窗口协议没有退款 API。请在您的 Paysera 账户中办理退款。当 Paysera 报告退款时，订单会添加一条含退款金额的备注，订单状态不会改变。如有需要，请在 OpenCart 中手动记录退款。Sales > Returns 中的商品退货不会通过 Paysera 退还款项。

许可证密钥

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

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

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

故障排除

结账时未显示 Paysera：请检查许可证是否有效、Enable/Disable 是否开启，以及 Project ID 和 Project password 是否都已填写。只要缺少其中任何一项，设置页面就会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：订单的状态来自 Paysera 回调，而不是顾客的返回。请检查设置中显示的 Callback URL 是否可从互联网访问（不能位于登录、基本认证或防火墙之后），并查看扩展页面上的 Log 字段。

回调返回 Invalid signature：Project password 与项目不匹配，或回调并非来自 Paysera。请重新复制项目密码。如果您更改了项目或密码，则更改之前发起的付款将无法再被验证。

回调返回 Project ID mismatch：设置中的 Project ID 与完成付款的项目不同。

回调返回 Order not found：回调中的订单在本店铺中没有 Paysera 付款，例如付款是在另一家使用同一项目的店铺中发起的。

回调返回 Gateway not configured、Busy 或 Temporary error：项目 ID 或密码为空，同一购物车的另一个回调仍在处理中，或无法设置订单状态。Paysera 会重试回调。开启 Debug log 可查看原因。

Paysera 拒绝付款窗口，或提示项目不存在：请检查 Environment。普通的 Paysera 项目只能使用 Production；Sandbox 需要在 Paysera 沙盒环境中创建的项目。

测试付款没有为订单付款：TEST 付款只有在 Test payments 开启时才会为订单付款。否则，订单会被置于 On hold 状态，并附带备注说明没有收取任何款项。另外请在 Paysera 项目中启用 Allow test payments。

订单处于 On hold 状态，备注提示金额或货币不符：Paysera 确认了一笔金额或货币与订单总额不符的付款。请在 Paysera 账户中核对该付款，然后接受订单或手动退款。

顾客看到 Paysera payments are temporarily unavailable：请查看 Log 字段。项目 ID 或密码可能为空，或发送给 Paysera 的某个店铺地址超过了 255 个字符。

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

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Paysera Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除其事件以及在维护模式下允许回调和顾客返回的启动操作）。如果 Delete data 已开启，其他设置（标题、描述、项目 ID 和密码、测试、日志）和日志都会被删除。如果已关闭，它们会被保留，以便日后重新安装时使用。Paysera 付款记录始终会被保留。现有订单会保留其付款备注。

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

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