VibeFox Vindi for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

Shop currency: Brazilian Real (BRL). Vindi charges in BRL only, so the payment method is hidden for carts in 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 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 Vindi 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. 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.

On install the module creates two order statuses, Awaiting Vindi payment and Vindi payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences; the module must be allowed for BRL there.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Vindi Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when the shop 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. When you save, the keys are trimmed. If no payment method is selected, credit card is selected and the page shows Choose at least one payment method — credit card was selected. An empty Title is not saved: the page shows Enter a title for the payment method.

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.

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

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

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: the boleto is issued at once and the order waits in Awaiting Vindi payment.

PIX: the PIX QR code and copy and paste code are issued at once and the order waits in Awaiting Vindi payment.

BolePix (boleto + PIX): a boleto that can also be paid by PIX, issued at once like boleto and PIX.

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

Payment notifications (webhook)

The webhook tells your shop that a bill was paid, cancelled, rejected or refunded. The Webhook URL field of this section shows the URL. With friendly URLs it looks like https://your-shop/module/wcp_vindi_gateway/webhook?token=... and contains a secret token created by the module. 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.

Vindi does not sign its notifications, so requests with a missing or wrong token are rejected, and every notification only makes the module read the bill again through the Vindi API before an order changes. Without the webhook, a card payment is only picked up when the customer places the order again with the same cart (the paid bill is then found and the order is created), and a boleto or PIX payment when the customer opens the order confirmation page again.

Advanced

Debug log: logs API calls and notifications to logs/wc_vdi_debug.log.php in the module folder. 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 module removes the settings, the webhook token and the logs. Orders and the Vindi bill references of orders are kept. 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 credit card is not offered; otherwise it shows Required for boleto and PIX. The field is filled in from the Identification number or the VAT number of the invoice address when they hold a valid CPF or CNPJ. 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.

When the customer confirms the order, the module creates a Vindi customer for this cart from the invoice address and a Vindi bill for the cart total, in a single installment. In Vindi the bill is named Order # and the cart number.

Credit card: the customer is sent to the Vindi bill page and pays there. No order exists yet at this point. Vindi has no return URL for bills, so the customer is not sent back to the shop automatically. The order is created when Vindi confirms the payment by the webhook. If the customer places the order again with the same cart, the pending bill is offered again, or, if it is already paid, the order is created at once.

Boleto, PIX and BolePix: the bill is issued at once, the order is created with the status Awaiting Vindi payment and the customer lands on the order confirmation 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 confirmation e-mail contains 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 module reads the bill from the Vindi API and checks the currency, that the bill belongs to the cart (cart code and Vindi customer) and that the paid amount equals the order total. The order confirmation page checks a waiting order through the API again, at most every 15 seconds. When the payment has been received, it shows Your payment with Vindi has been received. While the bill is under review at Vindi 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.

A new payment attempt for the same cart reuses the 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. If the previous bill was paid in the meantime, the order is created and no new bill is issued.

If Vindi cannot start the payment, the customer stays at checkout with a short message, 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 webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module 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

No order yet: a card payment was started and Vindi has not confirmed it yet. Only the cart exists.

Awaiting Vindi payment: a boleto, PIX or BolePix payment is waiting (note Awaiting ... payment at Vindi.). The order moves to Payment accepted when Vindi reports the bill paid.

Payment accepted: the payment was confirmed. The payment is recorded with the Vindi bill ID as the transaction ID, and a note shows the Vindi bill, the amount and the environment.

Vindi payment on hold: the Vindi bill is under review, the paid bill does not match the order (currency, amount, cart code or Vindi customer), or the bill was paid after the order had been cancelled. The note explains it, and a paid amount is recorded on the order. Check the order and the stock, then complete the order or refund the payment.

Payment error: 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 Payment accepted.

Canceled: the bill of a waiting order was cancelled at Vindi. When you cancel an order in the shop, 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: the payment was fully refunded through the module.

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

Vindi payment block

The order page shows a Vindi payment block with the Vindi bill and charge, the environment (with a Sandbox badge for sandbox payments), the payment method, the status, the amount paid and refunded, the refund history, all Bills of this cart and the Vindi notes of the order.

Refunds

In the Vindi payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, 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 edit orders; access to the Modules pages is not needed. 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; 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 block shows the error and no refund is recorded. Refunds are available once Vindi has reported the bill paid.

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

The module does not create credit slips. The standard PrestaShop refund buttons of the order page 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; record them in PrestaShop with a manual refund if needed.

License key

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

Vindi does not appear at checkout: check that the license is active, Enable / Disable is on, the cart 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. In Payment > Preferences check that the module is allowed for BRL, the customer's country and the customer's group.

The payment went through, but no order was created or the order stays Awaiting Vindi payment: 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 could not be created (for example, the module is disabled). 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 when placing the order: look at the Log field on the module 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 Vindi payment on hold: read the notes in the Vindi payment block (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.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Vindi Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the settings, the webhook token and the logs are removed. If it is off, all settings are kept for a later re-install. The Vindi bills and refunds of orders and the order statuses Awaiting Vindi payment and Vindi payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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