VibeFox Vindi for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Store currency: Brazilian Real (BRL). Vindi charges in BRL only, so the payment method is hidden for any other currency.

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

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

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

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

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 save. Test a payment in sandbox mode, then untick Sandbox mode to accept real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Vindi. Above the fields the page warns you when the store currency is not BRL or when the API key of the current mode is empty. In both cases the payment method is not shown at checkout. In the list of payment methods, Vindi is marked as needing setup until the current mode has an API key. When you save, the keys are trimmed, and if no payment method is selected, credit card is selected and the page shows Choose at least one payment method — credit card was selected.

General

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

Title: the payment method name shown at checkout. Default: Vindi.

Description: the text shown under the payment method at checkout. Default: Pay by credit card on the secure Vindi page, or by boleto / PIX.

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. Each order remembers where its bill was created, so checks, cancellations and refunds always use that environment.

Sandbox mode: Create new payments in the Vindi sandbox uses 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. Untick it 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.

Payment methods

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

Credit card: the customer pays on the Vindi bill page.

Boleto, PIX, BolePix (boleto + PIX): the bill is issued at once and the order waits On hold. These methods 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 or refunded. This section of the settings shows the webhook URL. It looks like https://your-site/wc-api/webhook_wc_vindi/?token=... and contains a secret token created by the plugin. 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:

bill_paid: a bill was paid.

bill_canceled: a bill was cancelled.

charge_rejected: a payment attempt was rejected.

charge_refunded: a payment was refunded, for example in the Vindi dashboard.

Requests with a missing or wrong token are rejected. Every notification only makes the plugin read the bill again through the Vindi API before an order changes. Without the webhook, card, boleto and PIX payments are only confirmed when the customer opens the order received page.

Advanced

Debug log: Log API calls and notifications writes details to WooCommerce > Status > Logs, source wcp_vindi_gateway. Errors and warnings are always logged, even when this is off. Keys and customer data are never logged. Default: off.

Delete data on uninstall: Remove the settings, webhook token and logs when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default Vindi). 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 only those methods are offered; otherwise it shows Required for boleto and PIX. The number is checked by its check digits. On the classic checkout the field is not shown when Brazilian Market on WooCommerce is active, because that plugin already asks for CPF / CNPJ. Its CPF / CNPJ, house number and neighbourhood are then used. 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.

When the order is placed, the plugin creates a Vindi customer for this order from the billing details and a Vindi bill for the order total, in a single installment.

Credit card: the customer is sent to the Vindi bill page and pays there. Vindi has no return URL for bills, so the customer is not sent back to the store automatically. The order is confirmed by the webhook, or when the customer opens the order received page. While the payment is not complete, that page and the order in My account show Your payment has not been completed yet. and a Pay at Vindi button.

Boleto, PIX and BolePix: the bill is issued at once, the order is set to On hold and the customer lands on the order received page. There, and in My account > Orders, 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 customer's on-hold e-mail and the invoice e-mail contain the PIX code and the boleto link.

The order is marked paid only after Vindi confirms it: the plugin reads the bill from the Vindi API and checks that it belongs to the order (order code and Vindi customer) and that the paid amount equals the order total.

A customer can pay an unpaid order again from the Pay for order page. If the method, amount and environment are the same, the pending Vindi bill is reused. Otherwise it is cancelled at Vindi before a new one is created, so the customer cannot pay the same order twice. If the previous bill was paid in the meantime, the order is marked paid and no new bill is created.

If Vindi cannot start the payment, the customer sees a short message, for example to check the CPF / CNPJ, the billing address, the e-mail or the phone number, or that Vindi is temporarily unavailable. If the same order is being processed by another request at that moment, the customer is asked to wait a moment and try again.

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

The plugin takes 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.

Orders and refunds

Order statuses

Pending payment: a card payment was started and Vindi has not confirmed it yet.

On hold: a boleto, PIX or BolePix payment is waiting (note Awaiting ... payment at Vindi.), or the Vindi bill is under review.

Processing or Completed: the payment was confirmed. The status is set the standard WooCommerce way: Processing, or Completed for orders with only virtual downloadable products. The order note shows the Vindi bill, the amount and the environment. The transaction ID is the Vindi bill ID.

On hold after payment: the paid bill does not match the order (amount, order code or Vindi customer), or the bill was paid after the order had been cancelled. The order note explains it. Check the order and the stock, then complete the order or refund the payment.

Failed: Vindi rejected the payment attempt. The note shows the reason from the acquirer if there is one. The customer can still pay the same bill, and a later payment completes the order.

Cancelled: the bill was cancelled at Vindi, or the order was cancelled by you, by the customer or by the WooCommerce hold stock timeout. When an order is cancelled in the store, 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. Before the hold stock timeout cancels an order, the bill is checked: if it was paid in the meantime, the order is marked paid instead.

If a second bill is paid for an order that is already paid, the order is not changed again. A note asks you to refund one payment in Vindi.

Refunds

Open the order, click Refund, enter the amount and click Refund via Vindi. Full and partial refunds of card and PIX payments are supported. A full refund also cancels the bill at Vindi. The refund is sent in the environment of the payment (live or sandbox), so that environment's API key must be set. A successful refund is added to the order notes with the Vindi charge and the status. If Vindi or the acquirer refuses the refund, WooCommerce shows the error and no refund is recorded.

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

Refunds made in the Vindi dashboard arrive by the charge_refunded webhook and are added to the order notes. They are not recorded as WooCommerce refunds automatically. If needed, create a manual refund in WooCommerce without Refund via Vindi.

License key

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

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

Without an active key, 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

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

Troubleshooting

Vindi does not appear at checkout: check that the license is active, Enable / Disable is on, the store currency is 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 currency is not BRL.

The payment went through, but the order stays Pending payment or On hold: 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. The order is also confirmed when the customer opens the order received page.

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 or Order busy, retry later: the bill could not be read from the Vindi API (for example the API key of that environment was removed), or the order was being updated by another request at the same moment. Vindi sends the notification again.

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 when placing the order: open the order notes or the log at WooCommerce > Status > Logs, source wcp_vindi_gateway. Errors are logged even when Debug log is off. For boleto, the billing address must have the street, postcode, city and state.

Order is On hold after payment: read the order note. The paid amount, the order code or the Vindi customer differed from the order, or the payment came after the order was cancelled. Complete the order or refund the payment.

Old sandbox orders after switching to live: each order 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.

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

Uninstall

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

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