VibeFox Paysera for PrestaShop — 帮助

要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝安装在更早的 PHP 版本上。

Paysera 项目：您需要 Paysera 项目的项目 ID 和项目密码（sign key）。客户看到的付款方式就是此项目中启用的付款方式。回调无需在 Paysera 中进行任何设置：其 URL 会随每个付款请求一起发送。

可访问的商店：订单由 Paysera 回调创建，因此您的商店必须可以从互联网访问，不能位于登录页面、基本身份验证或防火墙之后。即使商店处于维护模式，回调仍可正常工作。

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

安装

1. 在后台进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Paysera Payment，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。

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

5. 可选：在 Paysera 项目中启用 Allow test payments，并在模块中启用 Test payments，以便在不扣款的情况下测试流程。开始销售前请将其关闭。

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

安装时，模块会创建两个订单状态：Awaiting Paysera payment 和 Paysera payment on hold。PrestaShop 会为所有货币、国家和客户组提供新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都在模块页面上：Modules > Module Manager > VibeFox Paysera Payment > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，当缺少其中任一项时，页面会显示 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.。

Paysera

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

Title：客户在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Paysera。必填。

Description：结账时显示在付款方式下方的文字。默认：Pay securely via Paysera。

Paysera 项目

项目 ID 和项目密码可在您的 Paysera 账户中找到：进入 Projects and activities，选择您的项目，然后进入 General project settings。

Callback URL：Paysera 用于确认每笔付款的地址。使用友好 URL 时，它的形式为 https://your-shop/module/wcp_paysera_payment/callback，可能包含语言代码。它会随每笔付款自动发送，因此无需在 Paysera 中进行任何设置，但该地址必须可以从互联网访问。订单只会由这些已签名的回调创建。

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

Project password：项目密码（sign key）。它用于签名付款请求并验证 Paysera 回调。已保存的密码不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved password：勾选 Project password，然后点击 Save，即可删除已保存的密码。字段为空时将保留已保存的值。

测试

Test payments：以测试模式发送付款，因此不会扣款。Paysera 会返回一笔成功的测试付款，且不会向客户收费。请先在 Paysera 项目设置中启用 Allow test payments。此选项开启时，测试付款会将订单标记为已付款；关闭时，测试付款会使订单进入保留状态。默认：off。开启时，客户会在付款方式下方看到 TEST MODE — no money will be charged.

Environment：客户被转到的环境。普通的 Paysera 项目（包括测试付款）请保持 Production。默认：Production。

高级

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

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

Delete data：开启时，卸载模块会删除模块设置和日志。订单数据（订单、Paysera 付款记录、订单状态）始终保留。默认：off。

结账

在付款步骤中，客户选择付款方式（默认为 Paysera）并确认订单。模块会创建一个已签名的付款请求，其中包括按购物车货币的最小单位计算的购物车总额、客户的姓名、电子邮件和账单地址，以及商店页面的语言（立陶宛语、拉脱维亚语、爱沙尼亚语、俄语、德语、波兰语，其他情况为英语）。客户会被转到 Paysera 付款窗口，并在那里选择银行、卡片或其他方式。此时尚不存在订单。

Paysera 通过服务器对服务器的回调确认付款。只有在 Paysera 通过已签名的回调确认后，订单才会被标记为已付款；客户返回商店的动作绝不会创建订单或使订单付款。客户在回调之后返回时，会显示标准的订单确认页面。如果银行已接受付款订单但尚未执行，订单会以 Awaiting Paysera payment 状态创建，页面会显示 Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. 对于处于保留状态的订单，页面会显示 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. 两种情况下购物车都会保留。如果购物车已有订单，新的尝试会直接进入订单确认页面，而不会再次付款。

如果无法发起付款，客户将留在结账页面，并显示 Paysera payments are temporarily unavailable. Please choose another payment method.；若订单总额无效，则显示 This order cannot be paid via Paysera. 原因会写入日志。

商店处于维护模式时回调仍然有效，且不受商店国家限制的影响。

模块不支持在后台退款，也不支持在结账页面选择银行或付款方式，不支持订阅、保存的卡片，以及 Paysera 配送或快递服务。

订单

订单状态

No order yet：客户已被转到 Paysera，但回调尚未到达，或客户已取消。此时只存在购物车。

Payment accepted：Paysera 已确认金额和货币相符的付款。该付款以 Paysera 请求 ID 作为交易 ID 记录，备注中会显示请求和付款方式；测试付款会标记 (TEST — no money charged)。

Awaiting Paysera payment：Paysera 已接受付款订单，但银行尚未执行。Paysera 确认付款后，订单将变为 Payment accepted。

Paysera payment on hold：该付款需要人工审核。已付金额或货币与购物车或订单总额不符；Test payments 关闭时收到了 TEST 付款（未扣款）；或者付款是在客户取消之后才被确认的。该付款不会被记录。备注会说明原因，Paysera 区块会提示您在 Paysera 账户中核对该付款，然后将订单设为 Payment accepted，或取消订单并在 Paysera 中退款。

Cancelled：对于已取消的订单，之后确认的付款不会更改其状态。备注会提示您恢复订单（设为 Payment accepted）或在 Paysera 中退款。对已取消订单而言，之后的 TEST 付款或金额不符同样只会添加备注。

如果已付款的订单又收到另一笔成功的付款，订单不会被更改，备注会提示您在 Paysera 账户中退还重复的付款。其他 Paysera 状态（付款未执行、需要补充信息）只会添加备注。

Paysera 付款区块

订单页面会显示 Paysera payment 区块，其中包括 Paysera 订单 ID（购物车编号和尝试次数）、Paysera 请求 ID、环境和 TEST payment 标记、付款状态、请求金额和已付金额、付款方式以及模块备注。

退款

不支持在后台退款：Paysera 付款窗口协议没有退款 API。请在您的 Paysera 账户中办理退款。当 Paysera 报告退款时，订单会添加一条包含退款金额的备注，订单状态不会改变。如有需要，请在 PrestaShop 中手动记录该退款。

许可证密钥

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

没有有效密钥时，结账时不会向客户显示 Paysera。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法知道您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡会出现提醒。现有订单不受影响：已经开始的付款仍会通过回调确认。

许可证过期后，模块仍会继续运行，但更新和支持需要续期。在后台工作时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Paysera：请检查许可证是否有效、Enable/Disable 是否已开启，以及 Project ID 和 Project password 是否都已输入。缺少其中任何一项时，设置页面都会显示警告。在 Payment > Preferences 中，检查该模块是否允许用于购物车货币、客户所在国家和客户所属的客户组。

付款已完成，但未创建订单：订单由 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 payments 开启时，TEST 付款才会支付订单。否则，订单会进入保留状态，并附带备注说明未扣款。同时请在 Paysera 项目中启用 Allow test payments。

订单处于 Paysera payment on hold 状态，并附有金额/货币不符的备注：Paysera 确认了一笔金额或货币与购物车总额不符的付款，例如客户开始付款后，购物车在另一个标签页中被修改。请在您的 Paysera 账户中核对该付款，然后接受订单或手动退款。同一订单之后的一笔正确付款会将其标记为已付款。

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

卸载

进入 Modules > Module Manager，打开 VibeFox Paysera Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data 已开启，模块设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Paysera 付款记录以及 Awaiting Paysera payment 和 Paysera payment on hold 订单状态始终会被保留。现有订单会保留其付款备注和交易 ID。

Paysera 是其各自所有者的商标。本模块与 Paysera 无关联，也未获得 Paysera 的认可。