VibeFox Vindi for Adobe Commerce — Guida
Requirements
Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.
PHP: 8.1 to 8.4, with the cURL and JSON extensions.
Currency: Brazilian Real (BRL). Vindi charges in BRL only, so the payment method is hidden for carts in any other currency. The base currency of your store may be another one, as long as 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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.
1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-vindi-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/VindiPayment/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_VindiPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Vindi Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, 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, copy the webhook URL into Vindi (see Configuration), set Enable to Yes and click Save Config. Test a payment in sandbox mode, then set Sandbox Mode to No to accept real payments.
The module adds the Vindi payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Vindi bills and refunds, and a secret webhook token on installation.
Configuration
All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Vindi Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete settings on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".
If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a title for the payment method (1 to 128 characters)., Sort order must be a whole number. or Order total must be a number, 0 or greater. If no payment method is selected in Offered methods, credit card is selected, the page is saved and the warning Choose at least one payment method — credit card was selected. is shown.
When Enable is Yes, the Connection and webhook row warns The API key of the selected Vindi environment is missing. when the key of the current mode is empty, and Vindi charges BRL only. Other currencies are hidden at checkout. when the default display currency of the store is not BRL.
General
Enable: shows or hides Vindi at checkout. It is shown only when the API key of the current mode is set and at least one method is offered. Default: No.
Title: the payment method name customers see at checkout. It is also stored in the order. Default: Vindi. Required, at most 128 characters.
Description: the text shown under the payment method when the customer selects it 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. While it is on, customers see TEST MODE — no real charges will be made. under the payment method. Default: Yes. Set it to No 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.
Magento stores the keys encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete a saved key, clear the field and click Save Config. Spaces around a pasted key are removed.
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.
Connection and webhook
The webhook tells your store that a bill was paid, cancelled, rejected or refunded. The Connection and webhook row shows Webhook URL: and the URL. It is the storefront address of the default store view (in the scope of a website, of the default store view of that website) and looks like https://your-store/wcpvindigateway/checkout/notify?token=.... The token is a secret created by the module. Copy the URL 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 module read the bill again through the Vindi API before an order changes. The row also says Vindi does not return card payments automatically. The webhook or a status check confirms payment. Without the webhook, a card payment is not confirmed automatically, and a boleto or PIX payment only when the customer clicks Check again on the payment instructions page.
Clear product cache: the button in the same row. Every bill uses one generic product in your Vindi account, which the module finds or creates and remembers for a day. Click the button if that product was deleted or changed in Vindi.
Conditions
Payment from Applicable Countries: All Allowed Countries offers Vindi for every country your store allows, Specific Countries only for the countries below.
Payment from Specific Countries: offer Vindi only for billing addresses in these countries.
Minimum Order Total: offer Vindi only from this order total, in the base currency of your store. Empty means no minimum.
Maximum Order Total: offer Vindi only up to this order total, in the base currency. Empty means no maximum.
Sort Order: the position among the payment methods at checkout. A whole number.
Advanced
Debug Log: logs API calls and notifications to var/log/wc_vdi_debug.log.php in the Magento 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: No.
Debug log viewer: shows the size and the latest entries of the log. Click Clear log to empty it.
Delete settings on uninstall: when Yes, uninstalling the module with its data deletes the settings, the webhook token, the product cache and the log (see Uninstall). The license key is always removed. The Vindi bills and refunds of orders always stay. Default: No.
Checkout
At the payment step the customer chooses the payment method (by default Vindi) and sees the description and the choice Vindi payment option with the offered methods. When boleto, PIX or BolePix is offered, the box also has a CPF / CNPJ field, prefilled from the VAT number of the billing address. The number is checked by its check digits. It is required for boleto, PIX and BolePix; for a card it may stay empty. If something is missing, the customer sees Choose a Vindi payment option. or Enter a valid CPF or CNPJ.
After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Vindi customer from the billing address and a Vindi bill for the order total in BRL, in a single installment. In Vindi the bill item is named Order # and the order number.
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 when Vindi reports the payment by the webhook.
Boleto, PIX and BolePix: the bill is issued at once and the customer lands on the page Vindi payment instructions with Your Vindi payment is pending., the Print boleto link, the PIX QR code and the PIX copy and paste code. Check again asks Vindi for the status at once. Try a new Vindi bill cancels the pending bill at Vindi and issues a new one. If Vindi refuses the new bill, the order is cancelled and the cart is restored, as when the payment cannot be started. If the earlier bill cannot be cancelled or its state is unclear, the order and that bill stay as they are, and the customer is back on the instructions page with Vindi payment could not be started. Check the payment details or choose another method. The boleto link, the PIX code and Pay at Vindi are also shown in the payment information of the order in the customer account while the bill is waiting. If Vindi does not return the boleto or PIX data, the bill is cancelled and the payment is not started.
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 order (bill code and Vindi customer) and that the paid amount equals the order total. Magento then creates the invoice, and the order e-mail is sent. When the customer comes back to the instructions page after the payment, the standard order success page opens. The page checks a waiting bill through the API at most every 15 seconds. While the bill is under review at Vindi, or the payment needs your review, the page shows We are confirming your Vindi payment.
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 Vindi cannot start the payment, the order is cancelled (the stock goes back), the cart is restored and the customer sees Vindi payment could not be started. Check the payment details or choose another method. in the cart. The technical reason is written to the log. When a bill is cancelled at Vindi while the customer is on the instructions page, the order is cancelled, the cart is restored and the customer sees Vindi payment was canceled.
When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its pending Vindi bill is cancelled, so it can no longer be paid. If that is not possible, a note asks you to cancel the bill in the Vindi dashboard. While the payment of the order is being updated by another request, the order is not cancelled: the Admin shows This payment is being updated. Try again shortly., and the cron tries again on its next run. Set the lifetime longer than the time your customers need to pay a boleto.
The module works with the standard Magento checkout. It 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. Vindi is not offered for orders created in the Admin.
Orders and refunds
Order statuses
Pending Payment: the order was placed and the bill was created, but Vindi has not confirmed the payment yet. There is no invoice. When Vindi rejects a payment attempt, the order stays here with the note Vindi rejected the latest charge. The bill remains payable.
Processing: the payment was confirmed. The invoice is created with the Vindi environment and bill ID (for example live:12345) as the transaction ID, and the note Vindi payment confirmed through authenticated API verification. is added.
On Hold: the Vindi bill is under review (note Vindi bill is under review.); the order is released and invoiced when Vindi reports it paid. After a mismatch of the amount or currency the order is also put on hold, without an invoice, with the note Vindi paid amount/currency mismatch. Money received; manual review required. Check the payment in the Vindi dashboard, then fulfil the order or refund the payment there.
Canceled: the payment could not be started, the bill was cancelled at Vindi, or the order was cancelled in Magento. If the bill is paid after the order was cancelled, the order is not reopened and the note Vindi paid after order stopped waiting. Order not reopened; review/refund manually. is added.
Closed: the payment was fully refunded with a credit memo.
If a second bill is paid for a cart that is already paid, the order is not changed. A note asks you to review and refund one payment in Vindi. The notes are order comments that the customer does not see.
Vindi payment information
On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for each bill of the order, Vindi attempt # with the environment and bill ID, the method, the status and the amount in BRL, and Vindi refund # for each refund. It is shown also when the module is disabled.
Refunds
Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Vindi. Full and partial refunds of card, PIX and BolePix payments are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Vindi.
The refund is made in BRL, up to the amount Vindi charged minus the amounts already refunded. 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; refunds also work while Enable is No. If Vindi does not confirm the refund, Magento shows the error, for example Vindi did not confirm the refund. Review it before retrying., and the credit memo is not created. A full refund closes the order. Refunds are available once Vindi has confirmed the payment and the order has an invoice.
Vindi cannot refund boleto payments. The credit memo shows Boleto refunds must be handled in the Vindi dashboard. Return the money to the customer in Vindi or by bank transfer and create a credit memo with Refund Offline.
When the answer of Vindi to a refund is unclear, for example after a timeout, the refund is kept as unconfirmed, and further online refunds of the order show A Vindi refund is unconfirmed. Reconcile it before retrying. until it is checked. Refunds made in the Vindi dashboard arrive by the charge_refunded webhook and are added to the order notes (Vindi dashboard refund with the amount). The order and credit memos are not changed automatically. Create a credit memo with Refund Offline if needed; until then a new online refund shows A dashboard refund needs reconciliation before a new refund.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Vindi Gateway is the first row of the VibeFox Vindi Gateway group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-vindi and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.
One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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, no bill is created, the order is cancelled, the cart is restored and the customer sees Vindi payment could not be started. Check the payment details or choose another method. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides 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 module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.
Troubleshooting
Vindi does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the cart currency is BRL, that at least one method is selected in Offered methods and that the current mode has an API key: Sandbox API key in sandbox mode, Live API key in live mode. The Connection and webhook row shows a warning when the key is missing or the currency is not BRL. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.
The payment went through, but the order stays Pending 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. Without the webhook, a paid card order may be cancelled by the Pending Payment Order Lifetime; the payment is then noted as paid after the order stopped waiting, and you must refund it or fulfil the order manually.
Webhook answers Forbidden: the token in the URL is missing or wrong. Copy the URL again from the settings.
Webhook answers Verification failed; retry: 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 log shows the reason.
Webhook answers Unknown bill: the bill was not created by this store, for example a bill of another shop in the same Vindi account. Nothing is changed.
The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Vindi.
Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Vindi sends the notification again later.
The customer is back in the cart with Vindi payment could not be started: look at the Debug log viewer in the settings. Errors are logged even when Debug Log is off. Check the API key of the current mode, the CPF / CNPJ and, for boleto, that the billing address has the street, postcode, city and state. If an earlier bill of the same cart could not be confirmed (for example after a timeout), a new bill is not created until that bill is checked in Vindi.
Order is On Hold after payment: read the order notes (see Order statuses), then fulfil 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.
The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the Vindi dashboard.
The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.
Uninstall
Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_VindiPayment. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_VindiPayment to remove the data, then bin/magento module:disable Vibefox_VindiPayment, delete the folder app/code/Vibefox/VindiPayment and run bin/magento setup:upgrade.
The license key and license status are always removed. If Delete settings on uninstall is Yes, the settings, the webhook token, the product cache and the log are removed too. If it is No, the settings are kept for a re-install. The Vindi bills and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.
Vindi is a trademark of its respective owner. This module is not affiliated with or endorsed by Vindi.