VibeFox Przelewy24 for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：订单必须使用 PLN、EUR、GBP 或 CZK。使用其他货币时，结账页面不会显示该付款方式。订单以其自身货币扣款；扩展不进行货币换算。

Przelewy24 账户：您需要一个 Przelewy24 商户账户及其 API 数据：Merchant ID、API 密钥（在 Przelewy24 后台称为 report key）、CRC key，以及如果您的店铺拥有自己的 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 购买。一个密钥只能用于一个域名。

安装

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

OpenCart 3

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

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

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

4. 输入沙盒密钥（Merchant ID、API 密钥、CRC key；仅当 POS ID 与 Merchant ID 不同时才需要输入 POS ID），开启 Enable/Disable，点击 Save，并在沙盒模式下进行一次测试付款。

5. 输入正式密钥，关闭 Test Mode，然后点击 Save 以接受真实付款。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至第 5 步输入许可证密钥和 Przelewy24 密钥。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见付款通知）。

新安装默认关闭付款方式，并开启测试模式。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Przelewy24 Payment > Edit。各部分列于左侧；列表下方的 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 不接受店铺的默认货币，警告会指出该货币以及支持的货币。保存后，警告会立即反映新的模式和密钥。若没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，如果某个字段有误，则不会保存任何内容：Title 不能为空（Enter a title for the payment method (at most 128 characters).），Sort Order 必须为整数（允许负数），Total 必须为 0 或更大的数字，并且 Geo Zone 和订单状态必须存在。缺少密钥不会阻止保存。与 Przelewy24 后台的密钥一同复制的空格和换行符，在保存时会被删除。

Przelewy24

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

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

Description：在 Confirm Order 步骤中、确认按钮上方向顾客显示的文字。默认：Pay with BLIK, online bank transfer or card via Przelewy24。

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

Geo Zone：仅向所选地理区域内的账单地址提供 Przelewy24。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

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

API 凭据

本部分说明在哪里找到密钥（Przelewy24 商户后台中的 My data > API data and configuration），并提供 Przelewy24 后台和沙盒后台的链接。

Test Mode：使用 Przelewy24 沙盒和沙盒密钥，不会扣除真实款项。关闭后将使用正式密钥接受真实付款。默认：on。开启期间，顾客会在 Confirm Order 步骤中看到 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 key，用于对请求签名并验证沙盒通知。

已保存的 API 密钥和 CRC key 将不再显示。该字段保持为空，并显示 Saved - leave empty to keep it. 仅当您想更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved value，然后点击 Save。

正式密钥和沙盒密钥是不同的。Merchant ID 和 POS ID 只能包含数字；在输入当前模式的 Merchant ID、API 密钥和 CRC key 之前，结账页面不会显示该付款方式。在某一模式下发起的付款，即使切换模式后，也始终使用该模式的密钥进行验证和退款，因此在旧模式的付款仍未结束或可能需要退款期间，请保留旧模式的密钥。

付款通知

Notification URL：接收 Przelewy24 付款通知的地址。其形式为 OpenCart 3 的 https://your-store/index.php?route=extension/payment/wcp_przelewy24_payment/notify，OpenCart 4 的 https://your-store/index.php?route=extension/wcp_przelewy24_payment/payment/wcp_przelewy_24payment.notify，由您的 OpenCart 安装的店铺前台地址生成。扩展会在每笔付款和每次退款时将此 URL 发送给 Przelewy24，因此无需在 Przelewy24 后台进行任何配置。该 URL 必须能够从互联网访问：其前面不能有防火墙或 HTTP 身份验证。店铺处于维护模式时，它仍可正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 上，扩展会为通知 URL 和顾客返回添加自己的启动动作。即使没有通知，顾客返回店铺时付款仍会被确认（见结账）；如果顾客没有返回，订单将保持无状态。

订单

OpenCart 在 Confirm Order 步骤中创建订单，此时订单无状态（缺失订单）。只有在 Przelewy24 确认付款并且扩展完成验证后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Paid Order Status：付款经验证后的状态。默认：Processing。

On Hold (Review) Status：金额或币种与订单不符（未验证）的付款，或在订单被取消后到达的付款，将获得此状态以及说明原因的备注。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Order Status：扩展从不设置此状态。对处于此状态订单的已验证付款，会将订单置于暂停状态，而不是悄悄将其重新打开。默认：Canceled。

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

