VibeFox Vindi 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) must be set up in System > Localisation > Currencies. Vindi charges in BRL only, so the payment method is shown only when the customer pays in BRL.

Vindi account: you need the API key of your Vindi account. The Vindi sandbox is a separate Vindi test account with its own key. Boleto, PIX and BolePix must also be enabled in your Vindi account if you want to offer them.

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_vindi_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_vindi_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_vindi_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 Vindi 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. Paste the Sandbox API key and, when you are ready, the Live API key. Choose the Offered methods.

5. Copy the webhook URL from the settings into Vindi (see Configuration).

6. Turn on Enable / Disable and click Save. Test a payment in sandbox mode, then turn off Sandbox mode to accept real payments.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_vindi_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 Vindi Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the API keys, the methods and the webhook as in steps 3 to 6 for OpenCart 3. The settings page and its fields are the same in both versions. Only the webhook URL is different (see Webhook).

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

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Vindi 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 the mode, TEST MODE or LIVE, and warns you when the API key of the current mode is empty (the payment method is then not shown at checkout) or when the default currency of the store is not BRL (the payment method is then shown only when the customer pays in BRL). Without the right to modify the extension the page shows the settings but cannot save them.

When you save, the keys are saved as typed, without spaces at the start and end. If no payment method is selected, credit card is saved and the page shows Choose at least one payment method — credit card was selected. An empty Title or one longer than 128 characters, a Sort Order that is not a whole number (negative values are allowed), a Total that is not a number of 0 or more, or a geo zone or order status that does not exist is not accepted: nothing is saved and the page shows the message, for example Enter a title for the payment method (1 to 128 characters).

Vindi

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

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

Description: the text shown to the customer at the Confirm Order step, above the payment fields. Default: Pay by credit card on the secure Vindi page, or by boleto / PIX.

Sort Order: the position of Vindi among the payment methods at checkout. Leave it empty or enter a whole number (negative values are allowed).

Geo Zone: offer Vindi 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 Vindi is offered. Leave it empty to offer Vindi for any total.

API keys

Create the keys in the Vindi dashboard under Settings > API keys: on app.vindi.com.br for live and on sandbox-app.vindi.com.br for the sandbox. Live and sandbox have separate hosts and keys. Each payment remembers where its bill was created, so checks, cancellations and refunds always use that environment.

Sandbox mode: creates new payments in the Vindi sandbox, using sandbox-app.vindi.com.br with the sandbox API key. Customers see a TEST MODE note at checkout: Vindi sandbox: no real charges. Default: on. Turn it off to accept real payments.

Live API key: the private key of the live Vindi account. It is only sent to the Vindi API.

Sandbox API key: the private key of the Vindi sandbox account.

Saved keys 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 key, tick Clear the saved key on save under the field and click Save.

Payment methods

Offered methods: the methods customers can choose. Default: credit card. The methods must also be enabled in your Vindi account.

Boleto, PIX and BolePix need the customer's CPF or CNPJ, which is asked at checkout.

Payment notifications (webhook)

The webhook tells your store that a bill was paid, cancelled, rejected or refunded. The Webhook URL field of this section shows the URL. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_vindi_gateway/webhook&token=..., on OpenCart 4 like https://your-store/index.php?route=extension/wcp_vindi_gateway/payment/wcp_vindi_gateway.webhook&token=.... It is built from the storefront address of your OpenCart installation and contains a secret token created by the extension. Copy it exactly as the settings show it. In Vindi go to Settings > Webhooks, in the live account and in the sandbox account, add this URL and select these events:

Vindi does not sign its notifications, so requests with a missing or wrong token are rejected, and every notification only makes the extension read the bill again through the Vindi API before an order changes. The URL also works while the store is in maintenance mode (on OpenCart 4 a startup action of the extension lets the webhook and the payment status page through). Vindi bills have no return URL, so without the webhook a card payment is only picked up when the customer confirms the order again with the same cart (the paid bill is then found), and a boleto or PIX payment when the customer opens the order in the account (My Account > Order History) again.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after Vindi has reported the bill; the bill is always read back from Vindi. Boleto, PIX and BolePix orders get the awaiting status as soon as the bill is issued. Each field below lists your OpenCart order statuses. OpenCart has no On hold status, so the awaiting and on-hold statuses both use Pending by default; the order notes tell them apart. You can create your own statuses in System > Localisation > Order Statuses and select them here.

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

Awaiting Vindi Payment Status: boleto, PIX or BolePix issued at checkout; Vindi confirms the money later. The payment data is added to the history comment the customer sees. Default: Pending.

Vindi Payment On Hold Status: the bill is under review at Vindi, the paid bill does not match the order (currency, amount, bill code or Vindi customer), or it was paid after the order had been cancelled. A note explains why. Default: Pending.

Payment Error Status: Vindi rejected the payment attempt of a waiting order. The customer can still pay the same bill; a later payment sets the status after payment. Default: Failed.

