VibeFox Vindi for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 8.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer.

Shopwährung: Brasilianischer Real (BRL). Vindi rechnet nur in BRL ab, daher wird die Zahlungsart bei jeder anderen Währung ausgeblendet.

Vindi-Konto: Sie benötigen den API-Schlüssel Ihres Vindi-Kontos. Die Vindi-Sandbox ist ein separates Testkonto mit eigenem Schlüssel. Boleto, PIX und BolePix müssen außerdem in Ihrem Vindi-Konto aktiviert sein, wenn Sie diese anbieten möchten.

VibeFox-Lizenzschlüssel: Erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer Domain.

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins, klicken Sie auf Install Now und danach auf Activate. Alternativ können Sie den Ordner wcp_vindi_gateway per FTP in /wp-content/plugins/ hochladen.

2. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Vindi > Manage, oder klicken Sie auf der Seite Plugins unter dem Namen des Plugins auf Settings.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

4. Fügen Sie den Sandbox API key und, wenn Sie so weit sind, den Live API key ein. Wählen Sie die Offered methods aus.

5. Kopieren Sie die Webhook-URL aus den Einstellungen nach Vindi (siehe Konfiguration).

6. Aktivieren Sie Enable / Disable und speichern Sie. Testen Sie eine Zahlung im Sandbox-Modus und entfernen Sie dann den Haken bei Sandbox mode, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Vindi. Oberhalb der Felder warnt Sie die Seite, wenn die Shopwährung nicht BRL ist oder der API-Schlüssel des aktuellen Modus leer ist. In beiden Fällen wird die Zahlungsart an der Kasse nicht angezeigt. In der Liste der Zahlungsarten ist Vindi als einrichtungsbedürftig markiert, bis der aktuelle Modus einen API-Schlüssel hat. Beim Speichern werden die Schlüssel bereinigt, und wenn keine Zahlungsart ausgewählt ist, wird Kreditkarte ausgewählt und die Seite zeigt Choose at least one payment method — credit card was selected.

Allgemein

Enable / Disable: Enable Vindi payments schaltet die Zahlungsart ein oder aus. Standard: off.

Title: der Name der Zahlungsart, der an der Kasse angezeigt wird. Standard: Vindi.

Description: der Text, der an der Kasse unter der Zahlungsart angezeigt wird. Standard: Pay by credit card on the secure Vindi page, or by boleto / PIX.

API-Schlüssel

Erstellen Sie die Schlüssel im Vindi-Dashboard unter Settings > API keys: auf app.vindi.com.br für den Live-Betrieb und auf sandbox-app.vindi.com.br für die Sandbox. Jede Bestellung merkt sich, wo ihre Rechnung erstellt wurde, sodass Prüfungen, Stornierungen und Erstattungen immer in dieser Umgebung erfolgen.

Sandbox mode: Create new payments in the Vindi sandbox verwendet sandbox-app.vindi.com.br mit dem Sandbox-API-Schlüssel. Kunden sehen an der Kasse den Hinweis TEST MODE: Vindi sandbox: no real charges. Standard: on. Entfernen Sie den Haken, um echte Zahlungen anzunehmen.

Live API key: der private Schlüssel des Live-Vindi-Kontos. Er wird nur an die Vindi-API gesendet.

Sandbox API key: der private Schlüssel des Vindi-Sandbox-Kontos.

Zahlungsarten

Offered methods: die Zahlungsarten, die Kunden wählen können. Standard: credit card. Die Zahlungsarten müssen außerdem in Ihrem Vindi-Konto aktiviert sein.

Credit card: der Kunde zahlt auf der Vindi-Rechnungsseite.

Boleto, PIX, BolePix (boleto + PIX): die Rechnung wird sofort erstellt und die Bestellung bleibt im Status Wartend. Für diese Zahlungsarten wird die CPF- oder CNPJ-Nummer des Kunden benötigt, die an der Kasse abgefragt wird.

Zahlungsbenachrichtigungen (Webhook)

