VibeFox Przelewy24 for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
币种：购物车必须使用 PLN、EUR、GBP 或 CZK。使用其他币种时，结账页面会隐藏该付款方式。购物车以其自身币种收费；模块不进行货币转换。
Przelewy24 账户：您需要一个 Przelewy24 商户账户及其 API 数据：Merchant ID、API 密钥（在 Przelewy24 后台称为 report key）、CRC 密钥，以及若您的店铺拥有自己的 ID，则需要 POS ID（Shop ID）。您可以在 Przelewy24 商户后台 panel.przelewy24.pl 中，于 My data > API data and configuration 下找到它们。沙盒密钥来自单独的沙盒账户，位于 sandbox.przelewy24.pl/panel。除此之外，Przelewy24 后台无需进行其他设置：模块会在每次付款时发送其通知 URL。您的店铺必须可从互联网访问，因为 Przelewy24 会向其发送付款通知。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Przelewy24 Payment，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 输入沙盒密钥（Merchant ID、API 密钥、CRC 密钥；仅当 POS ID 与 Merchant ID 不同时才需要输入 POS ID），开启 Enable/Disable，点击 Save，并在沙盒模式下进行一次测试付款。
5. 输入正式密钥，关闭 Test Mode，然后点击 Save，即可接收真实付款。
安装时，模块会创建订单状态 Przelewy24 payment on hold。之后，PrestaShop 会为所有币种、国家和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中对其进行限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Przelewy24 Payment > Configure。每个部分都有各自的 Save 按钮，它会保存整个页面。在字段上方，如有缺失项，页面会显示警告。沙盒开启时：Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. 当当前模式的密钥不完整时：Enter the Sandbox Merchant ID, API key and CRC key - until then Przelewy24 is not shown at checkout.（正式密钥同理）。如果 Przelewy24 不接受您店铺的默认币种，警告会指明该币种以及受支持的币种。保存后，警告会立即跟随新的模式和密钥。从 Przelewy24 后台与密钥一起复制的空格和换行，会在保存时被去除。
Przelewy24
Enable/Disable：Enable Przelewy24 Payment 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Przelewy24。必填：若标题为空即保存，会出现 Enter a title for the payment method.
Description：结账时显示在付款方式下方的文本。默认：Pay with BLIK, online bank transfer or card via Przelewy24。
API 凭据
本部分说明可在何处找到密钥（Przelewy24 商户后台中的 My data > API data and configuration），并提供 panel.przelewy24.pl 和 sandbox.przelewy24.pl/panel 的链接。
Test Mode：使用 Przelewy24 沙盒（sandbox.przelewy24.pl）和沙盒密钥。不会收取真实费用。关闭后，将使用正式密钥在 secure.przelewy24.pl 上接收真实付款。默认：开启。开启期间，顾客会在付款方式下方看到 Sandbox mode - no real money is charged。
正式密钥
Live Merchant ID：您的 Przelewy24 商户 ID，仅限数字。
Live POS ID (optional)：Shop ID（posId）。若与 Merchant ID 相同，请留空。
Live API key (report key)：来自 Przelewy24 后台的 API 密钥。用于 API 身份验证。
Live CRC key：用于对发送给 Przelewy24 的请求进行签名，并验证 Przelewy24 通知的签名。
沙盒密钥
Sandbox Merchant ID：您的 Przelewy24 沙盒账户的 Merchant ID。
Sandbox POS ID (optional)：沙盒账户的 Shop ID（posId）。若与 Merchant ID 相同，请留空。
Sandbox API key (report key)：沙盒账户的 API 密钥。
Sandbox CRC key：沙盒账户的 CRC 密钥，用于对请求进行签名并验证沙盒通知。
已保存的 API 密钥和 CRC 密钥将不再显示。字段保持为空，并显示 Saved - leave empty to keep it. 仅当您想更改时才输入新值。
Clear saved secrets：勾选某个密钥并点击 Save 即可将其删除。空字段会保留已保存的值。
正式密钥与沙盒密钥是不同的。Merchant ID 和 POS ID 只能包含数字；在输入当前模式的 Merchant ID、API 密钥和 CRC 密钥之前，结账页面不会显示该付款方式。在某一模式下发起的付款，即使您切换了模式，也始终使用该模式的密钥进行核实和退款，因此只要旧模式的付款仍未完结或可能需要退款，请保留其密钥。
付款通知
Notification URL：接收 Przelewy24 付款通知的地址。使用友好 URL 时，它类似于 https://your-shop/module/wcp_przelewy24_payment/notify，可能还带有语言代码，例如 /en/。模块会在每次付款和每次退款时将此 URL 发送给 Przelewy24，因此无需在 Przelewy24 后台进行任何设置。该 URL 必须可从互联网访问：其前面不得有防火墙或 HTTP 身份验证。即使店铺处于维护模式，它仍会继续工作，并且不会被店铺的国家限制所阻止。若没有通知，付款仍会在顾客返回店铺时得到确认（见结账）；如果顾客没有返回，则不会创建订单。
高级
Debug Log：将技术事件（购物车编号、P24 交易 ID、错误）写入模块文件夹中的 logs/wc_p24_debug.log.php。该文件无法通过网页打开。错误和警告（例如被拒绝的通知，或验证或退款失败）始终会被记录；打开该开关可同时记录每个步骤。密钥、请求正文和个人数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 即可清空。
Delete data on uninstall：开启后，卸载模块时会删除模块设置和日志。订单及其 Przelewy24 付款数据绝不会被删除。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为带有 P24 标志的 Przelewy24）并确认订单。模块会以购物车币种为购物车总额在 Przelewy24 登记一笔交易，附带顾客的电子邮件、姓名和账单国家，以及包含购物车编号和您店铺名称的说明 Cart #。每次付款尝试都会获得各自的会话 ID。顾客会被转到 Przelewy24 付款页面，使用 BLIK、在线银行转账、银行卡或您的 Przelewy24 账户已启用的其他方式付款。若 Przelewy24 支持，付款页面会以顾客购物车的语言显示，否则显示英语。此时尚不存在订单。
只有在 Przelewy24 确认后，订单才会被标记为已付款。Przelewy24 会向您的店铺发送经签名的通知。模块会用 CRC 密钥、Merchant ID 和 POS ID 检查签名；检查会话是否是为此购物车并在同一模式下登记的；并检查金额和币种是否与付款尝试以及当前购物车总额一致。只有这样，它才会向 Przelewy24 核实交易（Przelewy24 只入账已核实的付款），并以 Payment accepted 状态创建订单。没有有效签名的 webhook 会被拒绝。
付款后，顾客会返回您的店铺。如果通知尚未到达，模块会通过经身份验证的服务器到服务器请求向 Przelewy24 查询交易状态（每个购物车最多每 10 秒一次），并应用相同的检查。仅返回页面绝不会将订单标记为已付款。付款确认后，顾客会看到标准的订单确认页面。在确认之前，Payment confirmation 页面会显示 We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again:，并带有 Check again 按钮和 Pay again 按钮，后者会打开结账页面。购物车会被保留，并且稍后通过同一购物车较旧的 Przelewy24 页面所作的付款仍会被接受。如果订单处于保留状态，确认页面会显示 Your payment is being verified. We will send you an e-mail as soon as it is confirmed.
如果无法发起付款，顾客会停留在结账页面并看到简短提示：Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method.（原因会记入日志）、Payment gateway is not configured properly. Please contact the administrator.（缺少当前模式的密钥）、提示 Przelewy24 无法接受该购物车币种付款的消息，或 The order total must be greater than zero. 已经存在订单的购物车不会再次发送给 Przelewy24；顾客会被引导至订单确认页面。
模块不支持保存的银行卡或一键付款、订阅或定期付款，不允许在结账页面选择 P24 付款方式（例如 BLIK 代码输入框），也不提供分期付款小工具，并且不会将购物车内容发送给 Przelewy24。
订单和退款
订单状态
No order yet：顾客已被转到 Przelewy24 但尚未付款，或付款尚未确认。此时只存在购物车。
Payment accepted：付款已核实。该付款以 P24 订单号作为交易 ID 记录，备注中显示 P24 订单号、金额和模式。每笔付款只会应用一次。
Przelewy24 payment on hold：Przelewy24 报告的金额或币种与购物车不一致（例如，付款开始后购物车被修改）；付款未被确认，备注中会说明。或者付款已到达并针对一个已取消的订单完成了核实；该订单不会被悄悄重新打开，备注会请您发货或为该付款退款。请在 Przelewy24 后台核对该付款。如果在不一致之后，同一订单的另一次尝试稍后才到达正确的付款，订单将变为 Payment accepted。
Refunded：该付款已通过模块全额退款。
如果针对订单已付款或已退款的购物车又到达了第二笔付款（旧的付款链接、两个浏览器标签页），它不会被确认，因此 Przelewy24 不会入账。订单上的备注会要求您在 Przelewy24 后台核对，并在需要时将款项退还给买家。
Przelewy24 付款区块
订单页面会显示 Przelewy24 payment 区块，其中包括 P24 订单号、会话、环境（沙盒付款显示 Sandbox 标记）、付款状态及验证方式（通知或返回）、已付和已退金额、退款表单、退款记录以及订单的 Payment notes。
退款
在 Przelewy24 payment 区块中输入金额（尚未退款的金额会自动填入），可选填原因，然后点击 Refund via Przelewy24。确认提示 Refund this amount through Przelewy24? This cannot be undone.。支持全额和部分退款，但不得超过尚未退款的金额。您需要拥有编辑订单的权限；无需访问模块页面。退款会以付款时所在的模式（沙盒或正式）发送，因此必须已设置该模式的密钥。只有在 Przelewy24 核实付款之后，才能进行退款。
Przelewy24 以异步方式处理退款。区块会显示 Refund of … requested at Przelewy24. The result will be added as an order note.，退款记录显示状态 requested，并添加一条备注。结果稍后会到达通知 URL：状态变为 completed 并附带备注 Przelewy24: refund of … completed.，或变为 rejected 并附带备注，说明款项未退还给买家。全额退款会在请求时将订单设为 Refunded；部分退款不会改变状态。如果退款被拒绝，请在 Przelewy24 后台核对；订单状态不会自动恢复。
如果 Przelewy24 不接受退款请求，区块会显示 Przelewy24 refund failed: 及原因，并且不会记录任何退款。模块不会创建退款凭证（credit slip）。订单页面上标准的 PrestaShop 退款按钮不会通过 Przelewy24 退回款项，直接在 Przelewy24 后台进行的退款也不会添加到订单中。
许可证密钥
模块需要在 vibefox.net 获取的 VibeFox 许可证密钥才能运行。License — VibeFox Przelewy24 Payment 许可证区块是 Modules > Module Manager > VibeFox Przelewy24 Payment > Configure 页面中位于设置上方的第一个区块。请在 License key 中输入密钥，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期至何时以及您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: presta-payment-przelewy24 一行，以及打开您 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 账户中释放该名额。
没有有效密钥时，结账页面不会向顾客显示 Przelewy24。若仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法知道您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账页面进行测试。Modules > Module Manager 中的 Alerts 标签页会显示提醒。现有订单不受影响：已发起的付款仍会被核实和确认，退款也仍然可用。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您于后台工作时，状态会自动重新检查：密钥输入后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，总会移除许可证密钥和许可证状态。
故障排除
结账页面中没有 Przelewy24：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 Merchant ID、API 密钥和 CRC 密钥是否已输入（Test Mode 开启时使用沙盒密钥，否则使用正式密钥；Merchant ID 和 POS ID 只能为数字），以及购物车币种是否为 PLN、EUR、GBP 或 CZK。设置顶部的警告会指出问题所在。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家以及顾客所属群组。开发人员可以使用 actionWcpPrzelewy24SupportedCurrencies 钩子更改币种列表（仅限为您的 Przelewy24 账户启用了两位小数的币种）。
付款已完成，但没有创建订单：Przelewy24 的通知没有到达您的店铺，并且顾客也没有返回店铺。请检查 Notification URL 是否可从互联网访问（其前面没有防火墙或 HTTP 身份验证），以及该付款所属模式的 Merchant ID、POS ID 和 CRC 密钥是否正确。即使 Debug Log 关闭，被拒绝的通知仍会写入日志；请查看模块页面上的 Log 字段。
店铺如何响应通知：已处理、重复或未知的通知会收到 HTTP 200 响应。否则，Przelewy24 会稍后重新发送：400（数据缺失或格式错误）、401 Invalid signature（CRC 密钥错误，Merchant ID 或 POS ID 不匹配）、401 Invalid signature for this payment（通知使用的密钥与付款所在模式不同）、405（不是 POST 请求）、500 Verification failed（与 Przelewy24 的核实失败；若订单存在，会向订单添加一条备注，且仅添加一次）、500 Order could not be created（例如模块已禁用；下一个通知会在无需再次核实的情况下创建订单）以及 503 Busy, retry later（购物车正被另一请求同时确认）。
顾客看到 Payment error: Przelewy24 could not start the payment:Przelewy24 拒绝了该交易，通常是因为当前模式的密钥有误（沙盒密钥仅适用于沙盒模式，正式密钥仅适用于正式模式）。Przelewy24 返回的错误记录在日志中。
付款后订单处于 Przelewy24 payment on hold：请阅读 Przelewy24 payment 区块中的备注。金额或币种与购物车不同，或付款是针对一个已取消的订单到达的。请在 Przelewy24 后台核对该付款，然后处理订单或为付款退款。
退款失败：This order has no verified Przelewy24 payment. Cannot process refund. 表示该订单并非通过已核实的 Przelewy24 付款支付的。The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing.（或正式模式的相同提示）表示该付款所属模式的密钥已被删除；请重新输入。Invalid refund amount 表示金额为空、不是数字，或超过了尚未退款的金额。
卸载
进入 Modules > Module Manager，打开 VibeFox Przelewy24 Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块设置和日志将被删除。如果已关闭，则所有设置都会保留，以便之后重新安装。订单的 Przelewy24 付款数据（会话、P24 订单号、退款）和订单状态 Przelewy24 payment on hold 始终会保留，因此之前已付款的订单即使在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Przelewy24 是其各自所有者的商标。本模块与 Przelewy24 无关联，也未获得 Przelewy24 的认可。