VibeFox Iugu for Adobe Commerce — ヘルプ

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Currency: Brazilian Real (BRL). Iugu charges in BRL only. The payment method is hidden for carts in another currency and for totals below R$ 1,00 (the Iugu minimum). The base currency of your store can be another one, as long as the customer's cart is in BRL.

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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-iugu-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/IuguPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_IuguPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Iugu Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the test and live API tokens (see Configuration), keep Test mode at Yes, set Enable to Yes and click Save Config. Place a test order in BRL and pay it on the Iugu page with an Iugu test payment. When ready, set Test mode to No.

The module adds the Iugu payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the Iugu invoices, their processed statuses and the refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Iugu Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a payment method title of 1 to 128 characters. for an empty or too long Title; Sort order must be a whole number. for a Sort Order that is empty or not a whole number; Order total must be a non-negative number. for a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater.

While Enable is Yes, the Payment notifications row shows warnings for the settings of the default store view: Enter the API token of the active mode. Iugu is hidden until it is configured., TEST MODE: invoices use the test API token. No real charges. while test mode is on, and Iugu charges in BRL only. It is hidden for carts in other currencies. when the currency of the default store view is not BRL.

General

Enable: shows or hides Iugu at checkout. It is shown only when the API token of the current mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Iugu. Required, at most 128 characters.

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

API tokens

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: uses the test API token, so no real charges are made. Default: Yes. While it is on, customers see SANDBOX: Test mode enabled. No real charges. under the payment method. 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.

Magento stores the tokens encrypted and never shows them again. An empty field or the mask keeps the saved token. Type a new value only to change it.

Clear saved token: Test API token and Clear saved token: Live API token: set to Yes and click Save Config to delete the saved token. The switch goes back to No after saving.

Payment notifications

Payment notifications: every invoice tells Iugu to report status changes to the notification URL of your store. The row shows the URL of the default store view. It looks like https://your-store/wcpiugugateway/webhook/index/; an invoice of another store view carries the URL of that store view. 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 an order is changed.

The module 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 invoiced and moves to Processing 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. A waiting order is cancelled.

canceled: the invoice was canceled. A waiting order is cancelled.

refunded: the invoice was refunded in Iugu. A paid order gets an offline credit memo and is closed.

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

Other events and invoices that were not created by your store are answered with HTTP 200 and ignored, without a request to Iugu. Without notifications, an invoice is checked only when the customer returns to the store from the Iugu page.

Conditions

Payment from Applicable Countries: All Allowed Countries offers Iugu for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Iugu only for billing addresses in these countries.

Minimum Order Total: offer Iugu only from this order total, in the base currency of your store. Empty or 0 means no minimum. Iugu is never offered below R$ 1,00 in any case.

Maximum Order Total: offer Iugu only up to this order total, in the base currency. Empty or 0 means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number. Default: 0.

Advanced

Debug log: writes Iugu requests and notifications to var/log/wc_igu_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Tokens and customer data are not logged. Errors and warnings are always written, even when the switch is off. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Iugu invoice references and refunds always stay. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Iugu) and sees the Iugu logo, the description and the note You will be redirected to the secure Iugu invoice page. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then 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 invoice shows Order # and the order number. The customer's name and e-mail are passed to Iugu, plus the company and the CPF/CNPJ from the VAT Number of the billing address or the Tax/VAT number of the customer when present. Phone and address are sent only in the format Iugu accepts (Brazilian phone numbers, Brazilian addresses with an 8-digit CEP; the house number is sent as s/n and the other street lines as the complement).

After paying, the customer returns to 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. Magento then creates the invoice with the Iugu invoice ID as the transaction ID, sets the order to Processing and sends the order and invoice e-mails. The customer sees the standard order success page with Your payment with Iugu has been received.

If the customer generated a boleto or PIX code and came back before paying, the order stays in Pending Payment, the order e-mail is sent and the success page shows Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. The order is invoiced when Iugu reports the money. If Iugu could not be reached when the customer comes back, a Payment confirmation page shows We are confirming your payment with Iugu. Please do not pay again. with the links Check again and Back to checkout. A payment that needs your review shows Your Iugu payment needs manual review. Please contact us about this order. on the success page. A customer who comes back in another browser lands on the home page; the payment is still checked.

If the invoice was canceled or has expired, the order is cancelled (the stock goes back) and the customer is back in the cart with The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. The cart is restored. Before a new invoice is created for the same cart, the previous open invoice is canceled in Iugu, so one cart cannot be paid twice through two open invoices. If the previous invoice turns out to be paid already, that payment is applied instead of a new one.

If Iugu cannot create the invoice, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example Iugu could not create the invoice: with the reason and a request to check the billing details, A valid billing email is required for Iugu. or Could not connect to Iugu. Please try again in a moment. The technical reason is written to the log.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings, 480 minutes by default), its open Iugu invoice is canceled in Iugu and can no longer be paid. An order with a boleto or PIX waiting for payment is affected too: set the lifetime longer than the 3 days the invoice is due in if your customers pay by boleto.

The module works with the standard Magento checkout. It 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 module settings: all methods enabled in your Iugu account are offered. Iugu is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Iugu, but Iugu has not confirmed the payment yet, or a boleto or PIX is waiting for payment. There is no invoice.

