VibeFox PagSeguro for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce，插件无法启用。
PHP：8.0 或更高版本。
货币：巴西雷亚尔（BRL）。如果店铺货币（或在 Pay for order 页面上的订单货币）不是 BRL，结账时将不显示该付款方式。
HTTPS：您的网站必须可通过 HTTPS 从互联网访问，PagBank 才能发送付款通知。
PagBank 账户：用于真实付款的正式环境令牌，以及用于测试的沙盒令牌。正式环境令牌：登录您的 PagBank 账户，打开 Venda online > Integrações，然后点击 Gerar token；PagBank 会通过电子邮件发送令牌。沙盒：在 PagBank 开发者门户中创建沙盒账户，并复制其令牌。沙盒令牌和正式环境令牌只能在各自的环境中使用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_pagseguro_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入沙盒令牌；如需接收真实付款，再输入正式环境令牌。
6. 启用 Enable / Disable 并保存。在 Sandbox Mode 开启时进行测试付款，然后关闭它以接收真实付款。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > PagSeguro / PagBank。在标题下方，页面会显示当前模式：SANDBOX MODE（付款在 PagBank 沙盒中创建，不会产生真实扣款）或 LIVE（付款使用正式环境令牌创建）。如果当前模式的令牌缺失（此时结账页面会隐藏该付款方式），或店铺货币不是 BRL，页面会发出警告。在付款方式列表中，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 提示。订单的状态查询和退款始终使用创建该订单付款时所用的环境和令牌。默认：开启。
Sandbox token：PagBank 沙盒令牌。沙盒模式开启时使用。
Production token：PagBank 正式环境令牌。沙盒模式关闭时使用。请妥善保密。
1.0 版本中的单一令牌会自动迁移：如果沙盒模式原本已开启，它将成为沙盒令牌；否则保留为正式环境令牌。
付款通知
每笔付款都会告知 PagBank 将状态变更通知发送到何处，因此无需在 PagBank 中进行设置。本节会显示通知 URL，其格式如下：https://your-site/wc-api/webhook_wc_pagseguro/。该地址必须可通过 HTTPS 从互联网访问。
带有 x-authenticity-token 标头的通知会使用订单所在环境的令牌进行校验；签名无效的通知会被拒绝。通知正文本身永远不会被信任：插件在修改订单之前，始终会通过 PagBank API 读取结账信息和 PagBank 订单（状态、金额和币种）。
高级
Debug log：Log API requests and notifications 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_pagseguro_gateway。错误始终会被记录。日志中不包含令牌或顾客数据。默认：关闭。
Delete Data on Uninstall：Remove the gateway settings and logs when the plugin is deleted。默认：关闭。
结账
顾客选择付款方式（默认为 PagSeguro / PagBank）并下单。插件会以 BRL 为货币，按订单的确切总额创建一笔 PagBank 结账，将其作为单个商品，Order # 后附订单号和您的店铺名称，然后将顾客引导至 PagBank 付款页面。如果店铺已有顾客的姓名和电子邮件、来自 Brazilian Market on WooCommerce 插件字段的 CPF 或 CNPJ，以及巴西电话号码，这些信息会自动填入；顾客可以在 PagBank 页面上补充或更正。顾客使用您 PagBank 账户中已启用的付款方式付款，例如信用卡、PIX 或 boleto。
付款页面会在 WooCommerce 的 Hold stock 计时器取消未付款订单之前 5 分钟过期（最少 10 分钟）；如果未保留库存，则在 120 分钟后过期。
付款后，顾客会返回店铺。返回会以与通知相同的方式进行核实：插件通过 PagBank API 读取付款，仅凭返回本身，订单绝不会被标记为已付款。已付款的订单，或仍在等待中的付款（boleto、PIX、审核），会进入订单已接收页面；如果 PagBank 尚未发出通知，订单将由通知确认。
如果付款未完成，顾客会返回 Pay for order 页面，并看到 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. 如果付款已取消且订单也随之取消，顾客会被带到购物车，并看到 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. PagBank 给出的原因会添加到订单备注中。
该付款方式适用于经典结账、结账区块以及 Pay for order 页面，并兼容 WooCommerce 高性能订单存储（HPOS）。
插件不提供网站内银行卡表单、已保存的银行卡、订阅、定期付款、分单付款或市场功能。付款方式和分期付款以您 PagBank 账户中的设置为准。
订单与退款
订单状态
Pending payment：顾客已被引导至 PagBank，但尚未付款。备注中会显示 PagBank 结账 ID 和环境。如果付款页面在未付款的情况下过期，备注会说明此事，且状态不会变化。
Processing：付款已确认。这是付款后 WooCommerce 的标准状态；只包含虚拟可下载商品的订单会变为已完成。订单备注会显示金额、付款方式以及 PagBank 扣款 ID，该 ID 同时也是订单的交易 ID。
On hold：已生成 boleto 或 PIX 并等待付款；付款正在审核中；银行卡付款已授权但未捕获（请在 PagBank 中捕获）；已付金额或币种与订单不符；或者在 WooCommerce 取消未付款订单后才收到付款（请检查库存，然后完成订单或在 PagBank 中退款）。订单备注会说明原因。
Failed：付款被拒绝。顾客可以从 Pay for order 页面重新付款。
Cancelled：付款已取消，例如 boleto 或 PIX 已过期。
Refunded：付款已在 PagBank 后台全额退款。
每个 PagBank 状态只会应用一次，因此重复的通知或返回不会添加备注、邮件或库存扣减。如果已付款的订单又收到第二笔付款，备注会提示您在 PagBank 中退款。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via PagSeguro / PagBank（按钮会显示您的付款方式名称）。支持全额和部分退款。退款会在付款时所用的环境中，并使用当时的令牌发送。只有 PagBank 确认后才会记录退款；否则 WooCommerce 会显示错误，例如 PagBank refund failed: ... 或 PagBank did not confirm the refund，且不会记录任何内容。boleto 付款的退款以及 PIX 的部分退款遵循 PagBank 的规则。成功的退款会连同扣款 ID 一起添加到订单备注中。
在 PagBank 后台进行的退款不会作为 WooCommerce 退款项导入。全额退款会将订单设为已退款；部分退款会添加一条包含退款金额的备注，您可以手动将退款添加到订单中。
许可证密钥
插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > PagSeguro / PagBank 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证的有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将密钥从本站移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额，请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账页面不会向顾客显示 PagBank。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常进行。
许可证过期后，插件仍会继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 PagBank：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式的令牌是否已填写（沙盒模式为 Sandbox token，实时模式为 Production token），以及店铺货币是否为 BRL。在上述任一情况下，设置页面都会显示警告。
付款已完成，但订单仍处于待付款状态：PagBank 尚未报告该付款，且顾客也没有返回店铺。收到通知后订单会自动更新。请检查您的网站是否可通过 HTTPS 从互联网访问，并查看 WooCommerce > Status > Logs，来源为 wcp_pagseguro_gateway。
通知返回 Invalid signature：x-authenticity-token 与订单付款时所用环境的令牌不匹配。请检查设置中是否填写了正确的令牌。
通知返回 Verification failed, retry later：无法连接 PagBank API，订单环境的令牌缺失，或订单正被另一个请求同时更新。PagBank 会重试该通知。
通知返回 Order not found：订单在本店铺中不存在，或使用了其他付款方式付款。不会进行任何更改。
顾客看到 This order is already being processed：通知或顾客的返回正在同时更新订单。顾客可稍后重试。
顾客看到 PagBank payments are temporarily unavailable：当前模式的令牌缺失，或被 PagBank 拒绝。
顾客看到 PagSeguro/PagBank only accepts payments in Brazilian Real (BRL)：订单使用的是其他货币。
订单处于 On hold 状态，备注为 Amount/currency does not match：PagBank 报告的付款金额或币种与订单总额不符，例如订单在付款页面创建后被编辑过。请在 PagBank 中比对金额，然后手动完成或退款。
退款时出现与令牌相关的错误信息：付款是在沙盒或正式环境中完成的，而该环境的令牌缺失或被拒绝。请输入正确的令牌后重试。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会沿用最后已知的状态继续运行。
卸载
停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。只有在 Delete Data on Uninstall 已开启时，网关设置、插件的其他选项及其日志才会被删除；否则它们会保留，以便日后重新安装。现有订单会保留其付款备注、交易 ID 和 PagBank 数据。
PagSeguro 和 PagBank 是其各自所有者的商标。本插件与 PagSeguro 或 PagBank 无关联，也未获得其认可。