Der Webhook teilt Ihrem Shop mit, dass eine Rechnung bezahlt, storniert oder erstattet wurde. Dieser Abschnitt der Einstellungen zeigt die Webhook-URL. Sie sieht etwa so aus: https://your-site/wc-api/webhook_wc_vindi/?token=... und enthält ein vom Plugin erstelltes geheimes Token. Kopieren Sie sie genau so, wie die Einstellungen sie anzeigen. Gehen Sie in Vindi zu Settings > Webhooks, sowohl im Live-Konto als auch im Sandbox-Konto, fügen Sie diese URL hinzu und wählen Sie folgende Ereignisse aus:

bill_paid: eine Rechnung wurde bezahlt.

bill_canceled: eine Rechnung wurde storniert.

charge_rejected: ein Zahlungsversuch wurde abgelehnt.

charge_refunded: eine Zahlung wurde erstattet, zum Beispiel im Vindi-Dashboard.

Anfragen mit fehlendem oder falschem Token werden abgelehnt. Jede Benachrichtigung veranlasst das Plugin nur dazu, die Rechnung erneut über die Vindi-API abzurufen, bevor sich eine Bestellung ändert. Ohne den Webhook werden Kartenzahlungen, Boleto- und PIX-Zahlungen erst bestätigt, wenn der Kunde die Seite „Bestellung eingegangen“ öffnet.

Erweitert

Debug log: Log API calls and notifications schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_vindi_gateway. Fehler und Warnungen werden immer protokolliert, auch wenn diese Option aus ist. Schlüssel und Kundendaten werden nie protokolliert. Standard: off.

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

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Vindi). Wenn mehr als eine Zahlungsart angeboten wird, zeigt das Zahlungsfeld Pay with und eine Auswahl aus Kreditkarte, Boleto, PIX oder BolePix. Wenn Boleto, PIX oder BolePix angeboten wird, enthält das Feld außerdem ein Feld CPF or CNPJ. Es ist Pflicht, wenn nur diese Zahlungsarten angeboten werden; andernfalls erscheint Required for boleto and PIX. Die Nummer wird anhand ihrer Prüfziffern geprüft. In der klassischen Kasse wird das Feld nicht angezeigt, wenn Brazilian Market on WooCommerce aktiv ist, weil dieses Plugin bereits CPF / CNPJ abfragt. Dann werden dessen CPF / CNPJ, Hausnummer und Ortsteil verwendet. Fehlt etwas, sieht der Kunde Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. oder Please enter your CPF or CNPJ — it is required for boleto and PIX.

Beim Abschluss der Bestellung erstellt das Plugin aus den Rechnungsdaten einen Vindi-Kunden für diese Bestellung und eine Vindi-Rechnung über den Bestellbetrag in einer einzigen Rate.

Credit card: Der Kunde wird zur Vindi-Rechnungsseite weitergeleitet und zahlt dort. Vindi hat für Rechnungen keine Rückkehr-URL, daher kehrt der Kunde nicht automatisch in den Shop zurück. Die Bestellung wird durch den Webhook bestätigt oder wenn der Kunde die Seite „Bestellung eingegangen“ öffnet. Solange die Zahlung nicht abgeschlossen ist, zeigen diese Seite und die Bestellung unter My account den Hinweis Your payment has not been completed yet. und eine Schaltfläche Pay at Vindi.

Boleto, PIX und BolePix: Die Rechnung wird sofort erstellt, die Bestellung wird auf Wartend gesetzt und der Kunde gelangt auf die Seite „Bestellung eingegangen“. Dort und unter My account > Orders zeigt ein Abschnitt Payment den PIX-QR-Code, den PIX-Code zum Kopieren und Einfügen mit der Schaltfläche Copy code und dessen Ablaufdatum sowie die Schaltfläche Open boleto. Die E-Mail des Kunden zur wartenden Bestellung und die Rechnungs-E-Mail enthalten den PIX-Code und den Boleto-Link.

Die Bestellung wird erst als bezahlt markiert, nachdem Vindi bestätigt hat: Das Plugin liest die Rechnung über die Vindi-API und prüft, dass sie zur Bestellung gehört (Bestellnummer und Vindi-Kunde) und dass der bezahlte Betrag dem Bestellbetrag entspricht.

