VibeFox Iugu for PrestaShop — 帮助

要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。

货币：巴西雷亚尔（BRL）。Iugu 仅以 BRL 收费。对于使用其他货币的购物车，以及总额低于 R$ 1.00（Iugu 的最低金额）的购物车，将隐藏该付款方式。

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

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Iugu Gateway，然后点击 Configure。

3. 在配置页面顶部的许可证区块中，在 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

4. 输入测试和正式 API 令牌（参见配置），保持 Test mode 开启，开启 Enable / Disable，然后点击 Save。

5. 下一笔测试订单，并在 Iugu 页面使用 Iugu 测试付款完成支付。准备就绪后，关闭 Test mode。

安装时，模块会创建两个订单状态：Awaiting Iugu payment 和 Iugu payment on hold。PrestaShop 会为所有货币、国家和客户组提供一个新的付款模块。您可以在 Payment > Preferences 中对其进行限制。无论如何，Iugu 仅对 BRL 购物车开放。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Iugu Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，页面会显示 TEST MODE（账单使用测试 API 令牌创建，不会产生真实扣款）或 LIVE。当当前模式的令牌缺失时（此时结账页面会隐藏该付款方式），以及商店的默认货币不是 BRL 时（此时对其他货币的购物车不提供 Iugu），页面会发出警告。

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：使用测试 API 令牌，因此不会产生真实扣款。默认：on。测试模式开启时，结账页面会在描述上方显示 SANDBOX — Test mode enabled. No real charges. 订单的状态查询和退款始终使用其账单创建时所处模式的令牌，因此切换模式不会影响旧订单。

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

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

已保存的令牌不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved tokens：勾选某个令牌并点击 Save 即可将其删除。字段留空则保留已保存的值。

付款通知

Notification URL：每张账单都会要求 Iugu 将状态变化报告到您商店的这个网址。使用友好 URL 时，它的形式为：https://your-shop/module/wcp_iugu_gateway/webhook。在 Iugu 中无需进行任何配置。在账户级别添加指向同一网址的额外触发器（gatilho）也没有影响。通知中不包含商店可以信任的付款数据：在创建或修改订单之前，账单始终会通过 Iugu API 重新读取（状态、金额、货币）。

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

其他事件以及并非由您的商店创建的账单会以 HTTP 200 响应并被忽略，不会向 Iugu 发出任何请求。如果没有通知，只有在顾客从 Iugu 页面返回商店时，才会检查账单。

高级

Debug log：将 Iugu 请求和通知写入模块文件夹中的 logs/wc_igu_debug.log.php。该文件无法通过网页打开。令牌和顾客数据不会被记录。即使开关关闭，错误和警告也始终会被写入。默认：off。

Log：显示日志的大小和最新条目。点击 Clear log 即可清空。

Delete Data on Uninstall：开启后，卸载模块时会删除网关设置和日志。订单、Iugu 账单引用、退款以及模块的订单状态始终会保留，因此旧订单在重新安装后仍可正常使用。默认：off。

结账

在付款步骤中，顾客选择付款方式（默认为 Iugu）并确认。需要有效的顾客电子邮件地址。模块会按购物车总额以 BRL 创建一张 Iugu 账单，到期时间为 3 天，并将顾客引导至 Iugu 账单页面。顾客可在该页面使用信用卡、boleto 或 PIX 付款，可用方式取决于您 Iugu 账户中启用的付款方式。账单会显示 Order # 和购物车编号。顾客的姓名和电子邮件会发送给 Iugu；如果地址中填写了 Identification number 或 VAT number 字段，还会发送公司名称和 CPF/CNPJ。电话和地址仅以 Iugu 可接受的格式发送（巴西电话号码、带 8 位 CEP 的巴西地址；门牌号以 s/n 形式发送）。此时订单尚未创建。

