VibeFox Pagar.me for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce，插件无法启用。

PHP：8.0 或更高版本。

货币：巴西雷亚尔（BRL）。若店铺货币（或在 Pay for order 页面中的订单货币）不是 BRL，则隐藏此付款方式。

Pagar.me 账户：您需要 Pagar.me 账户的密钥：测试密钥（sk_test_...），以及在正式上线时使用的正式密钥（sk_...）。它们位于 Pagar.me 控制台的 Development > Keys 下。仅使用密钥；不需要公开密钥（pk_...）。只能提供您的 Pagar.me 账户中已启用的付款方式。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_pagarme_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Pagar.me > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 输入测试密钥；正式上线时，再输入正式密钥。

6. 在 Pagar.me 控制台中，使用设置中显示的 URL 创建 Webhook（参见“配置”）。

7. 开启 Enable / Disable 并保存。在开启 Test mode 的情况下进行测试付款，然后关闭它以接收真实付款。

配置

所有设置都在一个页面中：WooCommerce > Settings > Payments > Pagar.me。标题下方，页面会显示当前模式：TEST MODE（付款使用测试密钥创建，不会产生真实扣款）或 LIVE。当当前模式的密钥缺失时（此时结账页面中会隐藏该付款方式）、测试密钥不是以 sk_test_ 开头时、正式密钥不是以 sk_ 开头或是测试密钥时，以及店铺货币不是 BRL 时，页面都会发出警告。在付款方式列表中，Pagar.me 会被标记为需要设置，直到输入当前模式的密钥；测试模式开启时，还会显示测试模式标记。

常规

Enable / Disable：Enable Pagar.me payments 用于开启或关闭此付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。默认：Pagar.me。

Description：结账时显示在付款方式下方的文字。默认：Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

API 密钥

从 Pagar.me 控制台复制密钥：Development > Keys。Pagar.me 对测试和正式付款使用同一个 API 地址；由密钥决定付款是测试还是真实付款。

Test mode：Use the test secret key (no real charges)。测试模式开启时，结账页面会显示 TEST MODE 提示。订单的状态查询和退款始终使用其付款创建时所处模式的密钥。默认：开启。

Test secret key：Pagar.me 测试密钥（sk_test_...）。测试模式开启时使用。

Live secret key：Pagar.me 正式密钥（sk_...）。测试模式关闭时使用。请妥善保管。

1.0 版本中的单一密钥会自动迁移：测试密钥会移入 Test secret key 并开启测试模式；否则它保留为正式密钥，并关闭测试模式。

付款页面

Payment methods：在 Pagar.me 付款页面中提供的付款方式。请只选择您的 Pagar.me 账户中已启用的方式。默认：Credit card、PIX 和 Boleto。

Boleto due in (days)：boleto 到期前的天数，范围为 1 至 30。在 Pagar.me 确认付款之前，订单将保持 On hold 状态。默认：3。

付款通知（Webhook）

在 Pagar.me 控制台中打开 Settings > Webhooks，并使用本部分显示的 URL 创建 Webhook。其格式类似 https://your-site/wc-api/webhook_wc_pagarme/。请与设置中显示的内容完全一致地复制。

选择以下事件：

Webhook 不需要密码或签名。其内容永远不会被视为可信：店铺只从中提取 Pagar.me 订单 ID，并使用订单创建时所处模式的密钥通过 Pagar.me API 读取该订单。同一 Pagar.me 账户中其他店铺的订单通知会被忽略。没有 Webhook 时，之后才付款的 PIX 和 boleto 只有在顾客返回店铺时才会得到确认。

高级

Debug log：Log API requests and notifications 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_pagarme_gateway。错误始终会被记录。日志不包含密钥和顾客数据。默认：关闭。

Delete data on uninstall：Remove the gateway settings and logs when the plugin is deleted。默认：关闭。

结账

顾客选择付款方式（默认为 Pagar.me）并下单。必须提供有效的账单邮箱。插件会为订单总额创建一个 BRL 金额的 Pagar.me 订单，其中包含订单商品行、运费和费用（如果商品行无法精确相加，则使用一行包含订单号的 Order #），然后将顾客转到 Pagar.me 付款页面。顾客的姓名、邮箱，以及针对巴西的电话号码和账单地址，都会传递给 Pagar.me。若存在 Brazilian Market on WooCommerce 插件的字段，CPF 或 CNPJ 将取自这些字段；否则顾客需要在 Pagar.me 页面中输入。

付款后，顾客会返回您的店铺。只有在 Pagar.me 确认后，订单才会被标记为已付款：店铺通过 API 读取 Pagar.me 订单，且已付金额和货币必须与订单一致。已完成的银行卡、PIX 或 boleto 付款会将订单标记为已付款。已生成但尚未付款的 PIX 或 boleto 会使订单保持 On hold，直到 Pagar.me 通过 Webhook 确认付款。

如果顾客未付款就返回，或付款被拒绝或取消，他会进入 Pay for order 页面，并看到 The Pagar.me payment was not completed. You can pay the order below. 或 The Pagar.me payment was declined or canceled. You can try again below.

顾客再次付款时，如果金额和模式相同，则会复用仍然打开的 Pagar.me 付款页面；否则，会先在 Pagar.me 中关闭它，再创建新的付款页面。如果之前的尝试在此期间已付款，或其 PIX 或 boleto 仍在等待，订单会在无需再次付款的情况下更新。如果无法关闭之前的页面，它会保持与订单关联，因此在该页面上完成的付款仍会被记录。

