VibeFox Iugu for WooCommerce — 帮助

要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法激活。

PHP：8.0 或更高版本。

商店货币：巴西雷亚尔（BRL）。Iugu 仅以 BRL 收费。当商店或 Pay for order 页面上的订单使用其他货币时，以及订单金额低于 R$ 1,00（Iugu 最低限额）时，付款方式将被隐藏。

Iugu 账户：您需要从 Iugu 后台获取两个 API 令牌，一个类型为"Test"，一个类型为"Live"（见配置）。Iugu 对两者使用同一 API 地址：令牌决定账单是测试账单还是真实账单。无需在 Iugu 中设置 Webhook。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。

安装

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

2. 点击 Activate。

3. 在 WooCommerce > Settings > General 中将商店货币设置为巴西雷亚尔（BRL）。

4. 打开设置：WooCommerce > Settings > Payments > Iugu > Manage，或在插件列表页点击插件名称下的 Settings。

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

6. 输入测试和正式 API 令牌（见配置），保持 Test mode 开启，开启 Enable / Disable 并保存。

7. 下测试订单，并使用 Iugu 测试卡付款。准备就绪后，取消勾选 Test mode。

配置

所有设置都在同一页面：WooCommerce > Settings > Payments > Iugu。在网关标题下方，页面会显示 TEST MODE（账单使用测试 API 令牌创建，不会产生真实扣款）或 LIVE。当当前模式的令牌缺失时（此时付款方式在结账时被隐藏），以及商店货币不是 BRL 时，页面会发出警告。在付款方式列表中，在输入当前模式的令牌之前，Iugu 会标记为需要设置；测试模式开启时，还会显示测试模式徽章。

常规

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

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

Description：结账时付款方式下方显示的文字。默认：Pay securely via Iugu. You will be redirected to complete your payment.

API 凭据

在 Iugu Alia（alia.iugu.com）中创建 API 令牌：Settings > API integration > New。创建一个类型为"Test"的令牌和一个类型为"Live"的令牌。

Test mode：Use the test API token (no real charges)。默认：on。测试模式开启时，结账页面会在描述上方显示 SANDBOX — Test mode enabled. No real charges.。订单的状态查询和退款始终使用创建其账单时所用模式的令牌，因此切换模式不会影响旧订单。

Test API token：类型为"Test"的 Iugu API 令牌。测试模式开启时使用。

Live API token：类型为"Live"（正式）的 Iugu API 令牌。测试模式关闭时使用。请妥善保密。

付款通知

每张账单都会要求 Iugu 将状态变化报告到您商店的通知网址，该网址显示在设置的此部分中。格式如下：https://your-site/wc-api/webhook_wc_iugu/。无需在 Iugu 中进行任何设置。指向同一网址的账户级附加触发器（gatilho）不会造成影响。通知中不包含商店可信赖的付款数据：在订单发生任何变化之前，系统始终会通过 Iugu API 重新读取账单（状态、金额、货币）。

插件会响应可能改变账单状态的 Iugu 事件：invoice.status_changed、invoice.refund、invoice.released、invoice.dunning_action 和 invoices。对于每个事件，插件都会读取账单并应用其状态：

其他事件以及不属于本商店订单的账单会收到 OK 回复并被忽略。若没有通知，则只有在顾客从 Iugu 页面返回商店时才会检查订单。

高级

Debug log：在 WooCommerce > Status > Logs 中记录 Log API requests and notifications，来源为 wcp_iugu_gateway，不包含令牌或顾客数据。错误始终会被记录。默认：off。

Delete Data on Uninstall：Remove the gateway settings and logs when the plugin is deleted。默认：off。

结账

顾客选择付款方式（默认为 Iugu）并下单。必须提供有效的账单邮箱。插件会按订单总额以 BRL 创建 Iugu 账单，付款期限为 3 天，并将顾客引导至 Iugu 账单页面。顾客在该页面可使用您 Iugu 账户中启用的方式，通过信用卡、boleto 或 PIX 付款。顾客的姓名和邮箱会传递给 Iugu；若存在，还会传递来自"Brazilian Market on WooCommerce"结账字段的 CPF/CNPJ、门牌号和街区。电话和地址仅以 Iugu 可接受的格式发送（巴西电话号码，以及带 8 位 CEP 的巴西地址）。

付款后，顾客会返回您商店的"订单已收到"页面。只有在 Iugu 确认后，订单才会被标记为已付款：顾客返回时以及 Iugu 发送通知时，都会通过 Iugu API 读取账单。如果顾客生成了 boleto 或 PIX 付款码并在付款前返回，订单将变为保留状态，直到 Iugu 确认付款。WooCommerce 的未付款订单计时器不会取消仍有未结 Iugu 账单的订单。

