VibeFox Iugu for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. Without WooCommerce the plugin refuses to activate.

PHP: 8.0 or later.

Store currency: Brazilian Real (BRL). Iugu charges in BRL only. The payment method is hidden when the store, or the order on the Pay for order page, uses another currency, and for totals below R$ 1,00 (the Iugu minimum).

Iugu account: you need two API tokens from the Iugu dashboard, one of type "Test" and one of type "Live" (see Configuration). Iugu uses one API address for both: the token decides whether invoices are test or real. No webhook needs to be set up in Iugu.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_iugu_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Set the store currency to Brazilian Real (BRL) in WooCommerce > Settings > General.

4. Open the settings: WooCommerce > Settings > Payments > Iugu > Manage, or click Settings under the plugin name on the Plugins page.

5. Enter your VibeFox license key in the license block at the top of the page and click Activate.

6. Enter the test and live API tokens (see Configuration), keep Test mode on, turn on Enable / Disable and save.

7. Place a test order and pay it with an Iugu test card. When ready, untick Test mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Iugu. Under the gateway title the page shows TEST MODE (invoices are created with the test API token, no real charges) or LIVE. It warns you when the token of the active mode is missing (the payment method is then hidden at checkout) and when the store currency is not BRL. In the list of payment methods, Iugu is marked as needing setup until the token of the active mode is entered, and shows a test mode badge while test mode is on.

General

Enable / Disable: Enable Iugu payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Iugu.

Description: the text shown under the payment method at checkout. Default: Pay securely via Iugu. You will be redirected to complete your payment.

API credentials

Create the API tokens in Iugu Alia (alia.iugu.com): Settings > API integration > New. Create one token of type "Test" and one of type "Live".

Test mode: Use the test API token (no real charges). Default: on. While test mode is on, the checkout shows SANDBOX — Test mode enabled. No real charges. above the description. Status checks and refunds of an order always use the token of the mode in which its invoice was created, so switching the mode does not break older orders.

Test API token: the Iugu API token of type "Test". Used while test mode is on.

Live API token: the Iugu API token of type "Live" (production). Used when test mode is off. Keep it secret.

Payment notifications

Every invoice tells Iugu to report status changes to the notification URL of your store, shown in this section of the settings. It looks like https://your-site/wc-api/webhook_wc_iugu/. There is nothing to configure in Iugu. An additional account-wide trigger (gatilho) pointing to the same URL is harmless. Notifications carry no payment data the store trusts: the invoice is always read back from the Iugu API (status, amount, currency) before the order changes.

The plugin reacts to the Iugu events that can change an invoice status: invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action and invoices. For each of them it reads the invoice and applies its status:

paid: the order is marked paid after the amount and currency check.

authorized or in_analysis: the card payment waits for capture or is under analysis. The order is put on hold.

partially_paid: the invoice was paid partially. The order is put on hold.

expired: the invoice expired without payment. The order becomes Failed and can be paid again.

canceled: the invoice was canceled. The order is cancelled.

refunded: the invoice was refunded in Iugu. The order becomes Refunded.

chargeback: the card holder disputed the payment. A paid order is put on hold.

Other events and invoices that do not belong to an order of this store are answered with OK and ignored. Without notifications, an order is checked only when the customer returns to the store from the Iugu page.

Advanced

Debug log: Log API requests and notifications in WooCommerce > Status > Logs, source wcp_iugu_gateway, without tokens or customer data. Errors are always logged. Default: off.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default Iugu) and places the order. A valid billing e-mail is required. The plugin creates an Iugu invoice for the order total in BRL, due in 3 days, and sends the customer to the Iugu invoice page. There the customer pays by credit card, boleto or PIX, with the methods enabled in your Iugu account. The customer's name and e-mail are passed to Iugu, plus CPF/CNPJ, street number and neighbourhood from the "Brazilian Market on WooCommerce" checkout fields when present. Phone and address are sent only in the format Iugu accepts (Brazilian phone numbers, Brazilian addresses with an 8-digit CEP).

After paying, the customer returns to the order received page of your store. The order is marked paid only after Iugu confirms it: the invoice is read from the Iugu API when the customer returns and when Iugu sends a notification. If the customer generated a boleto or PIX code and came back before paying, the order is put on hold until Iugu confirms the payment. WooCommerce's unpaid-order timer does not cancel orders whose Iugu invoice is still open.

