VibeFox Iugu for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

货币：巴西雷亚尔（BRL）。Iugu 仅以 BRL 收费，因此商店需要在 System > Localisation > Currencies 中设置 BRL 货币。当客户结账所用的货币不是 BRL，或订单总额低于 R$ 1,00（Iugu 的最低金额）时，该付款方式会被隐藏。

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

CPF/CNPJ（可选）：OpenCart 没有自己的 CPF 字段。如果您添加了名称包含 CPF 或 CNPJ 的客户或地址自定义字段（Customers > Custom Fields），其值将被传递给 Iugu。

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

安装

下载文件是一个压缩包，包含两个 OpenCart 版本的安装包。请先在您的电脑上解压。压缩包中有 README.txt、OpenCart 3 安装包 wcp_iugu_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_iugu_gateway.ocmod.zip。只安装适用于您 OpenCart 版本的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 wcp_iugu_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将此安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Iugu Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见 License key）。

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

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

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 wcp_iugu_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Iugu Gateway，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥和 API 令牌。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见付款通知）。

新安装默认付款方式为关闭，测试模式为开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Iugu Gateway > Edit。左侧列出各个部分；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会显示 TEST MODE（发票使用测试 API 令牌创建，不会产生真实扣款）或 LIVE。当当前模式的令牌缺失时（此时结账页面会隐藏该付款方式），以及当商店默认货币不是 BRL 时（此时不会为其他货币提供 Iugu），页面会发出警告。如果您没有修改扩展的权限，页面只显示设置，无法保存。

保存时，Title 不能为空或超过 128 个字符，Sort Order 必须是整数，Total 必须是 0 或更大的数字，并且所选的地理区域和订单状态必须存在。否则不会保存任何内容，错误信息会指出具体字段。

Iugu

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

Title：客户在结账时看到的付款方式名称，也是订单中保存的付款方式名称。默认：Iugu。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中显示给客户的文字，位于确认按钮上方。默认：通过 Iugu 安全支付。您将被重定向以完成付款。

Sort Order：Iugu 在结账付款方式中的位置。留空或输入整数。

Geo Zone：仅对所选地理区域中的付款地址提供 Iugu。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单需要达到的结账总额（以商店默认货币计）才会提供 Iugu。留空则对任何金额都提供 Iugu。Iugu 本身要求至少 R$ 1,00。

API 凭据

在 Iugu Alia 中创建 API 令牌（本节中的链接指向该处）：Settings > API integration > New。创建一个类型为 "Test" 的令牌和一个类型为 "Live" 的令牌。

Test mode：使用测试 API 令牌，因此不会产生真实扣款。默认：开启。测试模式开启时，客户在 Confirm Order 步骤中会在说明上方看到 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 the saved token on save，然后点击 Save。

付款通知

Notification URL：每张发票都会让 Iugu 将状态变化报告到您商店的这个 URL。在 OpenCart 3 中，其格式类似 https://your-store/index.php?route=extension/payment/wcp_iugu_gateway/webhook；在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_iugu_gateway/payment/wcp_iugu_gateway.webhook。它必须能从互联网访问。在 Iugu 中无需进行任何配置。指向同一 URL 的账户级附加触发器没有害处。通知中不包含商店可以信任的付款数据：在订单变更之前，发票始终会从 Iugu API 重新读取（状态、金额、货币）。

扩展会响应本节列出的 Iugu 事件：invoice.status_changed、invoice.refund、invoice.released、invoice.dunning_action 和 invoices。对于每个事件，扩展都会读取发票并应用其状态：

对于尚无状态的订单，如果其发票已过期或被取消，订单将保持无状态，以便客户可以再次付款。其他事件以及并非由您的商店创建的发票会以 HTTP 200 响应并被忽略，不会向 Iugu 发出任何请求。如果没有通知，只有在客户从 Iugu 页面返回商店时才会检查发票。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Iugu 通过通知或在客户返回时报告了发票之后，订单才会获得状态；发票始终从 Iugu 重新读取。下面的每个字段都列出您的 OpenCart 订单状态。

