VibeFox Iugu for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Currency: Brazilian Real (BRL). Iugu charges in BRL only, so the store needs the BRL currency in System > Localisation > Currencies. The payment method is hidden when the customer's checkout currency is another one 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.

CPF/CNPJ (optional): OpenCart has no CPF field of its own. If you add a customer or address custom field whose name contains CPF or CNPJ (Customers > Custom Fields), its value is passed to Iugu.

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

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_iugu_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_iugu_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_iugu_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Iugu Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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 in BRL and pay it on the Iugu page with an Iugu test payment. When ready, turn off Test mode.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_iugu_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Iugu Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the API tokens as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the notification URL is different (see Payment notifications).

A new install starts with the payment method turned off and test mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Iugu Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 store is not BRL (Iugu is then not offered for other currencies). Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty or longer than 128 characters, Sort Order must be a whole number, Total a number of 0 or more, and the selected geo zone and order statuses must exist. Otherwise nothing is saved and the error names the field.

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, up to 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely via Iugu. You will be redirected to complete your payment.

Sort Order: the position of Iugu among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Iugu only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Iugu is offered. Leave it empty to offer Iugu for any total. Iugu itself needs at least R$ 1,00.

API credentials

Create the API tokens in Iugu Alia (the section links there): 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, customers see SANDBOX — Test mode enabled. No real charges. at the Confirm Order step, 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. To remove a saved token, tick Clear the saved token on save under the field and click Save.

Payment notifications

Notification URL: every invoice tells Iugu to report status changes to this URL of your store. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_iugu_gateway/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_iugu_gateway/payment/wcp_iugu_gateway.webhook. It must be reachable from the internet. There is nothing to configure in Iugu. An additional account-wide trigger 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 extension reacts to the Iugu events listed in this section: 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 gets the Order Status After Payment after the amount and currency check.

authorized or in_analysis: the card payment waits for capture or is under analysis. The order gets the Iugu Payment On Hold Status.

partially_paid: the invoice was paid partially. The order gets the Iugu Payment On Hold Status.

pending: a notification does not change the order. Only when the customer comes back with a boleto or PIX issued does the order get the Awaiting Iugu Payment Status.

expired: the invoice expired without payment. A waiting order gets the Invoice Expired Status.

canceled: the invoice was canceled. A waiting order gets the Invoice Canceled Status.

refunded: the invoice was refunded in Iugu. The order gets the Refunded Status.

chargeback: the card holder disputed the payment. A paid order gets the Iugu Payment On Hold Status.

An expired or canceled invoice of an order still without a status leaves the order without a status, so the customer can pay again. 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.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after Iugu has reported the invoice, by notification or on the customer's return; the invoice is always read back from Iugu. Each field below lists your OpenCart order statuses.

Order Status After Payment: set after a verified Iugu payment. Default: Processing.

Awaiting Iugu Payment Status: the customer came back from the Iugu page with a boleto or PIX issued; Iugu confirms the money later. Default: Pending.

Iugu Payment On Hold Status: card payment authorized but not captured, payment under analysis, partially paid, chargeback, amount or currency different from the order, or paid after the order was cancelled. A note explains why; check it manually. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Invoice Expired Status: the invoice of a waiting order expired without payment. If Iugu still reports it paid later, the order gets the status after payment. Default: Failed.

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

Refunded Status: set after the payment is fully refunded from the order page or in the Iugu dashboard. Default: Refunded.

Advanced

Debug log: writes API requests and notifications to wc_igu_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. Tokens and customer data (e-mail, phone, CPF) are never 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 extension removes the gateway settings and the log. Orders, Iugu invoice references and refunds are always kept, so old orders still work after a re-install. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. API tokens are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved API tokens are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Iugu). At the Confirm Order step the customer sees your description and the note You will be redirected to the Iugu invoice page to pay by credit card, boleto or PIX. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension creates an Iugu invoice for the order total in BRL, due in 3 days, and sends the customer to the Iugu invoice page. A valid e-mail is required. The invoice shows Order # and the order number. 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 the CPF/CNPJ from a custom field named CPF or CNPJ when it has 11 or 14 digits. 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).

On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. By default OpenCart 4 does not ask for a payment address; the extension then takes the address and the CPF/CNPJ custom field of the shipping address.

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. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success page.

If the customer generated a boleto or PIX code and came back before paying, the order gets the Awaiting Iugu Payment Status 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 moves to the paid status when Iugu reports the money, by notification or when the customer opens the return link again. For an order on hold the success page shows We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. If Iugu could not be reached or has not reported the payment yet when the customer comes back, a Payment confirmation page shows the same text with a Check again and a Back to checkout button.