If the invoice was canceled or has expired and the order can still be paid, the customer lands on the Pay for order page with The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. When the customer pays again, the plugin sends the customer back to the same open invoice if the amount is unchanged. Otherwise it cancels the old invoice in Iugu and creates a new one, so one order cannot be paid twice through two open invoices. If an older invoice is paid anyway, the payment is still matched to the order.

If Iugu cannot create the invoice, the customer sees a short message, for example Iugu could not create the invoice: with the reason and a request to check the billing details, or Could not connect to Iugu. Please try again in a moment. The technical reason is added to the order notes and the log.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time payments only. It has no on-site card form, saved cards, subscriptions or recurring billing, payment booklets (carnê), split payments or installment settings — use the Iugu page settings for installments. The payment methods offered on the Iugu page cannot be chosen in the plugin settings: all methods enabled in your Iugu account are offered.

Orders and refunds

Order statuses

Pending payment: the invoice was created and the customer has not paid yet.

Processing or Completed: Iugu confirmed the payment. WooCommerce sets the usual status for a paid order. The order note shows the Iugu invoice ID and the payment method (credit card, boleto or PIX). The transaction ID is the Iugu invoice ID, and on the order screen it links to the invoice in Iugu.

On hold: the customer generated a boleto or PIX and returned to the store (payment pending), the card payment is authorized but not captured yet (capture it in Iugu, and the order is completed once Iugu reports the invoice paid), the payment is under analysis, the invoice was paid only partially, a chargeback was opened, or the paid amount or currency did not match the order. A payment that arrives after the order had been cancelled also puts it on hold instead of reopening it silently. The order notes tell which.

Failed: the invoice expired without payment. The customer can pay the order again.

Cancelled: the invoice was canceled in Iugu.

Refunded: the invoice that paid the order was refunded in Iugu.

If another invoice of the same order is paid as well, the order is not changed again. A note asks you to refund the duplicate payment in Iugu.

Refunds

Open the order, click Refund, enter the amount and click Refund via Iugu. The refund is sent with the token of the mode the invoice was created in.

Credit card: full or partial refunds.

PIX: full refunds only.

Boleto: cannot be refunded through Iugu. Return the money to the customer by bank transfer, then record the refund manually without Refund via Iugu.

Only paid invoices can be refunded, and not more than the amount still refundable in Iugu. A refund counts as done only when Iugu confirms it. If Iugu refuses the refund or does not confirm it, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the invoice ID and the reason.

A full refund made in the Iugu dashboard sets the order to Refunded. Partial refunds made in the dashboard are not imported.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Iugu. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Iugu is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Iugu does not appear at checkout: check that the license is active, Enable / Disable is on and the token of the active mode is set: Test API token in test mode, Live API token in live mode. The store currency must be BRL and the order total at least R$ 1,00. The settings page shows a warning when the token or the currency is wrong.

The payment went through, but the order stays Pending payment: the notification from Iugu did not reach your store or could not be checked. Turn on Debug log and look at WooCommerce > Status > Logs, source wcp_iugu_gateway. Check that your site is reachable from the internet at the notification URL shown in the settings and that the token of the mode the invoice was created in is still entered. The order is also checked when the customer returns to the store after paying.

Notification answers verification failed: the invoice could not be read from the Iugu API at that moment, for example because of a network error or a wrong token. Iugu retries the notification.

Notification answers invalid invoice id: the notification had no valid invoice ID. Nothing is changed.

Order is On hold: read the order notes. A boleto or PIX is still unpaid, a card payment waits for capture, the payment is under analysis, partially paid or disputed, the paid amount did not match the order, or the payment came after the order was cancelled.

The customer sees "Iugu payments are not available right now": the API token is missing or wrong. Check the token of the active mode.

Refund fails: read the message. Boleto payments cannot be refunded through Iugu, PIX payments can be refunded in full only, and only paid invoices can be refunded. If Iugu did not confirm the refund, check the invoice in Iugu before trying again.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Developers can change the invoice request, for example limit the payment methods with payable_with, with the filter wc_igu_invoice_data.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Iugu is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Iugu.