如果账单已取消或已过期，而订单仍可付款，顾客会进入 Pay for order 页面，并看到提示 The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. 顾客再次付款时，如果金额未变，插件会将其引导至同一张未结账单。否则，插件会在 Iugu 中取消旧账单并创建新账单，从而确保一笔订单不会通过两张未结账单被重复付款。如果旧账单仍被付款，该付款仍会与订单匹配。

如果 Iugu 无法创建账单，顾客会看到简短提示，例如 Iugu could not create the invoice:（附原因，并请求检查账单信息），或 Could not connect to Iugu. Please try again in a moment. 技术原因会添加到订单备注和日志中。

该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它与 WooCommerce High-Performance Order Storage（HPOS）兼容。

插件仅支持一次性付款。它没有站内银行卡表单、已保存的银行卡、订阅或定期扣款、carnê（分期付款簿）、拆分付款或分期设置——分期请使用 Iugu 页面中的设置。Iugu 页面上提供的付款方式无法在插件设置中选择：提供的是您 Iugu 账户中启用的全部方式。

订单与退款

订单状态

Pending payment：账单已创建，顾客尚未付款。

Processing or Completed：Iugu 已确认付款。WooCommerce 会为已付款订单设置常规状态。订单备注会显示 Iugu 账单 ID 以及付款方式（信用卡、boleto 或 PIX）。交易 ID 即 Iugu 账单 ID，在订单页面上会链接到 Iugu 中的账单。

On hold：顾客生成了 boleto 或 PIX 并返回商店（付款待定）；银行卡付款已授权但尚未扣款（请在 Iugu 中扣款，Iugu 报告账单已付款后订单才会完成）；付款正在审核；账单仅部分付款；已发起争议（chargeback）；或实付金额或货币与订单不符。订单取消后到达的付款同样会将其变为保留状态，而不是悄悄重新打开。订单备注会说明具体原因。

Failed：账单未付款即已过期。顾客可以再次付款。

Cancelled：账单已在 Iugu 中取消。

Refunded：为订单付款的账单已在 Iugu 中退款。

如果同一订单的另一张账单也被付款，订单不会再次更改。系统会添加备注，提醒您在 Iugu 中退还重复付款。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Iugu。退款会使用创建账单时所在模式的令牌发送。

只有已付款的账单才能退款，且退款金额不得超过 Iugu 中仍可退还的金额。只有在 Iugu 确认后，退款才视为完成。如果 Iugu 拒绝或未确认退款，WooCommerce 会显示错误，且不会记录任何退款。成功的退款会连同账单 ID 和原因一起添加到订单备注中。

在 Iugu 后台进行的全额退款会将订单设为已退款。在后台进行的部分退款不会被导入。

许可证密钥

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

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

如果没有有效的密钥，结账时顾客将看不到 Iugu。如果仍然开始付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的商店管理员仍会看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件列表页和 WooCommerce 页面会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也照常可用。

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

故障排除

结账时未显示 Iugu：请检查许可证是否有效，Enable / Disable 是否开启，以及当前模式的令牌是否已设置：测试模式下为 Test API token，正式模式下为 Live API token。商店货币必须为 BRL，订单总额至少为 R$ 1,00。当令牌或货币有误时，设置页面会显示警告。

付款已完成，但订单仍为 Pending payment：Iugu 的通知未能到达您的商店，或无法被核对。请开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_iugu_gateway。请确认您的网站可以通过互联网访问设置中显示的通知网址，并且创建账单时所用模式的令牌仍已填入。顾客付款后返回商店时，也会检查该订单。

Notification answers verification failed：当时无法通过 Iugu API 读取账单，例如因为网络错误或令牌错误。Iugu 会重试通知。

Notification answers invalid invoice id：通知中没有有效的账单 ID。不会更改任何内容。

订单处于 On hold：请阅读订单备注。boleto 或 PIX 仍未付款、银行卡付款等待扣款、付款正在审核、部分付款或存在争议、实付金额与订单不符，或付款是在订单取消之后到达的。

顾客看到 "Iugu payments are not available right now"：API 令牌缺失或错误。请检查当前模式的令牌。

退款失败：请阅读提示信息。boleto 付款无法通过 Iugu 退款，PIX 付款只能全额退款，并且只有已付款的账单才能退款。如果 Iugu 未确认退款，请在 Iugu 中检查该账单后再重试。

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

开发者可以修改账单请求，例如通过 payable_with 限制付款方式，并使用 wc_igu_invoice_data 过滤器。

卸载

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

Iugu 是其各自所有者的商标。本插件与 Iugu 无关联，也未获得 Iugu 的认可或背书。