Canceled Status: the bill of a waiting order was cancelled at Vindi. When you set an order of this extension to this status, its pending Vindi bill is cancelled too. Default: Canceled.

Refunded Status: set after the payment is fully refunded from the order page. Default: Refunded.

Advanced

Debug log: logs API calls and notifications to wc_vdi_debug.log.php in the OpenCart logs folder (storage/logs, on OpenCart 4 system/storage/logs). The file cannot be opened from the web. Errors and warnings are always logged, even when this is off. Keys, the webhook token and customer data are never logged. 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 settings, the webhook token, the product cache and the log. Orders and the Vindi bill references of orders are kept. Default: off.

Import / Export

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

Import: paste previously exported JSON and click Import to restore the settings. The saved API keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Vindi). At the Confirm Order step the customer sees your description. When more than one method is offered, the payment box shows Pay with and a choice of credit card, boleto, PIX or BolePix. When boleto, PIX or BolePix is offered, the box also has a CPF or CNPJ field. It is required when credit card is not offered; otherwise it shows Required for boleto and PIX. The field is filled in from a custom field of the customer or the address named CPF or CNPJ when it holds a valid number. The number is checked by its check digits. If something is missing, the customer sees Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. or Please enter your CPF or CNPJ — it is required for boleto and PIX. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options; the payment box with these fields and the Confirm Order button are at the bottom of the checkout page.

When the customer clicks Confirm Order, the extension creates a Vindi customer for this cart from the payment address and a Vindi bill for the order total, in a single installment. In Vindi the bill is named Order # and the OpenCart order number.

Credit card: the customer is sent to the Vindi bill page and pays there. The order stays without a status. Vindi has no return URL for bills, so the customer is not sent back to the store automatically. The order gets its status when Vindi confirms the payment by the webhook. If the customer confirms the order again with the same cart and the bill is already paid, the paid order is confirmed and the customer sees the success page.

Boleto, PIX and BolePix: the bill is issued at once, the order gets the awaiting status and the customer lands on the OpenCart order success page. There, and in the order details of the customer account, a Payment section shows the PIX QR code, the PIX copy and paste code with a Copy code button and its expiry date, and an Open boleto button. The order e-mail and the order history of the customer contain the PIX code and the boleto link. If Vindi does not return the boleto or PIX data, the bill is cancelled and the customer sees an error.

The order is marked paid only after Vindi confirms it: the extension reads the bill from the Vindi API and checks the currency, that the bill belongs to the order (bill code and Vindi customer) and that the paid amount equals the order total. The success page and the order page of the customer account check a waiting order through the API again, at most every 15 seconds. When the payment has been received, the success page shows Your payment with Vindi has been received. While the payment is not confirmed yet it shows We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. For a cancelled order it shows This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.

While the payment is not confirmed, the success page and the order page of the customer account (for an order that waits or is on hold) also show a Check payment status button. It checks the latest Vindi bill of the order. A confirmed or waiting order goes back to the success page with its payment data. If the bill is still unpaid, the page Payment says Your payment has not been completed yet. If you have already paid, the order is confirmed as soon as Vindi reports the payment — please do not pay again. and has the buttons Pay at Vindi, Check again and Back to checkout.

OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout, so the extension pays one cart only once. If another order of the same cart is already paid, waiting for boleto or PIX, or on hold, the customer goes to the success page and no new bill is issued. A new attempt for the same order reuses its pending Vindi bill if the method, amount and environment are the same. Otherwise the previous bill is cancelled at Vindi before a new one is created, so the customer cannot pay the same cart twice. 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. After a rejected card payment or a cancelled bill the customer pays the same order again. If that order was closed without a payment meanwhile, the customer is sent back to the checkout, and the next Confirm Order pays a new order: a cancelled order shows This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid., a failed one Your Vindi payment attempt was rejected. You can try again below. On OpenCart 4 the messages of the Payment status page that lead back to the checkout are shown above the checkout page.

If Vindi cannot start the payment, the customer stays at the Confirm Order step with a short message above the button, for example to check the CPF / CNPJ, the billing address (street, postcode, city and state are required for boleto), the e-mail or the phone number, or that Vindi is temporarily unavailable. The technical reason is written to the log.

The extension takes single payments in one installment. It has no subscriptions or recurring billing, no saved cards, no installments and no card form on your site: the card is always entered on the Vindi page. The house number and district are not part of the OpenCart address, so they are not sent to Vindi.

Orders and refunds

Order statuses

No status (missing order): a card payment was started and Vindi has not confirmed it yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders. On OpenCart 4.1 such an order can also have the status Voided, which OpenCart sets when the confirm step is shown again; the extension counts it as an order without a status.

Awaiting Vindi Payment Status (default Pending): a boleto, PIX or BolePix payment is waiting. The order moves to Order Status After Payment when Vindi reports the bill paid.