付款后，顾客返回您的商店。只有在 Iugu 确认后，订单才会被标记为已付款：顾客返回时以及 Iugu 发送通知时，都会通过 Iugu API 读取账单。随后订单被创建，顾客会看到标准的订单确认页面，并显示 Your payment with Iugu has been received.

如果顾客生成了 boleto 或 PIX 代码，并在付款前返回，订单会以 Awaiting Iugu payment 状态创建，确认页面会显示 Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. 当 Iugu 报告款项到账时（通过通知，或顾客再次打开返回链接时），订单会变为 Payment accepted。如果顾客返回时仍无法联系到 Iugu，将显示 Payment confirmation 页面，内容为 We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again.，并带有 Check again 按钮和 Back to checkout 按钮。账单已取消或未付款即过期的订单，会在确认页面显示 Your Iugu payment was not completed. Please contact us about this order.

如果账单在订单存在之前就已取消或过期，顾客会返回结账页面，并看到 The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. 购物车会被保留。顾客再次付款时，如果金额和模式未变，模块会将其引导至同一张未结账单。否则，模块会在 Iugu 中取消旧账单并创建新账单，从而确保同一购物车不能通过两张未结账单被重复付款。如果旧账单仍然被付款，该付款仍会与购物车匹配。

如果 Iugu 无法创建账单，顾客会停留在结账页面，并看到简短提示，例如 Iugu could not create the invoice:，后面附带原因和请检查账单信息的提示；或者 Could not connect to Iugu. Please try again in a moment. 技术原因会写入日志。

即使商店处于维护模式，通知网址仍然有效，并且不会受到商店国家限制的阻止。

模块仅支持一次性付款。它没有站内银行卡表单、已保存的银行卡、订阅或定期扣款、carnê（分期付款簿）、拆分付款或分期设置——分期请使用 Iugu 页面中的设置。Iugu 页面上提供的付款方式无法在模块设置中选择：将提供您 Iugu 账户中启用的所有方式。Payment error 或 Canceled 状态的订单无法在商店中再次付款；顾客需要重新下单。

订单和退款

订单状态

No order yet：顾客已被引导至 Iugu，但尚未付款，或 Iugu 尚未确认付款。此时只存在购物车。

Payment accepted：Iugu 已确认付款。该付款以 Iugu 账单 ID 作为交易 ID 记录，并且备注中会显示账单 ID 和付款方式（信用卡、boleto 或 PIX）。

Awaiting Iugu payment：顾客带着已生成的 boleto 或 PIX 返回。当 Iugu 报告付款时，订单变为 Payment accepted。

Iugu payment on hold：卡付款已授权但尚未扣款（请在 Iugu 中扣款，Iugu 报告账单已付款后订单即完成）；付款正在审核中；账单仅部分付款；已发起 chargeback；Iugu 报告的金额或货币与购物车不一致（例如，账单创建后购物车被修改）；或者付款是在订单被取消之后才到达的。备注会说明原因。请检查订单，然后完成订单或退还付款。

Payment error：等待中订单的账单未付款即已过期。如果 Iugu 之后报告该账单已付款，订单将变为 Payment accepted。

Canceled：等待中订单的账单已在 Iugu 中取消。

Refunded：付款已通过模块或在 Iugu 后台全额退款。

如果同一购物车的另一张账单也被付款，订单不会改变。备注会提示您在 Iugu 中退还重复付款。

Iugu 付款区块

订单页面会显示一个 Iugu payment 区块，其中包含 Iugu 账单 ID（链接到 Iugu 中的账单）、付款方式、状态、Iugu 收取的金额和已退款金额、测试账单的 Test mode 标记、退款记录以及订单的 Iugu notes。

退款

在 Iugu payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Iugu。确认提示 Refund this amount through Iugu? This cannot be undone. 您需要拥有编辑订单的权限。退款使用账单创建时所处模式的令牌发送，因此该令牌必须已设置。

