VibeFox PagSeguro for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
货币：巴西雷亚尔（BRL）。仅对 BRL 购物车显示该付款方式。
HTTPS：您的商店必须可通过互联网以 HTTPS 访问，以便 PagBank 能发送付款通知。
PagBank 账户：用于真实付款的正式环境令牌，以及用于测试的沙盒令牌。正式环境：登录您的 PagBank 账户，打开 Venda online > Integrações 并点击 Gerar token；PagBank 会通过电子邮件发送令牌。沙盒：在 PagBank 开发者门户中创建沙盒账户并复制其令牌。沙盒令牌和正式环境令牌只能在各自的环境中使用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox PagSeguro Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 输入沙盒令牌；若要接收真实付款，还需输入正式环境令牌。
5. 开启 Enable / Disable 并点击 Save。在开启 Sandbox Mode 的情况下进行测试付款，然后关闭它以接收真实付款。
安装时，模块会创建两个订单状态：Awaiting PagBank payment 和 PagBank payment on hold。PrestaShop 会为所有货币、国家和客户组提供新的付款模块。您可以在 Payment > Preferences 中加以限制；但模块必须始终允许 BRL 货币。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox PagSeguro Gateway > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。在各字段上方，页面会显示当前模式：SANDBOX MODE（付款在 PagBank 沙盒中创建，不产生真实扣款）或 LIVE（付款使用正式环境令牌创建）。当当前模式的令牌缺失时，页面会发出警告（此时付款方式在结账时会被隐藏）；当商店默认货币不是 BRL 时，也会发出警告（此时其他货币的购物车不会提供该付款方式）。
PagSeguro / PagBank
Enable / Disable：Enable PagSeguro/PagBank payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：PagSeguro / PagBank。必填。
Description：结账时显示在付款方式下方的文字。默认：Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.
PagBank 账户
本部分说明如何获取令牌，并提供指向您的 PagBank 账户及 PagBank 令牌说明页面的链接。
Sandbox Mode：Enable sandbox/test mode (no real charges)。新付款会使用沙盒令牌进入 PagBank 沙盒，顾客会在付款方式下方看到 SANDBOX MODE — Using test environment. No real charges. 订单的状态查询和退款始终使用创建其付款时所用的环境和令牌。默认：开启。
Sandbox token：PagBank 沙盒令牌。沙盒模式开启时使用。
Production token：PagBank 正式环境令牌（Bearer）。沙盒模式关闭时使用。请妥善保密。
已保存的令牌不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Clear saved tokens：勾选某个令牌并点击 Save 即可将其删除。字段留空则保留已保存的值。
付款通知
Notification URL：每笔付款都会告知 PagBank 将状态变化发送到哪里，因此无需在 PagBank 中进行任何设置。本部分会显示该 URL。启用友好 URL 时，它的格式如下：https://your-shop/module/wcp_pagseguro_gateway/webhook。该地址必须可通过互联网以 HTTPS 访问。
携带 x-authenticity-token 标头的通知会使用付款所在环境的令牌进行验证；签名无效的通知会被拒绝。通知正文本身永远不被信任：模块在创建或修改订单之前，始终会通过 PagBank API 读取 PagBank 的结账信息和订单（状态、金额、币种）。若没有收到通知，则在顾客付款后返回商店时创建订单。
高级
Debug log：Log API requests and notifications 会将详细信息写入模块文件夹中的 logs/wc_psg_debug.log.php。该文件无法通过网页打开。日志不包含令牌或顾客数据。错误始终会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data on Uninstall：开启后，卸载模块时会删除网关设置和日志。订单、其 PagBank 引用（退款所需）以及订单状态始终会保留。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 PagSeguro / PagBank）并确认。模块会为购物车总额（以 BRL 计）创建一笔 PagBank 付款，作为一个商品项，名称为 Order # 加购物车编号和您的商店名称，然后将顾客引导至 PagBank 付款页面。若商店已有顾客的姓名和电子邮件、地址中 Identification number 或 VAT number 字段中的 CPF 或 CNPJ，以及巴西电话号码，则会自动填入；顾客可以在 PagBank 页面上补充或更正这些信息。顾客使用您 PagBank 账户中已启用的付款方式付款，例如信用卡、PIX 或 boleto。付款页面将在 120 分钟后过期。此时尚未创建订单。
付款后，顾客返回您的商店。只有在 PagBank 确认付款后，订单才会被标记为已付款：模块会在收到通知或顾客返回时通过 PagBank API 读取付款信息，仅仅返回并不会将订单标记为已付款。随后订单被创建，顾客会看到订单确认页面，并显示 Your payment with PagBank has been received. 对于已生成的 boleto 或 PIX，或审核中的付款，页面会显示 Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. 如果此类付款之后被拒绝或取消，页面会显示 Your PagBank payment was not completed. Please contact us about this order. 如果顾客返回时 PagBank 尚未确认付款，将显示 Payment confirmation 页面，其中包含 We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. 以及 Check again 按钮。
如果付款未完成，顾客会返回结账页面，并看到 The PagBank payment was not completed. You can pay the order again below.、The PagBank payment page has expired. You can pay the order again below. 或 The payment was declined by PagBank. Please try again with another card or payment method. 购物车会被保留。如果正在等待 boleto 或 PIX 付款的订单已被取消，顾客会看到 The PagBank payment was cancelled, so the order was cancelled.
顾客再次付款时，如果金额和环境相同，且未在 10 分钟内过期，则会复用未关闭的 PagBank 付款；否则，之前的付款会被停用，无法再付款。在之前页面完成的付款仍然对购物车有效，系统会创建订单，而不是新建一笔付款。
如果 PagBank 无法发起付款，顾客会停留在结账页面，并看到简短提示，例如 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. 技术原因会写入日志。
即使商店处于维护模式，通知仍会正常工作，并且不受商店国家限制的影响。
本模块没有店内银行卡表单、不保存银行卡，也不支持订阅、定期付款、分单付款或市场（marketplace）。付款方式和分期付款由您在 PagBank 账户中设置。
订单与退款
订单状态
尚无订单：顾客已被转至 PagBank 但尚未付款，银行卡被拒绝或付款页面已过期。只存在购物车，顾客可以再次付款。
Payment accepted：付款已按预期金额和币种确认。付款会以 PagBank 收费 ID（charge ID）作为交易 ID 记录，并附注显示金额、付款方式和收费 ID。
Awaiting PagBank payment：已生成 boleto 或 PIX 并等待付款，或付款正在审核中。当 PagBank 报告已付款时，订单会转为 Payment accepted。
PagBank payment on hold：PagBank 报告的金额或币种与购物车不符（例如，在付款页面创建后购物车被修改），付款在订单被取消后到达（请检查库存，然后完成订单或在 PagBank 中退款），或银行卡付款已授权但未捕获（请在 PagBank 中捕获）。附注会说明原因。实际收到的款项会记录在订单中。
Payment error：等待中或审核中的付款被拒绝。
Canceled：等待中的付款（例如已过期的 boleto 或 PIX）被取消。
Refunded：付款已通过本模块或在 PagBank 后台全额退款。
每个 PagBank 状态只会应用一次，因此重复的通知或返回不会添加附注或更改状态。如果已付款的订单又收到第二笔付款，订单不会被更改，附注会提醒您在 PagBank 中退还重复的款项。
PagBank payment 区块
订单页面会显示 PagBank payment 区块，其中包括 PagBank 结账信息、PagBank 订单和收费 ID、付款方式、状态、已付金额和已退金额、沙盒付款的 Sandbox 标记、退款历史，以及订单的 PagBank notes。
退款
在 PagBank payment 区块中输入金额（尚未退款的金额会自动填入），可选填写原因，然后点击 Refund via PagBank。确认提示 Refund this amount through PagBank? This cannot be undone. 支持全额和部分退款。您需要有编辑订单的权限；无需访问模块页面的权限。上限为 PagBank 实际收取的金额，因此在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会在付款时所用的环境中并使用相同的令牌发送。只有 PagBank 确认后才会记录退款；否则该区块会显示错误，例如 PagBank refund failed: ... 或 PagBank did not confirm the refund，且不会记录任何内容。boleto 付款的退款以及 PIX 的部分退款遵循 PagBank 的规则。成功的退款会连同收费 ID 添加到退款历史和附注中。全额退款会将订单设为 Refunded；部分退款不会更改状态。只有在 PagBank 报告付款已完成后，才能进行退款。
本模块不会开具贷项凭证。PrestaShop 订单页面上的标准退款按钮不会通过 PagBank 退款。
在 PagBank 后台进行的退款会在下一次通知时被识别：全额退款会将订单设为 Refunded，部分退款会添加一条包含退款金额的附注，您也可以手动将退款记录到订单中。
许可证密钥
本模块需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox PagSeguro Gateway 是 Modules > Module Manager > VibeFox PagSeguro Gateway > Configure 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: presta-payment-pagseguro 一行，以及打开您 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 账户中释放名额。
没有有效密钥时，PagBank 不会在结账时显示给顾客。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 标签页会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可以正常进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron job。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 PagBank：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式的令牌是否已设置（沙盒模式为 Sandbox token，正式模式为 Production token），以及购物车货币是否为 BRL。当令牌缺失或商店货币不是 BRL 时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许 BRL、顾客所在国家以及顾客所在客户组。
付款已完成，但未创建订单：PagBank 尚未报告该付款，且顾客也没有返回商店。收到通知后，订单会立即创建。请检查您的商店能否通过互联网以 HTTPS 访问 Notification URL，并开启 Debug log 以查看通知。
通知返回 Invalid signature：x-authenticity-token 与付款所在环境的令牌不匹配，或该令牌未保存。请检查设置中是否填入了正确的令牌。
通知返回 Verification failed, retry later：无法连接 PagBank API、付款所在环境的令牌缺失，或购物车同时正被另一请求处理。PagBank 会重试该通知。
通知返回 Order not found：该通知对应的购物车不是通过本模块在本商店中付款的。不会做任何更改。
顾客看到 PagBank payments are temporarily unavailable. Please choose another payment method.:当前模式的令牌缺失，或 PagBank 拒绝了该令牌。
顾客看到 PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).:购物车使用的是其他货币。
订单为 PagBank payment on hold：请阅读 PagBank payment 区块中的附注（参见订单状态），在 PagBank 中比对金额，然后完成订单或退款。
退款失败并提示令牌相关信息：付款是在沙盒还是正式环境中进行的，而该环境的令牌缺失或被拒绝。请输入正确的令牌后重试。
卸载
进入 Modules > Module Manager，打开 VibeFox PagSeguro Gateway 旁边的菜单，然后选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，网关设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 PagBank 付款和退款以及订单状态 Awaiting PagBank payment 和 PagBank payment on hold 始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款附注和交易 ID。
PagSeguro 和 PagBank 是其各自所有者的商标。本模块与 PagSeguro 或 PagBank 无关，也未获得其认可。