If the invoice was canceled or has expired, the customer is back at checkout with The Iugu invoice was not paid (it was canceled or has expired). Your cart is kept: confirm the order again to pay. If the order had been cancelled because its invoice was canceled in Iugu, the message is Your order was cancelled because its Iugu invoice was canceled. If the cart is already empty (a boleto or PIX order had reached the success page before its invoice expired), the customer sees a Payment confirmation page instead, with 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. (or the cancelled message) and a Continue button. On OpenCart 4 the checkout messages are shown above the checkout page. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 updates the order of the checkout, so after an expired or canceled invoice the customer pays the same order with a new invoice. One cart is paid only once. Before a new invoice the extension checks the earlier invoices of the cart: if one is paid, that payment is applied and the customer goes to the success page; if the same order still has an open invoice with the same amount and mode, the customer is sent back to it; other open invoices are canceled in Iugu. If an older invoice is paid anyway, the payment is still matched, and a duplicate payment of a paid cart is flagged with a note. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed meanwhile (for example its boleto expired or you cancelled it), the customer is sent back to the checkout with The Iugu invoice was not paid (it was canceled or has expired). Your cart is kept: confirm the order again to pay., or, if it had been paid before it was closed, with This order was closed by the store, so it will not be shipped. Your cart is kept: confirm the order again to pay. If the order is already placed and the cart now holds a new purchase, Confirm Order reloads the checkout page. In each case the next Confirm Order pays a new order of the cart.

If Iugu cannot create the invoice, the customer stays at the Confirm Order step 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 also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action that lets the notification and the customer's return through.

The extension 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 extension settings: all methods enabled in your Iugu account are offered.

Orders and refunds

Order statuses

No status (missing order): the customer was sent to Iugu and has not paid, the invoice expired or was canceled, or Iugu has not confirmed the payment yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): Iugu confirmed the payment. A note shows the invoice ID and the payment method (credit card, boleto or PIX).

Awaiting Iugu Payment Status (default Pending): the customer came back with a boleto or PIX issued. The order moves to the paid status when Iugu reports the payment.

Iugu Payment On Hold Status (default 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, Iugu reported a different amount or currency than the order, or the payment arrived after the order had been cancelled. The notes explain it. Check the order and fulfil it or refund the payment.

Invoice Expired Status (default Failed): the invoice of a waiting order expired without payment. If Iugu still reports the invoice paid later, the order moves to the paid status.

Invoice Canceled Status (default Canceled): the invoice of a waiting order was canceled in Iugu.

Refunded Status (default Refunded): the payment was fully refunded through the extension or in the Iugu dashboard.

If another invoice of the same order or cart is paid as well, the order is not changed. A note asks you to refund the duplicate payment in Iugu. Notes are entries in the order History that the customer does not see. When a waiting order is paid, expires or is canceled later, OpenCart notifies the customer of the new status.

VibeFox Iugu Gateway tab

In Sales > Orders open an order paid with Iugu. At the bottom of the order page, next to History and Additional, the VibeFox Iugu Gateway tab shows the Iugu invoice ID (linked to the invoice in Iugu) with a Test mode label for test invoices, the Payment method, the Status, the amounts Paid / refunded, the refund form, the refund history and the Iugu notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox Iugu Gateway tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), and click Refund via Iugu. Confirm the question Refund this amount through Iugu? This cannot be undone. You need the right to modify the extension (set in System > Users > User Groups). 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, then record the refund manually.

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 tab 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 Status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status. Refunds are available once Iugu has reported the invoice paid.

Product returns in Sales > Returns do not send money back through Iugu.

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

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Iugu Gateway is the first block on Extensions > Extensions > Payments > VibeFox Iugu Gateway > Edit, 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: opencart-payment-iugu and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. 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 customer sees This payment method is not available. Please choose another one. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 customer's checkout currency must be BRL and the total at least R$ 1,00. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings. The settings page shows a warning when the token or the currency is wrong.

The payment went through, but the order stays without a status: the notification from Iugu did not reach your store or could not be checked. Turn on Debug log and look at the Log field on the extension page. 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.

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 status could not be set. 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 in the Iugu Payment On Hold Status: read the Iugu notes in the order tab. 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.

The customer sees "A valid billing email is required for Iugu": the order has no valid e-mail address.

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

The customer sees This payment method is not available.: the checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

Refund fails: read the message in the tab. 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.

For developers: before the invoice is created, the extension triggers the OpenCart event wc_igu_invoice_data with the invoice request and the order, for example to limit the payment methods with payable_with.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Iugu Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable / Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the notification and the customer's return through in maintenance mode). If Delete data on uninstall is on, the other gateway settings (title, description, test mode, API tokens, debug log switch) and the log are removed. If it is off, they are kept for a later 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 payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Iugu Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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