VibeFox Iugu for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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).

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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Iugu Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

5. Place a test order and pay it on the Iugu page with an Iugu test payment. When ready, turn off Test mode.

On install the module creates two order statuses, Awaiting Iugu payment and Iugu payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences. Iugu is offered only for carts in BRL in any case.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Iugu Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields 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 default currency of the shop is not BRL (Iugu is then not offered for carts in other currencies).

Iugu

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

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

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: uses the test API token, so no real charges are made. 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.

Saved tokens are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved tokens: tick a token and click Save to remove it. An empty field keeps the saved value.

Payment notifications

Notification URL: every invoice tells Iugu to report status changes to this URL of your shop. With friendly URLs it looks like https://your-shop/module/wcp_iugu_gateway/webhook. 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 shop trusts: the invoice is always read back from the Iugu API (status, amount, currency) before an order is created or 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 created as paid (or moves to the paid status) 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 gets Payment error.

canceled: the invoice was canceled. A waiting 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 were not created by your shop 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 shop from the Iugu page.

Advanced

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

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

Delete Data on Uninstall: when on, uninstalling the module removes the gateway settings and the log. Orders, Iugu invoice references, refunds and the module's order statuses are always kept, so old orders still work after a re-install. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Iugu) and confirms. A valid customer e-mail is required. The module creates an Iugu invoice for the cart 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 cart number. The customer's name and e-mail are passed to Iugu, plus the company and the CPF/CNPJ from the Identification number or VAT number field of the address 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). No order exists yet at this point.

After paying, the customer returns to your shop. 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. The order is then created and the customer sees the standard order confirmation 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 is created in Awaiting Iugu payment and the confirmation page shows Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. The order moves to Payment accepted when Iugu reports the money, by notification or when the customer opens the return link again. If Iugu could not be reached yet when the customer comes back, a Payment confirmation page shows We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. with a Check again and a Back to checkout button. An order whose invoice was canceled or expired without payment shows Your Iugu payment was not completed. Please contact us about this order. on the confirmation page.

If the invoice was canceled or has expired before an order exists, the customer is back at checkout with The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. The cart is kept. When the customer pays again, the module sends the customer back to the same open invoice if the amount and the mode are unchanged. Otherwise it cancels the old invoice in Iugu and creates a new one, so one cart cannot be paid twice through two open invoices. If an older invoice is paid anyway, the payment is still matched to the cart.

If Iugu cannot create the invoice, the customer stays at checkout with 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 written to the log.

The notification URL works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module 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. An order in Payment error or Canceled cannot be paid again from the shop; the customer places a new order.

Orders and refunds

Order statuses

No order yet: the customer was sent to Iugu and has not paid, or Iugu has not confirmed the payment yet. Only the cart exists.

Payment accepted: Iugu confirmed the payment. The payment is recorded with the Iugu invoice ID as the transaction ID, and a note shows the invoice ID and the payment method (credit card, boleto or PIX).

Awaiting Iugu payment: the customer came back with a boleto or PIX issued. The order moves to Payment accepted when Iugu reports the payment.

Iugu payment on hold: 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, Iugu reported a different amount or currency than the cart (for example, the cart was changed after the invoice was created), or the payment arrived after the order had been cancelled. The notes explain it. Check the order and fulfil it or refund the payment.

Payment error: the invoice of a waiting order expired without payment. If Iugu still reports the invoice paid later, the order moves to Payment accepted.

Canceled: the invoice of a waiting order was canceled in Iugu.

Refunded: the payment was fully refunded through the module 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.

Iugu payment block

The order page shows an Iugu payment block with the Iugu invoice ID (linked to the invoice in Iugu), the payment method, the status, the amount Iugu took and the amount refunded, a Test mode badge for test invoices, the refund history and the Iugu notes of the order.

Refunds

In the Iugu payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Iugu. Confirm the question Refund this amount through Iugu? This cannot be undone. You need the right to edit orders. The refund is sent with the token of the mode the invoice was created in, so that token must be set.

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.

Refunds count from the amount Iugu actually took for the invoice, so after an amount mismatch you can refund up to what the customer paid, not the order total. 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, the block shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the invoice ID and the reason. A full refund sets the order to Refunded. A partial refund does not change the status. Refunds are available once Iugu has reported the invoice paid.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Iugu.

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

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Iugu Gateway is the first block on Modules > Module Manager > VibeFox Iugu Gateway > Configure, 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 shop. Below them are the line Product: presta-payment-iugu and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency must be BRL and the total at least R$ 1,00. In Payment > Preferences check that the module is allowed for the BRL currency, the customer's country and the customer's group. The settings page shows a warning when the token or the currency is wrong.

The payment went through, but no order was created: the notification from Iugu did not reach your shop or could not be checked. Turn on Debug log and look at the Log field on the module page. Check that your shop 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 shop 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, a wrong token or a missing token of the invoice's mode. Iugu retries the notification.

Notification answers busy: the cart was being processed by another request at the same moment, or the order could not be created (for example, the module is disabled). Iugu retries the notification. The log shows the reason.

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

Order is Iugu payment on hold: read the Iugu notes in the order block. A card payment waits for capture, the payment is under analysis, partially paid or disputed, the paid amount did not match the cart, 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.

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 no order could be created. Check the invoice in Iugu and the log.

Refund fails: read the message in the block. 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 payment was made in test or live mode and no token is configured, enter the token of that mode. If Iugu did not confirm the refund, check the invoice in Iugu before trying again.

Developers can change the invoice request, for example limit the payment methods with payable_with, in the hook actionWcpIuguInvoiceData.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Iugu Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete Data on Uninstall is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The Iugu invoice references and refunds and the order statuses Awaiting Iugu payment and Iugu payment on hold 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 payment notes and transaction IDs.

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