如果 Pagar.me 无法发起付款，顾客会看到简短的提示，例如 Could not connect to Pagar.me. Please try again in a moment.，或 Pagar.me 关于账单信息无效的消息。技术原因会被添加到订单备注中。

该付款方式适用于经典结账、Checkout 区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。

本插件在您的结账页面中没有银行卡表单，不支持保存银行卡、订阅或定期付款、分期规则、拆分付款（市场）、仅授权的银行卡付款，也不支持 Pagar.me Hub 集成。

订单与退款

订单状态

Pending payment：顾客已被转到 Pagar.me，但尚未付款或尚未生成 PIX 或 boleto。备注中会显示 Pagar.me 订单 ID 和模式。

Processing：付款已确认。这是付款后 WooCommerce 的标准状态；仅包含虚拟可下载商品的订单会变为已完成（Completed）。订单备注会显示 Pagar.me 订单 ID 和付款方式。交易 ID 即为 Pagar.me 订单 ID（or_...）。

On hold：已生成 PIX 或 boleto（或银行卡付款正在审核中）并等待付款；或 boleto 只付了部分金额；或已付金额或货币与订单不一致；或订单取消后收到了付款；或顾客切换付款方式后，订单在 Pagar.me 中被付款；或已付款订单上发生了拒付（chargeback）。订单备注会说明原因。请检查订单并将其设为 Processing，或在 Pagar.me 中退款。

Failed：付款失败，或 Pagar.me 订单已取消或已过期（例如未付款的 boleto）。只有未付款订单的最后一次尝试才能将其设为 Failed。顾客可以重新付款。

Refunded：付款已在 Pagar.me 中退款或取消。

每个 Pagar.me 状态只会应用一次，因此重复的 Webhook 或返回不会添加备注、邮件或库存扣减。已付款订单永远不会被改回待付款或失败状态，已取消或已退款的订单也绝不会被重新打开。如果同一个 WooCommerce 订单的第二个 Pagar.me 订单被付款，备注会提示您在 Pagar.me 控制台中退还重复付款。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Pagar.me（按钮会显示您的付款方式标题）。支持对银行卡和 PIX 付款进行全额和部分退款，退款金额不得超过 Pagar.me 中仍可退款的金额。退款会使用付款时所处模式的密钥发送。只有在 Pagar.me 确认后，退款才会被记录；否则 WooCommerce 会显示错误，例如 Pagar.me refused the refund: ... 或 Pagar.me did not confirm the refund，并且不会记录退款。成功的退款会连同扣款 ID 添加到订单备注中。

Boleto 付款只能退款到顾客的银行账户。请在 Pagar.me 控制台中退款，然后手动在 WooCommerce 中记录退款，无需使用 Refund via Pagar.me。

在 Pagar.me 控制台中进行的全额退款或取消会通过 Webhook 送达，并将订单设为 Refunded。拒付会添加备注，并将处于 Processing 或 Completed 状态的订单设为 On hold。

许可证密钥

本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Pagar.me 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从此站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

一个密钥只适用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账页面不会向顾客显示 Pagar.me。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也仍然可以进行。

许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账页面中没有 Pagar.me：请检查许可证是否有效、Enable / Disable 是否开启、当前模式的密钥是否已设置（测试模式为 Test secret key，正式模式为 Live secret key），以及店铺货币是否为 BRL。设置页面会针对每种情况显示警告。

付款已完成，但订单仍为 Pending payment 或 On hold：Webhook 没有正常工作。请在 Pagar.me 控制台中检查您所用账户和模式下是否存在该 Webhook，其 URL 是否与设置中显示的完全一致，以及上面列出的事件是否已选中。顾客返回店铺时，订单也会被检查。

Webhook 返回 verification failed, retry later：店铺无法通过 API 读取 Pagar.me 订单，例如该模式的密钥缺失或 API 未响应。Pagar.me 会重试 Webhook。

Webhook 返回 busy, retry later：订单正被另一个请求同时更新。Pagar.me 会重试 Webhook。

Webhook 返回 unknown order：该 Pagar.me 订单并非由本店铺创建，例如同一账户中另一家店铺的订单。不会做任何更改。

顾客看到 This order is already being processed：一个 Webhook 或顾客的返回正在同时更新订单。顾客稍后可以重试。

顾客看到 Pagar.me payments are not available right now：密钥错误或缺失。请检查当前模式的密钥。

顾客看到 Pagar.me could not start the payment：Pagar.me 拒绝了账单信息。消息会指出问题；完整原因在订单备注中。

顾客看到 Pagar.me only supports payments in Brazilian Real (BRL)：订单使用的是其他货币，例如由于使用了货币切换插件。

付款后订单处于 On hold：请阅读订单备注。PIX 或 boleto 正在等待付款，已付金额或货币不符，或付款是在订单取消后到达的。

Boleto 退款失败：boleto 付款无法通过 API 退款。请在 Pagar.me 控制台中退款，并手动记录退款。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将沿用最近一次已知的状态继续工作。

卸载

停用插件会保留所有数据。要移除插件，请在 Plugins 页面中停用并删除。此插件的许可证密钥和许可证状态始终会被删除。网关设置和插件日志只有在 Delete data on uninstall 开启时才会被删除；否则它们会保留，以便日后重新安装时使用。现有订单会保留其付款备注、交易 ID 和 Pagar.me 数据。

Pagar.me 是其各自所有者的商标。本插件与 Pagar.me 无关联，也未获得 Pagar.me 的认可。