VibeFox PagSeguro for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Currency：巴西雷亚尔（BRL）。商店必须设置 BRL 货币（System > Localisation > Currencies），且只有当顾客以 BRL 结账时才会显示该付款方式。
Reachable site：您的商店必须可以通过互联网访问，PagBank 才能发送付款通知。
PagBank account：用于真实付款的生产令牌和用于测试的沙盒令牌。生产令牌：登录您的 PagBank 账户，打开 Venda online > Integrações，然后点击 Gerar token；PagBank 会通过电子邮件发送令牌。沙盒令牌：在 PagBank 开发者门户中复制您沙盒账户的令牌。沙盒令牌和生产令牌只能在各自的环境中使用。
VibeFox license key：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_pagseguro_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_pagseguro_gateway.ocmod.zip。只需安装适用于您的 OpenCart 版本的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_pagseguro_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PagSeguro Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。
4. 输入沙盒令牌；如需接受真实付款，再输入生产令牌。无需在 PagBank 中进行任何设置：每笔付款都会发送通知 URL。
5. 开启 Enable / Disable，然后点击 Save。开启 Sandbox Mode 进行测试付款，然后将其关闭以接受真实付款。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_pagseguro_gateway.ocmod.zip。请不要重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox PagSeguro Gateway，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 输入许可证密钥和令牌，并按照 OpenCart 3 步骤 3 至 5 的方式测试付款。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见 Notification URL）；它同样会随每笔付款发送至 PagBank。
新安装时，付款方式默认关闭，沙盒模式默认开启。
配置
所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox PagSeguro Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会显示当前模式：SANDBOX MODE（付款在 PagBank 沙盒中创建，不会产生真实扣款）或 LIVE（付款使用生产令牌创建）。当当前模式的令牌缺失时（此时付款方式会在结账时隐藏），以及商店的默认货币不是 BRL 时，页面会发出警告。如果没有修改扩展的权限，页面会显示设置，但无法保存。
保存时，Title 不能为空（最多 128 个字符），Sort Order 必须是整数（允许负数），Total 必须是 0 或更大的数字，且地理区域和订单状态必须存在。如果某个值有误，错误信息会指出该值，并且不会保存任何内容。
PagSeguro / PagBank
Enable / Disable：Enable PagSeguro/PagBank payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：PagSeguro / PagBank。必填，最多 128 个字符。
Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.
Sort Order：PagBank 在结账时付款方式中的排列位置。留空或输入整数。
Geo Zone：仅为所选地理区域内的付款地址提供 PagBank。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 中，如果商店不要求付款地址，则使用配送地址。
Total：订单必须达到的结账总额（以商店默认货币计算），才会提供 PagBank。留空则对任何总额都提供 PagBank。
PagBank 账户
本部分说明如何获取令牌，并提供指向您的 PagBank 账户和 PagBank 令牌说明页面的链接。
Sandbox Mode：Enable sandbox/test mode (no real charges)。新付款使用沙盒令牌发送到 PagBank 沙盒，顾客在 Confirm Order 步骤中会看到 SANDBOX MODE — Using test environment. No real charges. 状态查询和订单退款始终使用其付款创建时所用的环境和令牌。默认：开启。
Sandbox token：PagBank 沙盒令牌。沙盒模式开启时使用。
Production token：PagBank 生产令牌（Bearer）。沙盒模式关闭时使用。请妥善保密。
已保存的令牌不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 仅当您想更改时才输入新值。要删除已保存的令牌，请勾选字段下方的 Clear the saved token on save，然后点击 Save。
付款通知
Notification URL：每笔付款都会指示 PagBank 将其结账和付款通知发送到此 URL，因此无需在 PagBank 中进行任何配置。在 OpenCart 3 中，其格式类似 https://your-store/index.php?route=extension/payment/wcp_pagseguro_gateway/webhook；在 OpenCart 4 中，类似 https://your-store/index.php?route=extension/wcp_pagseguro_gateway/payment/wcp_pagseguro_gateway.webhook。该地址由您的 OpenCart 安装的商店前台地址生成。该 URL 必须可以通过互联网访问。
带有 x-authenticity-token 标头的通知会使用付款创建时所在环境的令牌进行验证；无效的签名会被拒绝。通知正文本身永远不被信任：扩展在更改订单之前，始终会通过 PagBank API 读取结账和 PagBank 订单（状态、金额、货币）。若没有通知，顾客付款后返回商店时，订单才会获得状态。
订单
OpenCart 在 Confirm Order 步骤中创建订单时不带状态（缺失订单）。只有在 PagBank 通过通知或顾客返回时报告付款后，订单才会获得状态；付款信息始终从 PagBank 回读。下面的每个字段都列出了您的 OpenCart 订单状态。
Order Status After Payment：经过验证的 PagBank 付款后设置的状态。默认：处理中。
Awaiting PagBank Payment Status：已生成 boleto 或 PIX，或付款正在审核中（WAITING / IN_ANALYSIS）；PagBank 稍后会确认款项。默认：待处理。
PagBank Payment On Hold Status：该付款需要您审核（参见订单状态）。默认：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。
Payment Declined Status：等待中的订单的付款被拒绝。如果 PagBank 之后报告已付款，订单将获得付款后的状态。默认：失败。
Payment Cancelled Status：等待中的订单的付款已在 PagBank 中取消。为处于此状态的订单收到的付款会将其转为审核状态。默认：已取消。
Refunded Status：在订单页面或 PagBank 后台将付款全额退款后设置。默认：已退款。
高级
Debug log：将 API 请求和通知写入 OpenCart 日志文件夹（storage/logs）中的 wc_psg_debug.log.php。该文件无法通过网页打开。日志不包含令牌和顾客数据。错误和警告始终会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可将其清空。
Delete Data on Uninstall：开启时，卸载扩展会删除网关设置和日志。订单及其 PagBank 引用（退款所需）始终会保留。默认：关闭。
导入 / 导出
Export：Download JSON 会将设置保存为 JSON 文件。令牌不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的令牌会保留。
结账
在 Payment Method 步骤中，顾客选择付款方式（默认为 PagSeguro / PagBank）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to the PagBank payment page (credit card, PIX, boleto) and returned to the store. OpenCart 在此步骤创建订单，仍不带状态。在 OpenCart 4 中，顾客需在 Payment method options 窗口中点击付款方式区块的 Choose 按钮选择付款方式，然后点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 时，扩展会以 BRL 为订单总额创建一个 PagBank 结账，作为单个商品，名称为 Order # 加上订单号和您的商店名称（优惠券、运费和税费都计入总额），并将顾客带到 PagBank 付款页面。系统会传递顾客的姓名和电子邮件，以及来自顾客或付款地址中名称包含 CPF 或 CNPJ 的自定义字段的 CPF 或 CNPJ（11 位或 14 位数字），还有一个巴西电话号码。OpenCart 默认没有 CPF 字段；您可以在 Customers > Custom Fields 中添加。在 OpenCart 4 中，如果商店不要求付款地址，则使用配送地址及其自定义字段。顾客可以在 PagBank 页面上补充或更正这些信息，并使用您 PagBank 账户中启用的方式付款。付款页面 120 分钟后过期。
付款后，顾客返回您的商店。只有在 PagBank 确认后，订单才会被标记为已付款：扩展会在收到通知或顾客返回时通过 PagBank API 读取付款信息，且扣款金额（不含 PagBank 分期利息）和货币必须与订单一致。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。对于已生成的 boleto 或 PIX，或处于审核中的付款，页面还会显示 Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. 对于处于审核状态的订单，则显示 We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. 如果顾客返回时 PagBank 尚未确认付款，Payment confirmation 页面会显示相同的文字，并带有 Check again 和 Back to checkout 按钮。
如果付款未完成，顾客会返回结账页面，并看到 The PagBank payment was not completed. You can try again or choose another payment method.、The PagBank payment page has expired. You can try again or choose another payment method. 或 The payment was declined by PagBank. Please try again with another card or payment method. 购物车会被保留。在 OpenCart 4 中，这些消息显示在结账页面上方。如果一个正在等待 boleto 或 PIX 的订单被取消，顾客会看到 The PagBank payment was cancelled, so the order was cancelled. 如果购物车已经为空（例如，订单在 boleto 或 PIX 过期之前已经到达成功页面），结账时没有任何需要支付的内容：取而代之，Payment confirmation 页面会显示该消息；对于未付款的订单，消息为 The PagBank payment of order #N was not completed (declined, canceled or expired), so the order will not be shipped. To buy these items, please place a new order.，并带有 Continue 按钮。
每次显示 Confirm Order 步骤时，OpenCart 3 都会创建一个新订单。OpenCart 4 为结账保留一个订单并对其进行更新，因此在银行卡被拒、付款未完成或页面过期后，顾客会以新的 PagBank 结账为同一订单付款。在新的付款之前，扩展会检查同一订单和购物车之前的 PagBank 结账：如果之前的页面已完成付款，则应用该付款，而不是创建新付款；如果购物车中的另一个订单已付款或正在等待，顾客将被带到成功页面。如果订单的未完成结账的金额和环境相同，并且在 10 分钟内不会过期，则会复用该结账；否则将其停用，使其无法再付款。如果仍然收到第二笔付款，会有一条备注请您退款。
如果订单已付款，之后被您关闭（例如取消或退款），从 PagBank 返回的顾客不会看到成功页面：顾客会回到结账页面，并看到 Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order.，如果购物车已为空，则会在 Payment confirmation 页面上看到该消息。
在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单期间已被关闭，Confirm Order 会将顾客带回结账页面并显示相应消息：上文关于 boleto 或 PIX 被取消以及付款被拒绝的消息，Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.；或者对于已付款后被您关闭的订单，显示商店关闭订单的消息。下一次 Confirm Order 会支付一个新订单。如果该订单已付款或正在等待，且购物车中现在有其他商品或数量不同，则消息为 Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it.
如果 PagBank 无法启动付款，顾客会停留在 Confirm Order 步骤，并显示一条简短消息，例如 PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. 或 Could not connect to PagBank. Please try again in a moment. 技术原因会写入日志。
商店处于维护模式时，通知仍然有效：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会添加一个启动操作，放行通知以及顾客从 PagBank 的返回。
该扩展没有站内银行卡表单、没有已保存的银行卡、没有订阅或定期付款，也不支持分单付款或市场模式。付款方式和分期付款由您在 PagBank 账户中的设置决定。
订单与退款
订单状态
No status (missing order)：顾客已被转到 PagBank 但尚未付款、银行卡被拒绝或付款页面已过期；顾客可以再次付款。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时才会显示此类订单。
在 OpenCart 4 中，结账时未付款的订单可能会获得 Voided 状态，该状态会在顾客返回 Confirm Order 步骤时由 OpenCart 4 设置。扩展将此类订单视为无状态订单，之后的付款仍会确认该订单。
Order Status After Payment (default Processing)：付款已按预期金额和货币确认。备注会显示金额、付款方式和 PagBank 扣款 ID。
Awaiting PagBank Payment Status (default Pending)：已生成 boleto 或 PIX 并等待付款，或付款正在审核中。当 PagBank 报告已付款时，订单会转为 Order Status After Payment。
PagBank Payment On Hold Status (default Pending)：PagBank 报告的金额或货币与订单不同；订单取消后又收到付款（请检查库存，然后完成订单或在 PagBank 中退款）；或银行卡付款已授权但未扣款（请在 PagBank 中扣款）。备注会说明情况。实际收到的款项会被记录下来，以便退款。
Payment Declined Status (default Failed)：等待中或审核中的付款被拒绝。
Payment Cancelled Status (default Canceled)：等待中的付款（例如过期的 boleto 或 PIX）被取消。
Refunded Status (default Refunded)：付款已全额退款，可通过扩展或 PagBank 后台完成。
每个 PagBank 状态只会应用一次，因此重复的通知或返回不会添加备注或更改状态。已付款的订单绝不会被改回。如果同一已付款订单又收到了第二笔付款，订单不会被更改，并且备注会请您在 PagBank 中退还重复的款项。备注是订单 History 中的条目，顾客看不到。
VibeFox PagSeguro Gateway 选项卡
在 Sales > Orders 中打开一笔通过 PagBank 付款的订单。在订单页面底部，History 和 Additional 旁边的 VibeFox PagSeguro Gateway 选项卡会显示 PagBank checkout（沙盒付款带有 Sandbox 标签）、PagBank order 和 Charge 的 ID、Payment method、Status、Paid / refunded 金额、退款表单、退款历史以及订单的 PagBank notes。该选项卡会显示给有权访问该扩展的用户。
退款
在 VibeFox PagSeguro Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via PagBank。确认提示 Refund this amount through PagBank? This cannot be undone. 支持全额退款和部分退款。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。上限是 PagBank 扣除的金额，因此在金额不一致的情况下，您最多可以退还顾客实际支付的金额，而不是订单总额。退款会在付款时所用的环境中并使用相应的令牌发送。只有当 PagBank 确认后，退款才会被记录；否则该选项卡会显示错误，例如 PagBank refund failed: ... 或 PagBank did not confirm the refund，并且不会记录任何内容。boleto 付款的退款以及 PIX 的部分退款遵循 PagBank 的规则。成功的退款会连同扣款 ID 一起添加到退款历史和备注中。全额退款会将订单设置为 Refunded Status，不会通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。一旦 PagBank 报告付款已完成，即可进行退款。
Sales > Returns 中的商品退货不会通过 PagBank 退还款项。
在 PagBank 后台进行的退款会在下一次通知或检查时被识别：全额退款会将订单设置为 Refunded Status，部分退款则会添加一条包含退款金额的备注。
许可证密钥
该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥才能运行。许可证区块 License — VibeFox PagSeguro Gateway 是 Extensions > Extensions > Payments > VibeFox PagSeguro Gateway > Edit 页面中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮盖的密钥、状态（例如许可证有效期截止日期和您的域名），以及用于重新检查状态的 Check now、用于输入其他密钥的 Change key，以及用于从此商店移除密钥的 Remove key 按钮。在它们下方有一行 Product: opencart-payment-pagseguro，以及打开您 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 PagBank。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 以同一浏览器登录后台的管理员用户仍会在商店中看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 中，此预览不可用：商店无法看到管理员的登录状态，因此在没有有效密钥的情况下，所有人都看不到该付款方式。打开一次 Edit 页面后，后台的 Dashboard 上会出现一条提醒。点击 × 可将其关闭，隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也照常进行。
许可证到期后，扩展仍会继续运行，但更新和支持需要续订。当您打开后台 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展始终会删除许可证密钥和许可证状态。
故障排除
PagBank does not appear at checkout：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式的令牌是否已设置（沙盒模式下为 Sandbox token，实时模式下为 Production token），以及顾客是否以 BRL 结账。当令牌缺失或商店货币不是 BRL 时，设置页面会显示警告。还请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。
The payment went through, but the order stays without a status：PagBank 尚未报告付款，且顾客也没有返回商店。通知一到达，订单就会获得状态。请检查您的商店能否通过互联网访问 Notification URL，并开启 Debug log 以查看通知。
The notification answers Invalid signature：x-authenticity-token 与付款所在环境的令牌不匹配，或该令牌未保存。请检查设置中是否填写了正确的令牌。
The notification answers Verification failed, retry later：无法访问 PagBank API，付款环境的令牌缺失，或者购物车在同一时刻正被另一个请求处理。PagBank 会重试该通知。
The notification answers Order not found：该通知针对的订单并非通过此商店中的此扩展付款的。不会更改任何内容。
The customer sees PagBank payments are temporarily unavailable. Please choose another payment method.：当前模式的令牌缺失，或 PagBank 拒绝了该令牌。
The customer sees PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).：结账所用货币不是 BRL。
The customer sees This order has no amount to pay.：订单总额为零。
Order is in the review status after payment：请阅读 VibeFox PagSeguro Gateway 选项卡中的备注（参见订单状态），在 PagBank 中核对金额，然后处理订单或为付款退款。
No refund form in the tab：选项卡会说明原因：付款尚未报告为已付款、已全额退款、您的用户组没有修改扩展的权限，或付款环境的令牌未设置。
Refund fails with a message about the token：付款是在沙盒或生产环境中完成的，而该环境的令牌缺失或被拒绝。请输入正确的令牌后重试。
面向开发者：在创建 PagBank 结账之前，扩展会触发 OpenCart 事件 wc_psg_checkout_data，并附带请求正文、订单和环境信息。商品金额必须与订单总额保持一致。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox PagSeguro Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，重新安装后这些设置会恢复为默认值。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件和启动操作，后者用于在维护模式下放行通知和顾客的返回）。如果 Delete Data on Uninstall 已开启，则其余网关设置（标题、描述、沙盒模式、令牌、日志记录）和日志会被删除。如果已关闭，这些设置会保留，供以后重新安装时使用。PagBank 的付款和退款记录始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如果还要删除扩展文件，请在卸载后进入 Extensions > Installer，点击已安装扩展列表中 VibeFox PagSeguro Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
PagSeguro 和 PagBank 是其各自所有者的商标。本扩展与 PagSeguro 或 PagBank 无关联，也未获得其认可或背书。