Ein Kunde kann eine unbezahlte Bestellung über die Seite Pay for order erneut bezahlen. Stimmen Zahlungsart, Betrag und Umgebung überein, wird die offene Vindi-Rechnung wiederverwendet. Andernfalls wird sie bei Vindi storniert, bevor eine neue erstellt wird, sodass der Kunde dieselbe Bestellung nicht zweimal bezahlen kann. Wurde die vorherige Rechnung inzwischen bezahlt, wird die Bestellung als bezahlt markiert und keine neue Rechnung erstellt.

Kann Vindi die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel dass er CPF / CNPJ, Rechnungsadresse, E-Mail oder Telefonnummer prüfen soll oder dass Vindi vorübergehend nicht verfügbar ist. Wird dieselbe Bestellung in diesem Moment von einer anderen Anfrage verarbeitet, wird der Kunde gebeten, kurz zu warten und es erneut zu versuchen.

Die Zahlungsart funktioniert in der klassischen Kasse, im Checkout-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin nimmt Einzelzahlungen in einer einzigen Rate an. Es bietet keine Abonnements oder wiederkehrenden Abrechnungen, keine gespeicherten Karten, keine Ratenzahlungen und kein Kartenformular auf Ihrer Website: Die Karte wird immer auf der Vindi-Seite eingegeben.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: eine Kartenzahlung wurde gestartet und Vindi hat sie noch nicht bestätigt.

On hold: eine Zahlung per Boleto, PIX oder BolePix wartet (Notiz Awaiting ... payment at Vindi.), oder die Vindi-Rechnung wird geprüft.

Processing or Completed: die Zahlung wurde bestätigt. Der Status wird wie in WooCommerce üblich gesetzt: In Bearbeitung oder Abgeschlossen bei Bestellungen, die nur virtuelle, herunterladbare Produkte enthalten. Die Bestellnotiz zeigt die Vindi-Rechnung, den Betrag und die Umgebung. Die Transaktions-ID ist die ID der Vindi-Rechnung.

On hold after payment: die bezahlte Rechnung passt nicht zur Bestellung (Betrag, Bestellnummer oder Vindi-Kunde), oder die Rechnung wurde bezahlt, nachdem die Bestellung storniert worden war. Die Bestellnotiz erklärt dies. Prüfen Sie die Bestellung und den Lagerbestand und schließen Sie dann die Bestellung ab oder erstatten Sie die Zahlung.

Failed: Vindi hat den Zahlungsversuch abgelehnt. Die Notiz zeigt den Grund des Zahlungsdienstleisters, sofern vorhanden. Der Kunde kann dieselbe Rechnung weiterhin bezahlen, und eine spätere Zahlung schließt die Bestellung ab.

Cancelled: Die Rechnung wurde bei Vindi storniert, oder die Bestellung wurde von Ihnen, vom Kunden oder durch das WooCommerce-Zeitlimit für die Lagerreservierung storniert. Wird eine Bestellung im Shop storniert, wird auch ihre offene Vindi-Rechnung storniert, sodass sie nicht mehr bezahlt werden kann. Ist das nicht möglich, weist eine Notiz Sie darauf hin, die Rechnung im Vindi-Dashboard zu stornieren. Bevor das Zeitlimit für die Lagerreservierung eine Bestellung storniert, wird die Rechnung geprüft: Wurde sie inzwischen bezahlt, wird die Bestellung stattdessen als bezahlt markiert.

Wird für eine bereits bezahlte Bestellung eine zweite Rechnung bezahlt, wird die Bestellung nicht erneut geändert. Eine Notiz fordert Sie auf, eine Zahlung in Vindi zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Vindi. Vollständige und teilweise Erstattungen von Kartenzahlungen und PIX-Zahlungen werden unterstützt. Eine vollständige Erstattung storniert außerdem die Rechnung bei Vindi. Die Erstattung wird in der Umgebung der Zahlung (Live oder Sandbox) gesendet, daher muss der API-Schlüssel dieser Umgebung hinterlegt sein. Eine erfolgreiche Erstattung wird mit der Vindi-Belastung und dem Status in den Bestellnotizen ergänzt. Lehnen Vindi oder der Zahlungsdienstleister die Erstattung ab, zeigt WooCommerce den Fehler an und es wird keine Erstattung erfasst.