Order Status After Payment：在经过验证的 Iugu 付款之后设置。默认：处理中。

Awaiting Iugu Payment Status：客户带着已生成的 boleto 或 PIX 从 Iugu 页面返回；Iugu 稍后会确认款项。默认：待付款。

Iugu Payment On Hold Status：信用卡付款已授权但未捕获、付款正在审核、部分付款、拒付（chargeback）、金额或货币与订单不符，或在订单取消后才收到付款。备注会说明原因；请手动检查。默认：待付款，因为 OpenCart 没有“保留”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Invoice Expired Status：等待中的订单的发票在未付款的情况下已过期。如果 Iugu 之后报告其已付款，订单将获得付款后的状态。默认：失败。

Invoice Canceled Status：等待中的订单的发票已在 Iugu 中取消。默认：已取消。

Refunded Status：在订单页面或 Iugu 后台将付款全额退款后设置。默认：已退款。

高级

Debug log：将 API 请求和通知写入 OpenCart 日志文件夹（storage/logs）中的 wc_igu_debug.log.php。该文件无法通过网页打开。令牌和客户数据（电子邮件、电话、CPF）从不记录。即使开关关闭，错误和警告仍会始终写入。默认：关闭。

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

Delete data on uninstall：开启时，卸载扩展会删除网关设置和日志。订单、Iugu 发票引用和退款始终保留，因此重新安装后旧订单仍可正常使用。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。API 令牌不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 API 令牌会保留。

结账

在 Payment Method 步骤中，客户选择付款方式（默认为 Iugu）。在 Confirm Order 步骤中，客户会看到您的说明以及提示 You will be redirected to the Iugu invoice page to pay by credit card, boleto or PIX. OpenCart 在此步骤创建订单，此时仍无状态。当客户点击 Confirm Order 时，扩展会为订单总额创建一张以 BRL 计价、3 天后到期的 Iugu 发票，并将客户带到 Iugu 发票页面。需要有效的电子邮件地址。发票上会显示 Order # 和订单号。客户在那里可以使用信用卡、boleto 或 PIX 付款，可用方式取决于您 Iugu 账户中启用的付款方式。客户的姓名和电子邮件会传递给 Iugu；如果名为 CPF 或 CNPJ 的自定义字段包含 11 或 14 位数字，其中的 CPF/CNPJ 也会一并传递。电话和地址仅以 Iugu 接受的格式发送（巴西电话号码，以及带 8 位 CEP 的巴西地址；门牌号以 s/n 发送）。

在 OpenCart 4 中，客户在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中），然后点击结账页面底部的 Confirm Order。OpenCart 4 默认不要求付款地址；此时扩展会获取配送地址及其 CPF/CNPJ 自定义字段。

付款后，客户会返回您的商店。只有在 Iugu 确认后，订单才会被标记为已付款：客户返回时以及 Iugu 发送通知时，都会从 Iugu API 读取发票。随后，订单会以 OpenCart 的标准方式获得状态，发送常规的订单邮件并更新库存，客户会看到 OpenCart 的订单成功页面。

如果客户已生成 boleto 或 PIX 代码并在付款前返回，订单会获得 Awaiting Iugu Payment Status，成功页面会显示 Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. 当 Iugu 报告款项到账时（通过通知，或客户再次打开返回链接时），订单会转为已付款状态。对于处于保留状态的订单，成功页面会显示 We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. 如果客户返回时无法连接到 Iugu，或 Iugu 尚未报告付款，则会显示一个 Payment confirmation 页面，内容相同，并带有 Check again 和 Back to checkout 按钮。

