VibeFox Przelewy24 for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法启用。
PHP：8.0 或更高版本。
币种：订单必须使用 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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_przelewy24_payment 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Przelewy24 > Manage，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入沙盒密钥（Merchant ID、API key、CRC key；仅当 POS ID 与 Merchant ID 不同时才需要 POS ID），开启 Enable/Disable，保存并在沙盒模式下完成一笔测试付款。
6. 输入正式（Live）密钥，取消勾选 Test Mode 并保存，即可接受真实付款。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > Przelewy24。在字段上方，页面会在缺少某项内容时显示警告。沙盒开启时，页面会显示：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 后台与密钥一同复制的空格和换行会在保存时被删除。
结账
Enable/Disable：Enable Przelewy24 Payment 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。默认：Przelewy24。
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：Enable sandbox (test) mode。开启后，新付款会使用沙盒密钥进入 Przelewy24 沙盒（sandbox.przelewy24.pl），且不会扣除真实款项。取消勾选则使用正式密钥在 secure.przelewy24.pl 接受真实付款。默认：开启。
正式密钥
Live Merchant ID：您的 Przelewy24 商户 ID，仅限数字。
Live POS ID (optional)：Shop ID（posId）。若与 Merchant ID 相同，请留空。
Live API key (report key)：来自 Przelewy24 后台的 API 密钥。它与 POS ID 一起用于 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 密钥，用于对请求进行签名并验证沙盒通知。
正式密钥与沙盒密钥不同。Merchant ID 和 POS ID 只能包含数字；在输入当前模式的 Merchant ID、API key 和 CRC key 之前，结账页面不会显示该付款方式。在某一模式下发起的付款，即使之后切换了模式，也始终使用该模式的密钥进行核实和退款，因此只要旧模式的付款仍未完成或可能需要退款，就请保留旧模式的密钥。
付款通知
本部分显示您店铺的通知 URL，格式类似：https://your-site/wc-api/wc_p24_payment/。插件会在每次付款时将此 URL 发送给 Przelewy24，因此无需在 Przelewy24 后台进行任何设置。同一 URL 也会接收退款结果。该 URL 必须可从互联网访问：前方不得有防火墙、维护模式或 HTTP 身份验证。若没有通知，顾客返回订单接收页面时付款仍会被确认（见结账）；若顾客未返回，订单将保持“待付款”状态。
高级
Debug Log：Enable logging 会将技术事件（订单号、P24 交易 ID、错误）写入 WooCommerce > Status > Logs，来源为 wcp_przelewy24_payment。错误和警告始终会被记录。密钥、请求正文和个人数据绝不会被记录。默认：关闭。
Delete data on uninstall：Delete the plugin settings and logs when the plugin is deleted。订单及其付款数据绝不会被删除。停用插件会保留所有内容。默认：关闭。
结账
顾客选择付款方式（默认为 Przelewy24，结账区块中带有 P24 标识）并下单。沙盒模式下，结账区块显示 Sandbox mode — no real money is charged。插件会以订单币种为订单总额创建一笔 Przelewy24 交易，附带顾客的电子邮件、姓名和账单国家，并向订单添加一条包含会话 ID 和模式（沙盒或正式）的备注。每次付款尝试都会获得自己的会话 ID。顾客会被转到 Przelewy24 付款页面，并使用 BLIK、在线银行转账、银行卡或您的 Przelewy24 账户已启用的其他方式付款。若 Przelewy24 支持，付款页面将以网站语言显示，否则显示英语。
只有 Przelewy24 确认后，订单才会被标记为已付款。Przelewy24 会向您的店铺发送经签名的通知。插件会使用 CRC 密钥、Merchant ID 和 POS ID 验证签名；验证会话是否为该订单在同一模式下登记；并验证金额和币种与付款尝试及订单当前总额一致。只有在这些检查通过后，插件才会在 Przelewy24 处核实交易（Przelewy24 仅对已核实的付款入账），然后将订单标记为已付款。没有有效签名的 Webhook 会被拒绝。
付款后，顾客返回订单接收页面。如果通知尚未到达，插件会通过经身份验证的服务器对服务器请求向 Przelewy24 查询交易状态（每个订单每 10 秒最多一次），并应用相同的检查。仅凭返回页面，订单永远不会被标记为已付款。在付款得到确认之前，页面会显示 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:，并附带一个 Pay again 按钮，点击后打开 Pay for order 页面。若订单处于保留状态，页面会显示 Your payment is being verified. We will send you an e-mail as soon as it is confirmed. 在同一订单的较早 Przelewy24 页面上稍后完成的付款仍会被接受。
如果无法发起付款，顾客会看到一条简短消息：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（This order does not need a payment any more.）。
该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件不支持保存的银行卡或一键付款、订阅或定期付款、在结账页面选择 P24 付款方式（例如 BLIK 代码输入框）、分期付款小工具，且不会将购物车内容发送给 Przelewy24。
订单与退款
订单状态
Pending payment：顾客已被转到 Przelewy24，但尚未付款，或付款尚未确认。
Processing or Completed：付款已核实。WooCommerce 会设为「处理中」，若订单仅包含可下载的虚拟商品，则设为「已完成」。订单备注会显示 P24 订单 ID、金额和模式。订单的交易 ID 即为 P24 订单 ID。每笔付款仅应用一次。
On hold：Przelewy24 报告的金额或币种与订单不一致（例如付款开始后订单总额被修改）；付款未被确认，备注会说明此情况。或者付款已到达，但针对的是已取消的订单并已核实；订单不会悄悄重新打开，备注会请您发货或退还付款。请在 Przelewy24 后台核对该付款。
如果已付款或已退款的订单又收到第二笔付款（例如旧的付款链接、两个浏览器标签页），该付款不会被确认，因此 Przelewy24 不会入账。订单上的备注会请您在 Przelewy24 后台核对，并在必要时退还给买家。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Przelewy24。支持全额和部分退款。退款会以付款时所在的模式（沙盒或正式）发送，因此必须已设置该模式的密钥。Przelewy24 会异步处理退款：订单备注首先显示退款已申请，结果稍后会到达通知 URL 并以备注形式添加：Przelewy24: refund of … completed.，或者显示退款被拒绝、款项未退回的备注。若退款被拒绝，请在 Przelewy24 后台核对；订单上已记录的 WooCommerce 退款不会被自动删除。
若 Przelewy24 不接受退款请求，WooCommerce 会显示 Przelewy24 refund failed: 及原因，并且不会记录任何退款。直接在 Przelewy24 后台进行的退款不会添加到订单中。
许可证密钥
插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Przelewy24 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，Change key 输入其他密钥，Remove key 将其从本站点移除。Manage licenses and domains in your account 链接可打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从某站点移除密钥不会释放该站点的域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Przelewy24 不会在结账时向顾客显示。若仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也照常可用。
许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Przelewy24：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 Merchant ID、API key 和 CRC key 是否已输入（Test Mode 开启时使用沙盒密钥，否则使用正式密钥；Merchant ID 和 POS ID 仅限数字），以及订单币种是否为 PLN、EUR、GBP 或 CZK。设置顶部的警告会指出问题所在。开发者可以使用过滤器 wc_p24_supported_currencies 修改币种列表（仅限您的 Przelewy24 账户已启用且有两位小数的币种）。
付款已完成，但订单仍为 Pending payment：Przelewy24 的通知未能到达您的店铺，且顾客也未返回订单接收页面。请检查 Payment notifications 中显示的 URL 能否从互联网访问（/wc-api/wc_p24_payment/ 前方不得有维护模式、防火墙或 HTTP 身份验证），并检查付款所用模式的 Merchant ID、POS ID 和 CRC key 是否正确。被拒绝的通知会记录在 WooCommerce > Status > Logs 中，来源为 wcp_przelewy24_payment，即使 Debug Log 已关闭也会记录。
店铺如何响应通知：已处理、重复或未知的通知会以 HTTP 200 响应。否则 Przelewy24 会稍后重新发送：400（数据缺失或格式错误）、401 Invalid signature（CRC 密钥错误、Merchant ID 或 POS ID 不同，或通知使用了与付款不同模式的密钥签名）、405（不是 POST 请求）、500 Verification failed（与 Przelewy24 的核实失败；订单会添加一条备注，仅一次）以及 503 Busy, retry later（订单在同一时刻正被另一请求更新）。
顾客看到 Payment error: Przelewy24 could not start the payment:Przelewy24 拒绝了该交易，通常是因为当前模式的密钥有误（沙盒密钥仅在沙盒模式下有效，正式密钥仅在正式模式下有效）。Przelewy24 返回的错误信息记录在日志中。
付款后订单处于 On hold：请阅读订单备注。金额或币种与订单不符，或付款是针对已取消的订单到达的。请在 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.（或正式模式的相同提示）表示该付款所用模式的密钥已被移除；请重新输入。
许可证区块显示错误：请按照区块中的提示操作。例如，若该密钥已在另一域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now，为新域名激活密钥。若无法连接许可证服务器，插件将继续使用最后已知的状态运行。
卸载
停用插件会保留所有数据。要删除插件，请在 Plugins 页面中停用并删除。本插件的许可证密钥和许可证状态，以及返回页面的短期标记，始终会被删除。插件设置及其日志（包括已轮转的日志文件，以及来源为 wcp_przelewy24_payment 的数据库日志条目）仅在 Delete data on uninstall 开启时才会被删除。否则它们会保留，以便日后重新安装。现有订单会保留其付款备注、交易 ID 和 Przelewy24 付款数据。
Przelewy24 是其各自所有者的商标。本插件与 Przelewy24 无关联，也未获得 Przelewy24 的认可。