Boleto-Zahlungen kann Vindi nicht erstatten. Das Plugin zeigt Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.

Im Vindi-Dashboard vorgenommene Erstattungen gehen über den Webhook charge_refunded ein und werden in den Bestellnotizen ergänzt. Sie werden nicht automatisch als WooCommerce-Erstattungen erfasst. Erstellen Sie bei Bedarf eine manuelle Erstattung in WooCommerce, ohne Refund via Vindi zu verwenden.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Vindi. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.

Ein Schlüssel funktioniert auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Vindi Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Ein Hinweis erscheint auf der Seite Plugins und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, Updates und Support erfordern jedoch eine Verlängerung. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

Vindi erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, die Shopwährung BRL ist, mindestens eine Zahlungsart in Offered methods ausgewählt ist und der aktuelle Modus einen API-Schlüssel hat: Sandbox API key im Sandbox-Modus, Live API key im Live-Modus. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt oder die Währung nicht BRL ist.

Die Zahlung war erfolgreich, aber die Bestellung bleibt auf Pending payment oder On hold: Der Webhook funktioniert nicht. Prüfen Sie bei Vindi, ob der Webhook im verwendeten Konto (Live oder Sandbox) existiert, ob seine URL genau der in den Einstellungen angezeigten entspricht, einschließlich des Tokens, und ob die vier Ereignisse ausgewählt sind. Die Bestellung wird auch bestätigt, wenn der Kunde die Seite „Bestellung eingegangen“ öffnet.

Der Webhook antwortet Forbidden: Das Token in der URL fehlt oder ist falsch. Kopieren Sie die URL erneut aus den Einstellungen.

Der Webhook antwortet Verification failed, retry later oder Order busy, retry later: Die Rechnung konnte nicht über die Vindi-API gelesen werden (zum Beispiel wurde der API-Schlüssel dieser Umgebung entfernt), oder die Bestellung wurde gerade von einer anderen Anfrage aktualisiert. Vindi sendet die Benachrichtigung erneut.

Der Kunde sieht This payment method is temporarily unavailable: Vindi hat den API-Schlüssel abgelehnt. Prüfen Sie den Schlüssel des aktuellen Modus.

Der Kunde sieht beim Abschluss der Bestellung einen Fehler: Öffnen Sie die Bestellnotizen oder das Protokoll unter WooCommerce > Status > Logs, Quelle wcp_vindi_gateway. Fehler werden auch protokolliert, wenn Debug log ausgeschaltet ist. Bei Boleto müssen in der Rechnungsadresse Straße, Postleitzahl, Ort und Bundesland angegeben sein.

Bestellung ist nach der Zahlung On hold: Lesen Sie die Bestellnotiz. Der bezahlte Betrag, die Bestellnummer oder der Vindi-Kunde wich von der Bestellung ab, oder die Zahlung kam, nachdem die Bestellung storniert wurde. Schließen Sie die Bestellung ab oder erstatten Sie die Zahlung.

Alte Sandbox-Bestellungen nach dem Wechsel auf Live: Jede Bestellung behält die Umgebung ihrer Rechnung. Prüfungen, Stornierungen und Erstattungen von Sandbox-Bestellungen verwenden weiterhin den Sandbox-Schlüssel, solange er in den Einstellungen hinterlegt ist.

Erstattung schlägt fehl: Lesen Sie die Meldung. Boleto-Zahlungen können nicht über Vindi erstattet werden, und der API-Schlüssel der Umgebung der Zahlung muss hinterlegt sein.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Wurde die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Kann der Lizenzserver nicht erreicht werden, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.

Deinstallation

Das Deaktivieren des Plugins behält alle Daten. Zum Entfernen deaktivieren Sie es und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Die Einstellungen des Gateways, das Webhook-Token, die übrigen gespeicherten Plugin-Daten und die Protokolle werden nur entfernt, wenn Delete data on uninstall aktiv war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Transaktions-IDs und Vindi-Daten.

Vindi ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Vindi verbunden noch wird es von Vindi unterstützt.