如果发票已取消或已过期，客户会返回结账页面，并显示 The Iugu invoice was not paid (it was canceled or has expired). Your cart is kept: confirm the order again to pay. 如果订单因其 Iugu 发票被取消而已被取消，提示信息为 Your order was cancelled because its Iugu invoice was canceled. 如果购物车已经为空（boleto 或 PIX 订单在发票过期前已进入成功页面），客户会看到一个 Payment confirmation 页面，内容为 The Iugu invoice of order #... was not paid (it was canceled or has expired), so the order will not be shipped. To buy these items, please place a new order.（或取消提示），并带有 Continue 按钮。在 OpenCart 4 中，这些提示显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则会更新结账的订单，因此在发票过期或取消后，客户会用新发票支付同一订单。但同一购物车只会付款一次。在创建新发票之前，扩展会检查该购物车的早前发票：如果其中一张已付款，则应用该付款，客户进入成功页面；如果同一订单仍有金额和模式相同的未结发票，客户会被送回该发票；其他未结发票会在 Iugu 中取消。如果较早的发票仍然被付款，付款依然会被匹配，并且对已付款购物车的重复付款会附加备注予以标记。购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在此期间已被关闭（例如 boleto 已过期或您取消了订单），客户会被带回结账页面，并显示 The Iugu invoice was not paid (it was canceled or has expired). Your cart is kept: confirm the order again to pay.；如果订单在关闭前已付款，则显示 This order was closed by the store, so it will not be shipped. Your cart is kept: confirm the order again to pay. 如果订单已经生成，且购物车中现在是新的购买内容，Confirm Order 会重新加载结账页面。两种情况下，下一次点击 Confirm Order 都会为购物车支付一个新订单。

如果 Iugu 无法创建发票，客户会停留在 Confirm Order 步骤，并看到简短提示，例如 Iugu could not create the invoice: 后附原因，并请您检查账单信息；或 Could not connect to Iugu. Please try again in a moment. 技术原因会写入日志。

商店处于维护模式时，通知 URL 也能正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动动作，放行通知和客户的返回请求。

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

订单和退款

订单状态

无状态（缺失订单）：客户已被送至 Iugu 但尚未付款，发票已过期或被取消，或 Iugu 尚未确认付款。在 Sales > Orders 中，这类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Order Status After Payment（默认 处理中）：Iugu 已确认付款。备注会显示发票 ID 和付款方式（信用卡、boleto 或 PIX）。

Awaiting Iugu Payment Status（默认 待付款）：客户带着已生成的 boleto 或 PIX 返回。Iugu 报告付款后，订单转为已付款状态。

Iugu Payment On Hold Status（默认 待付款）：信用卡付款已授权但尚未捕获（请在 Iugu 中捕获，Iugu 报告发票已付款后订单即完成），付款正在审核，发票仅部分付款，已发起拒付，Iugu 报告的金额或货币与订单不同，或付款是在订单取消后到达的。备注会对此加以说明。请检查订单，然后完成订单或退还付款。

Invoice Expired Status（默认 失败）：等待中的订单的发票在未付款的情况下已过期。如果 Iugu 之后仍报告该发票已付款，订单将转为已付款状态。

Invoice Canceled Status（默认 已取消）：等待中的订单的发票已在 Iugu 中取消。

Refunded Status（默认 已退款）：付款已通过扩展或 Iugu 后台全额退款。

如果同一订单或购物车的另一张发票也已付款，订单不会被更改。备注会要求您在 Iugu 中退还重复付款。备注是订单 History 中的条目，客户看不到。当等待中的订单之后被付款、过期或取消时，OpenCart 会将新状态通知客户。

VibeFox Iugu Gateway 选项卡

在 Sales > Orders 中打开一个使用 Iugu 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Iugu Gateway 选项卡会显示 Iugu invoice 的 ID（链接到 Iugu 中的发票）；测试发票会带有 Test mode 标签，并显示 Payment method、Status、Paid / refunded 金额、退款表单、退款历史以及该订单的 Iugu notes。该选项卡对有权访问扩展的用户显示。

退款

在 VibeFox Iugu Gateway 选项卡中输入 Amount（未退款金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via Iugu。确认提示 Refund this amount through Iugu? This cannot be undone. 您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款会使用发票创建时所处模式的令牌发送，因此该令牌必须已设置。