高级

Debug Log：将技术事件（订单号、P24 交易 ID、错误）写入 OpenCart 日志文件夹（storage/logs）中的 wc_p24_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会被移动到 wc_p24_debug.old.log.php。错误和警告（例如被拒绝的通知，或验证或退款失败）始终会被记录；打开该开关可同时记录每个步骤。密钥和个人数据永远不会被记录。默认：off。

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

Delete data on uninstall：开启后，卸载扩展时会删除网关设置和日志。订单及其 Przelewy24 付款数据永远不会被删除。默认：off。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。API 密钥和 CRC key 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 API 密钥和 CRC key 将被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Przelewy24）。在 Confirm Order 步骤中，顾客会看到您的说明以及提示 You will be redirected to the secure Przelewy24 page to complete the payment. OpenCart 在此步骤中创建订单，仍无状态。当顾客点击 Confirm Order 时，扩展会以订单货币为订单总额在 Przelewy24 中登记一笔交易，并附上顾客的电子邮件、姓名和账单国家，以及描述 Order #（后接订单号）和您的店铺名称。每次付款尝试都会获得自己的会话 ID。顾客会被带到 Przelewy24 付款页面，使用 BLIK、在线银行转账、银行卡或您的 Przelewy24 账户中启用的其他方式付款。如果 Przelewy24 支持，付款页面会以订单的语言显示，否则显示英文。在 OpenCart 4 上，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

只有在 Przelewy24 确认后，订单才会被标记为已付款。Przelewy24 会向您的店铺发送已签名的通知。扩展会使用 CRC key、Merchant ID 和 POS ID 验证签名；检查会话是否是为此订单以相同模式登记的；并检查金额和币种是否与付款尝试及订单总额一致。只有在这些检查通过后，扩展才会向 Przelewy24 验证交易（Przelewy24 只入账已验证的付款），并以 OpenCart 的标准方式设置 Paid Order Status，同时发送常规订单邮件并更新库存。没有有效签名的 Webhook 会被拒绝。

付款后，顾客会返回您的店铺。如果通知尚未到达，扩展会通过经过身份验证的服务器到服务器请求向 Przelewy24 查询交易状态（每次尝试最多每 10 秒一次），并应用相同的检查。仅返回页面本身永远不会将订单标记为已付款。付款确认后，顾客会看到 OpenCart 订单成功页面。在确认之前，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. 当之后的付款将订单从暂停状态转为 Paid Order Status 时，顾客会收到电子邮件通知。如果您在付款前取消了订单，且 Przelewy24 没有该订单的付款，返回的顾客会看到 Order #… was cancelled by the store before the payment was completed. No Przelewy24 payment was received for it. Please place a new order or contact us.

如果无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示：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. OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；已付款的订单或购物车不会再次发送给 Przelewy24，顾客会被带到成功页面。

OpenCart 4 为结账保留一个订单，并在每次显示 Confirm Order 步骤时更新该订单，因此 Pay again 会为同一订单启动新的 Przelewy24 交易。如果该订单其间已被商店关闭（例如被取消或退款），顾客会被带回结账页面，并看到 Your previous order was closed by the store. Please confirm the order again to place and pay a new order.（对于付款前已取消的订单，同时显示上文的已取消订单消息），下一次 Confirm Order 将为新订单付款。如果结账的订单已付款，但之后购物车已更改（包括数量变化），顾客会看到 Your previous order #… has already been placed. Your cart has changed: please confirm the new order to pay for it.，新购物车将以新订单付款。在 OpenCart 4 上，这些消息以及 We could not match this payment to an order. If you were charged, please contact us. 都会显示在结账页面上方。

该扩展不支持保存银行卡或一键付款、订阅或定期付款，不在您的结账页面提供 P24 付款方式选择（例如 BLIK 代码输入框），不提供分期付款组件，也不会将购物车内容发送给 Przelewy24。

订单与退款

订单状态

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

Paid Order Status（默认 Processing）：付款已验证。备注会显示 P24 订单 ID、金额和模式。每笔付款只会应用一次。

On Hold (Review) Status（默认 Pending）：Przelewy24 报告的金额或币种与订单不同；付款未被确认，备注会说明这一点。或者付款已到达，并且是针对已取消状态的订单进行验证的；订单不会被悄悄重新打开，备注会要求您发货或退还付款。请在 Przelewy24 后台核对该付款。如果在金额不符之后，同一订单的另一次尝试稍后又收到了正确付款，订单将转为 Paid Order Status。

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