Order Status After Payment (default Processing): the payment was confirmed. The order gets its status the standard OpenCart way, with the usual order e-mails and stock update. A note shows the Vindi bill, the amount and the environment.

Vindi Payment On Hold Status (default Pending): the Vindi bill is under review, the paid bill does not match the order (currency, amount, bill code or Vindi customer), or the bill was paid after the order had been cancelled. The note explains it. Check the order and the stock, then complete the order or refund the payment.

Payment Error Status (default Failed): Vindi rejected the payment attempt of a waiting order. The note shows the reason from the acquirer if there is one. The customer can still pay the same bill, and a later payment moves the order to Order Status After Payment.

Canceled Status (default Canceled): the bill of a waiting order was cancelled at Vindi. When you set an order to this status in OpenCart, its pending Vindi bill is cancelled too, so it can no longer be paid. If that is not possible, a note asks you to cancel the bill in the Vindi dashboard.

Refunded Status (default Refunded): the payment was fully refunded through the extension.

If a second bill is paid for an order that is already paid, or for another order of a cart that is already paid, the order is not changed. A note on the paid order asks you to refund one payment in Vindi. Notes are entries in the order History that the customer does not see.

VibeFox Vindi Gateway tab

In Sales > Orders open an order paid with Vindi. At the bottom of the order page, next to History and Additional, the VibeFox Vindi Gateway tab shows the Vindi bill, the Charge, the environment (with a Sandbox badge for sandbox payments), the Payment method, the Status, the amounts Paid / refunded, the refund form, the refund history, all Bills of this cart and the Vindi notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox Vindi Gateway tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), and click Refund via Vindi. Confirm the question Refund this amount through Vindi? This cannot be undone. Full and partial refunds of card and PIX payments are supported. You need the right to modify the extension (set in System > Users > User Groups). Refunds are limited to the amount Vindi actually charged, so after a mismatch you can refund up to what the customer paid, not the order total. The refund is sent in the environment of the payment (live or sandbox), so that environment's API key must be set.

A full refund also cancels the bill at Vindi and 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. A successful refund is added to the refund history and the notes with the Vindi charge and the status. If Vindi or the acquirer refuses the refund, the tab shows the error and no refund is recorded. Refunds are available once Vindi has reported the bill paid.

Vindi cannot refund boleto payments. The tab shows Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.

Product returns in Sales > Returns do not send money back through Vindi. Refunds made in the Vindi dashboard arrive by the charge_refunded webhook and are added to the notes. The order status is not changed automatically. Update it manually if needed.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Vindi Gateway is the first block on Extensions > Extensions > Payments > VibeFox Vindi 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-vindi 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, Vindi 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: bills already created are still confirmed by the Vindi webhook, 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

Vindi does not appear at checkout: check that the license is active, Enable / Disable is on, the customer pays in BRL, at least one method is selected in Offered methods and the current mode has an API key: Sandbox API key in sandbox mode, Live API key in live mode. The settings page shows a warning when the key is missing or the store currency is not BRL. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status or in the awaiting status: the webhook is not working. In Vindi check that the webhook exists in the account you use (live or sandbox), that its URL is exactly the one shown in the settings, including the token, and that the four events are selected.

Webhook answers Forbidden: the token in the URL is missing or wrong. Copy the URL again from the settings.

Webhook answers Verification failed, retry later: the bill could not be read from the Vindi API (for example the API key of that environment was removed), the cart was being updated by another request at the same moment, or the order status could not be set. Vindi sends the notification again. The log shows the reason.

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Vindi.

The customer sees This payment method is temporarily unavailable: Vindi rejected the API key. Check the key of the current mode.

The customer sees an error after Confirm Order: look at the Log field on the extension page. Errors are logged even when Debug log is off. For boleto, the billing address must have the street, postcode, city and state.

Order is in the on-hold status: read the notes in the VibeFox Vindi Gateway tab (see Order statuses), then complete the order or refund the payment.

Old sandbox orders after switching to live: each payment keeps the environment of its bill. Checks, cancellations and refunds of sandbox orders keep using the sandbox key as long as it stays in the settings.

Refund fails: read the message. Boleto payments cannot be refunded through Vindi, and the API key of the environment of the payment must be set. Without the right to modify the extension the tab says You do not have permission to refund orders (modify this extension).

For developers: before the Vindi customer and the bill are created, the extension triggers the OpenCart events wc_vdi_customer_request and wc_vdi_bill_request with the request data and the order.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Vindi 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 events of the extension are removed too (on OpenCart 4 also its startup action, which lets the webhook and the payment status page through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, sandbox mode, API keys, payment methods, logging), the webhook token, the product cache and the log are removed. If it is off, they are kept for a later re-install. The Vindi bills and refunds of orders are always kept, so orders paid before can still be refunded 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 Vindi Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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