退款以 Iugu 实际为该发票收取的金额为准，因此在金额不一致的情况下，您最多可以退还客户实际支付的金额，而不是订单总额。只有已付款的发票可以退款，且退款金额不能超过 Iugu 中仍可退款的金额。只有当 Iugu 确认退款后，退款才算完成。如果 Iugu 拒绝或未确认退款，选项卡会显示错误，并且不会记录任何退款。成功的退款会连同发票 ID 和原因一起添加到退款历史和备注中。全额退款会将订单设置为 Refunded Status，且不会通知客户，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。只有在 Iugu 报告发票已付款后，才可以退款。

在 Sales > Returns 中的商品退货不会通过 Iugu 退还款项。

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

许可证密钥

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

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

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账时不会向客户显示 Iugu。如果仍然开始了付款，客户会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍会在商店中看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 中没有此预览：商店看不到管理员登录状态，因此没有有效密钥时，付款方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现一条提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已开始的付款仍会被确认，退款也可以正常进行。

许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，许可证密钥和许可证状态总会被删除。

故障排除

结账时不显示 Iugu：请检查许可证是否有效、Enable / Disable 是否开启，以及当前模式的令牌是否已设置：测试模式下为 Test API token，正式模式下为 Live API token。客户的结账货币必须为 BRL，且总额至少为 R$ 1,00。另请检查付款地址是否位于所选 Geo Zone 中，以及订单是否达到设置中的 Total。如果令牌或货币有误，设置页面会显示警告。

付款已完成，但订单仍无状态：Iugu 的通知未能到达您的商店，或无法被核实。请开启 Debug log，并查看扩展页面上的 Log 字段。请确认您的商店可以从互联网通过 Notification URL 访问，并且发票创建时所用模式的令牌仍已填写。客户付款后返回商店时，也会检查发票。

通知返回 verification failed：当时无法从 Iugu API 读取发票，例如网络错误、令牌错误，或发票所属模式的令牌缺失。Iugu 会重试该通知。

通知返回 busy：购物车同时正在被另一个请求处理，或无法设置订单状态。Iugu 会重试该通知。日志会显示原因。

通知返回 invalid invoice id：通知中没有有效的发票 ID。不会更改任何内容。

订单处于 Iugu Payment On Hold Status：请在订单选项卡中阅读 Iugu notes。信用卡付款正在等待捕获，付款正在审核、部分付款或被争议，已付金额与订单不符，或付款是在订单取消之后到达的。

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

客户看到 "A valid billing email is required for Iugu"：订单没有有效的电子邮件地址。

客户看到 "This order already has an Iugu payment that the store has to review"：该订单较早的某张发票已授权、正在审核或已部分付款。请在 Iugu 中检查该发票并查看日志。

客户看到 This payment method is not available.：结账会话已与订单不匹配，或者该付款方式在此期间已被关闭。客户需要重新加载结账页面。

退款失败：请阅读选项卡中的信息。Boleto 付款无法通过 Iugu 退款，PIX 付款只能全额退款，并且只有已付款的发票才能退款。如果信息提示付款是在测试或正式模式下完成的，而未设置该模式的令牌，请输入该模式的令牌。如果 Iugu 未确认退款，请先在 Iugu 中检查发票，然后再重试。

对于开发者：在创建发票之前，扩展会触发 OpenCart 事件 wc_igu_invoice_data，并附带发票请求和订单，例如用于通过 payable_with 限制付款方式。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Iugu Gateway 旁边的 Uninstall（红色的 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其事件和启动动作，该动作在维护模式下放行通知和客户的返回请求）。如果 Delete data on uninstall 已开启，则其余的网关设置（标题、说明、测试模式、API 令牌、调试日志开关）和日志都会被删除；如果关闭，则会保留，以便日后重新安装时使用。Iugu 发票引用和退款始终保留，因此之前已付款的订单仍可退款，并且重新安装后迟到的通知仍会被正确匹配。现有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Iugu Gateway 旁边的 Uninstall（橙色的 − 按钮），然后点击 Delete（红色的垃圾桶按钮）以删除已上传的安装包。

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