如果同一订单或购物车已付款或已退款时又收到第二笔付款（旧的付款链接、两个浏览器标签页、同一购物车的另一个订单），则该付款不会被确认，因此 Przelewy24 不会入账。已付款订单上的备注会要求您在 Przelewy24 后台检查该付款，并在需要时退还给买家。

备注是订单 History 中的记录，顾客看不到。

VibeFox Przelewy24 Payment 标签页

在 Sales > Orders 中打开一个通过 Przelewy24 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Przelewy24 Payment 标签页会显示 P24 订单 ID、Session、Environment（Sandbox 或 Live）、付款的 Status 以及验证方式（通知或返回）、Paid / refunded 金额、退款表单、退款历史以及订单的 Payment notes。该标签页会显示给有权访问该扩展的用户。

退款

在 VibeFox Przelewy24 Payment 标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Przelewy24。确认提示 Refund this amount through Przelewy24? This cannot be undone. 支持全额和部分退款，但不能超过尚未退款的金额。您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。退款会以付款时所用的模式（沙盒或正式）发送，因此该模式的密钥必须已设置。付款经 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 Status，不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。如果退款被拒绝，请在 Przelewy24 后台核对；订单状态不会自动恢复。

如果 Przelewy24 不接受退款请求，该标签页会显示 Przelewy24 refund failed: 及原因，并且不会记录任何退款。在 Sales > Returns 中的商品退货不会通过 Przelewy24 退款，直接在 Przelewy24 后台进行的退款也不会添加到订单中。

许可证密钥

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

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

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

故障排除

结账时不显示 Przelewy24：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式的 Merchant ID、API 密钥和 CRC key 是否已输入（Test Mode 开启时使用沙盒密钥，否则使用正式密钥；Merchant ID 和 POS ID 仅限数字），以及订单货币是否为 PLN、EUR、GBP 或 CZK。设置顶部的警告会指出问题。另外请检查账单地址是否位于所选的 Geo Zone 内，以及订单金额是否达到设置中的 Total。

付款已完成，但订单仍无状态：Przelewy24 的通知未到达您的店铺，并且顾客也没有返回店铺。请检查 Notification URL 是否可从互联网访问（其前面没有防火墙或 HTTP 身份验证），以及付款所属模式的 Merchant ID、POS ID 和 CRC key 是否正确。即使 Debug Log 关闭，被拒绝的通知也会写入日志；请查看扩展页面上的 Log 字段。

店铺如何响应通知：已处理、重复或未知的通知会以 HTTP 200 响应。否则，Przelewy24 稍后会重新发送：400（数据缺失或格式错误）、401 Invalid signature（CRC key 错误，Merchant ID 或 POS ID 不同）、401 Invalid signature for this payment（使用与付款模式不同的密钥签名的通知）、405（非 POST 请求）、500 Verification failed（与 Przelewy24 的验证失败；订单中会添加一次备注）、500 Order could not be updated（无法设置订单状态；下一条通知会在不重新验证的情况下设置它）以及 503 Busy, retry later（该订单此时正被另一请求确认）。

顾客看到 Payment error: Przelewy24 could not start the payment:Przelewy24 拒绝了该交易，通常是因为当前模式的密钥错误（沙盒密钥仅适用于沙盒模式，正式密钥仅适用于正式模式）。Przelewy24 返回的错误记录在日志中。

顾客看到 We could not match this payment to an order:Przelewy24 的返回链接与店铺中的任何订单都不匹配。如果顾客已被扣款，请在 Przelewy24 后台查找该付款。

付款后订单处于审核状态：请阅读 VibeFox 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 表示金额为空、不是数字，或超过了尚未退款的金额。

面向开发人员：可以通过 OpenCart 事件 wc_p24_supported_currencies 修改货币列表（仅限两位小数的货币）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Przelewy24 Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 上，还会删除其事件和启动动作，它们让通知和顾客返回在维护模式下得以通过）。如果开启了 Delete data on uninstall，则其他网关设置（标题、说明、测试模式、密钥、调试日志开关）和日志都会被删除。如果关闭，则会保留它们，以便之后重新安装时使用。订单的 Przelewy24 付款数据（会话、P24 订单 ID、退款）始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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