退款以 Iugu 实际为该账单收取的金额为准，因此在出现金额不一致的情况下，您最多可以退还顾客实际支付的金额，而不是订单总额。只有已付款的账单可以退款，且退款金额不能超过 Iugu 中仍可退还的金额。只有在 Iugu 确认退款后，退款才算完成。如果 Iugu 拒绝退款或未确认退款，区块会显示错误，并且不会记录任何退款。成功的退款会连同账单 ID 和原因一起添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会改变状态。Iugu 报告账单已付款后，即可进行退款。

模块不会创建贷项单（credit slips）。订单页面上 PrestaShop 的标准退款按钮不会通过 Iugu 退回款项。

在 Iugu 后台完成的全额退款会将订单设为 Refunded 并附带备注。在后台完成的部分退款不会被导入。

许可证密钥

模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox Iugu Gateway 许可证区块位于 Modules > Module Manager > VibeFox Iugu Gateway > Configure 页面的设置上方，是第一个区块。在 License key 中输入密钥，然后点击 Activate。此后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店中移除密钥）。其下方是 Product: presta-payment-iugu 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字会跟随后台语言显示（包含英文和俄文）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加上日期。在更改商店地址之后，或在您的账户中释放了一个域名名额之后，请点击 Check now。如果无法连接许可证服务器，模块会继续按最后一次已知的状态运行。

一个密钥只能用于一个域名：主商店的域名，包括多店铺配置中的主商店。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，Iugu 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 标签页中会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也仍可正常进行。

许可证过期后，模块会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需配置计划任务（cron）。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

Iugu 没有出现在结账页面：请检查许可证是否有效，Enable / Disable 是否已开启，以及当前模式的令牌是否已设置：测试模式下为 Test API token，正式模式下为 Live API token。购物车货币必须为 BRL，总额至少为 R$ 1.00。在 Payment > Preferences 中，请检查模块是否允许用于 BRL 货币、顾客所在国家和顾客所在客户组。如果令牌或货币有误，设置页面会显示警告。

付款已完成，但未创建订单：Iugu 的通知没有到达您的商店，或者无法核对。请开启 Debug log，并查看模块页面上的 Log 字段。请检查您的商店是否可以通过互联网访问 Notification URL，以及账单所处模式的令牌是否仍已输入。顾客付款后返回商店时，也会检查账单。

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

Notification answers busy：购物车在同一时刻正被另一个请求处理，或者订单无法创建（例如模块已禁用）。Iugu 会重试通知。日志会显示原因。

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

订单处于 Iugu payment on hold：请阅读订单区块中的 Iugu notes。卡付款等待扣款、付款正在审核中、部分付款或存在争议、付款金额与购物车不符，或付款是在订单取消之后到达的。

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

顾客看到 「This order already has an Iugu payment that the store has to review」：购物车之前的某张账单已授权、正在审核或已部分付款，但无法创建订单。请在 Iugu 中检查该账单并查看日志。

退款失败：请阅读区块中的消息。boleto 付款无法通过 Iugu 退款，PIX 付款只能全额退款，并且只有已付款的账单可以退款。如果消息提示付款是在测试或正式模式下完成的，而未设置该模式的令牌，请输入该模式的令牌。如果 Iugu 未确认退款，请先在 Iugu 中检查账单，然后再重试。

开发人员可以修改账单请求，例如在 actionWcpIuguInvoiceData 钩子中使用 payable_with 限制付款方式。

卸载

进入 Modules > Module Manager，打开 VibeFox Iugu Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，网关设置和日志将被删除。如果已关闭，所有设置都会保留，以便以后重新安装时使用。Iugu 账单引用和退款，以及订单状态 Awaiting Iugu payment 和 Iugu payment on hold，始终会保留，因此之前已付款的订单仍可退款，而延迟到达的通知在重新安装后仍能正确匹配。现有订单会保留其付款备注和交易 ID。

Iugu 是其各自所有者的商标。本模块与 Iugu 无关联，也未获得 Iugu 的认可。