Processing: Iugu confirmed the payment. The invoice is created with the Iugu invoice ID as the transaction ID, and a note shows the invoice ID, the payment method (credit card, boleto or PIX) and how it was confirmed.

On Hold: the card payment is authorized but not captured yet (capture it in Iugu, and the order is invoiced once Iugu reports the invoice paid), the payment is under analysis, the invoice was paid only partially, or a chargeback was opened on a paid order. The notes explain it. An unpaid order is first moved from Pending Payment to Processing and then put on hold, so Unhold returns it to Processing and the Pending Payment cron does not cancel it. A later paid invoice is still invoiced, a canceled or expired invoice still cancels the order, and cancelling the order in the Admin cancels an Iugu invoice that is still pending or under analysis. Iugu does not cancel an authorized card invoice this way: release the authorization in Iugu.

On Hold after a mismatch: Iugu reported a different amount or currency than the order total. No invoice is created. Before the hold the order is moved from Pending Payment to Processing, so Unhold returns it to Processing and the Pending Payment cron does not cancel it. The note shows the amount expected and received in centavos. Check the payment in Iugu, then fulfil the order or refund the charge (see Refunds).

Canceled: the invoice was canceled or expired without payment, the payment could not be started, or the order was cancelled in Magento. If Iugu still reports a payment for a cancelled order, the order stays Canceled and a note asks you to review it and refund the charge.

Closed: the payment was fully refunded with a credit memo or in the Iugu dashboard.

If another invoice of the same cart is paid as well, the order is not changed. A note asks you to refund the duplicate payment in Iugu. The notes are order comments that the customer does not see.

Iugu payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Iugu invoice ID, Iugu mode, Iugu payment method, Requested amount (centavos), Received amount (centavos) and Received currency. The customer sees only the payment method title. The Information tab also shows the Iugu payment history block with every Iugu invoice of the order (the invoice ID linked to the invoice page in Iugu, the mode, the status, the requested and received amounts, the payment method and the due date) and the Iugu refund history. The block is shown also when the module is disabled.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Iugu in BRL. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Iugu.

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 create a credit memo with Refund Offline.

Refunds count from the amount Iugu actually took for the invoice, minus the amounts already refunded. The refund is sent with the token of the mode the invoice was created in, so that token must be set. A refund counts as done only when Iugu confirms it. If Iugu refuses the refund or does not confirm it, Magento shows the error and the credit memo is not created. After an unconfirmed result, further online refunds of the order are blocked until you check the invoice in Iugu; retrying the same refund checks Iugu again and never sends a second refund. A full refund closes the order. Refunds are available once Iugu has confirmed the payment and the order has an invoice.

A full refund made in the Iugu dashboard creates an offline credit memo for the invoice, closes the order and adds a note. Partial refunds made in the dashboard are not imported, and online refunds of that order are then refused with Iugu and native refunded amounts differ. Reconcile them before another refund. Record the same amount with a Refund Offline credit memo.

Charge without an invoice: after a mismatch the order has no invoice, so it cannot be refunded with a credit memo. The Iugu payment history block then offers Refund actual charge: enter the amount in BRL (the amount not refunded yet is filled in) and optionally a reason, click the button and confirm Refund this amount through Iugu? This cannot be undone. You need the permission for credit memos. No credit memo is created and the order status does not change; a note records the amount and the reason. The same limits for card, PIX and boleto apply.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Iugu Gateway is the first row of the VibeFox Iugu Gateway group in Stores > Configuration > Sales > Payment Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-iugu and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Iugu does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the token of the active mode is set: Test API token in test mode, Live API token in live mode. The cart currency must be BRL and the total at least R$ 1,00. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. The Payment notifications row 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. Set Debug log to Yes and look at the Log field. Check that your store is reachable from the internet at the notification URL and that the token of the mode the invoice was created in is still entered. The invoice is also checked when the customer returns to the store after paying. A boleto or PIX order stays in Pending Payment until the customer actually pays.

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

Notification answers busy: the order was being processed by another request at the same moment, or an error occurred while the order was being updated. Iugu retries the notification. The log shows the reason.

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

The notification URL shows method not allowed in the browser: this is normal. The URL accepts only notifications sent by Iugu.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. The order is confirmed by a later notification or when the customer returns.

A boleto order was cancelled before the customer paid: the Magento cron cancelled it after the Pending Payment Order Lifetime, and the Iugu invoice was canceled with it. Increase the lifetime in Stores > Configuration > Sales > Sales > Orders Cron Settings.

Order is On Hold: read the order notes. A card payment waits for capture, the payment is under analysis, partially paid or disputed, or the paid amount did not match the order.

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

The customer sees "This order already has an Iugu payment that the store has to review": an earlier invoice of the cart is authorized, under analysis or partially paid, but it could not be applied. Check the invoice in Iugu and the log.

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 the message says the invoice was created in test or live mode and that API token is not configured, enter the token of that mode. If Iugu did not confirm the refund, check the invoice in Iugu before trying again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) is refunded with Refund actual charge in the Iugu payment history block.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Developers can change the invoice request, for example limit the payment methods with payable_with, in an observer of the Magento event wc_igu_invoice_data.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_IuguPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_IuguPayment to remove the data, then bin/magento module:disable Vibefox_IuguPayment, delete the folder app/code/Vibefox/IuguPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Iugu invoice references and refunds are always kept, so orders paid before can still be refunded and late notifications are still matched after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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