VibeFox Vindi for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

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

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

VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer Domain.

Installation

1. Gehen Sie im Back-Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.

2. Klicken Sie nach Abschluss des Uploads auf Configure oder suchen Sie VibeFox Vindi Gateway später in der Modulliste und klicken Sie dort auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel in das Feld License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

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

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

6. Aktivieren Sie Enable / Disable und klicken Sie auf Save. Testen Sie eine Zahlung im Sandbox-Modus und deaktivieren Sie dann Sandbox mode, um echte Zahlungen anzunehmen.

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Vindi payment und Vindi payment on hold. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken; das Modul muss dort für BRL erlaubt sein.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Vindi Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. 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. Beim Speichern werden überflüssige Leerzeichen aus den Schlüsseln entfernt. Wenn keine Zahlungsart ausgewählt ist, wird Kreditkarte ausgewählt und die Seite zeigt Choose at least one payment method — credit card was selected. Ein leerer Title wird nicht gespeichert: Die Seite zeigt Enter a title for the payment method.

Vindi

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

Title: der Name der Zahlungsart, der an der Kasse angezeigt wird. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Vindi. Pflichtfeld.

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

Die Schlüssel erstellen Sie im Vindi-Dashboard unter Settings > API keys: auf app.vindi.com.br für Live und auf sandbox-app.vindi.com.br für die Sandbox. Live und Sandbox haben getrennte Hosts und Schlüssel. Jede Zahlung merkt sich, wo ihre Rechnung erstellt wurde, sodass Prüfungen, Stornierungen und Erstattungen immer diese Umgebung verwenden.

Sandbox mode: erstellt neue Zahlungen in der Vindi-Sandbox, über sandbox-app.vindi.com.br mit dem Sandbox-API-Schlüssel. Kunden sehen an der Kasse einen Hinweis TEST MODE: Vindi sandbox: no real charges. Standard: an. Deaktivieren Sie die Option, 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.

Gespeicherte Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Clear saved keys: Markieren Sie einen Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert bei.

Zahlungsarten

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

Boleto, PIX und BolePix benötigen die CPF oder CNPJ des Kunden, die an der Kasse abgefragt wird.

Zahlungsbenachrichtigungen (Webhook)

Der Webhook informiert Ihren Shop darüber, dass eine Rechnung bezahlt, storniert, abgelehnt oder erstattet wurde. Das Feld Webhook URL in diesem Abschnitt zeigt die URL. Mit suchmaschinenfreundlichen URLs sieht sie so aus: https://your-shop/module/wcp_vindi_gateway/webhook?token=... und sie enthält ein geheimes Token, das das Modul erstellt. 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:

Vindi signiert seine Benachrichtigungen nicht. Daher werden Anfragen mit fehlendem oder falschem Token abgelehnt, und jede Benachrichtigung veranlasst das Modul nur, die Rechnung erneut über die Vindi-API abzurufen, bevor sich eine Bestellung ändert. Ohne Webhook wird eine Kartenzahlung erst erkannt, wenn der Kunde die Bestellung erneut mit demselben Warenkorb aufgibt (dann wird die bezahlte Rechnung gefunden und die Bestellung angelegt), und eine Boleto- oder PIX-Zahlung erst, wenn der Kunde die Bestellbestätigungsseite erneut öffnet.

Erweitert

Debug log: protokolliert API-Aufrufe und Benachrichtigungen in logs/wc_vdi_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Fehler und Warnungen werden immer protokolliert, auch wenn die Option aus ist. Schlüssel, das Webhook-Token und Kundendaten werden nie protokolliert. Standard: aus.

Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.

Delete data on uninstall: wenn aktiviert, entfernt die Deinstallation des Moduls die Einstellungen, das Webhook-Token und die Protokolle. Bestellungen und die Vindi-Rechnungsverweise der Bestellungen bleiben erhalten. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Vindi). Wenn mehr als eine Zahlungsart angeboten wird, zeigt der Zahlungsbereich Pay with und eine Auswahl aus Kreditkarte, Boleto, PIX oder BolePix. Wenn Boleto, PIX oder BolePix angeboten wird, enthält der Bereich außerdem ein Feld CPF or CNPJ. Es ist Pflicht, wenn keine Kreditkarte angeboten wird; andernfalls zeigt es Required for boleto and PIX. Das Feld wird mit der Identification number oder der USt-IdNr. der Rechnungsadresse vorausgefüllt, wenn diese eine gültige CPF oder CNPJ enthalten. Die Nummer wird anhand ihrer Prüfziffern geprüft. 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.

Wenn der Kunde die Bestellung bestätigt, legt das Modul anhand der Rechnungsadresse einen Vindi-Kunden für diesen Warenkorb an sowie eine Vindi-Rechnung über die Warenkorbsumme in einer einzigen Rate. In Vindi heißt die Rechnung Order # und trägt die Warenkorbnummer.

Kreditkarte: Der Kunde wird zur Vindi-Rechnungsseite geschickt und zahlt dort. Zu diesem Zeitpunkt existiert noch keine Bestellung. Vindi hat keine Rücksprung-URL für Rechnungen, daher wird der Kunde nicht automatisch zurück in den Shop geleitet. Die Bestellung wird angelegt, wenn Vindi die Zahlung über den Webhook bestätigt. Gibt der Kunde die Bestellung mit demselben Warenkorb erneut auf, wird die offene Rechnung erneut angeboten oder, falls sie bereits bezahlt ist, sofort die Bestellung angelegt.

Boleto, PIX und BolePix: die Rechnung wird sofort ausgestellt, die Bestellung wird mit dem Status Awaiting Vindi payment angelegt und der Kunde landet auf der Bestellbestätigungsseite. Dort zeigt ein Abschnitt Payment – ebenso in den Bestelldetails des Kundenkontos – den PIX-QR-Code, den PIX-Code zum Kopieren und Einfügen mit einer Schaltfläche Copy code und dessen Ablaufdatum sowie eine Schaltfläche Open boleto. Die Bestellbestätigungs-E-Mail enthält den PIX-Code und den Boleto-Link. Wenn Vindi die Boleto- oder PIX-Daten nicht zurückgibt, wird die Rechnung storniert und der Kunde sieht einen Fehler.

Die Bestellung wird erst als bezahlt markiert, nachdem Vindi die Zahlung bestätigt hat: Das Modul liest die Rechnung über die Vindi-API und prüft die Währung, dass die Rechnung zum Warenkorb gehört (Warenkorbcode und Vindi-Kunde) und dass der bezahlte Betrag dem Bestellbetrag entspricht. Die Bestellbestätigungsseite prüft eine wartende Bestellung höchstens alle 15 Sekunden erneut über die API. Sobald die Zahlung eingegangen ist, zeigt sie Your payment with Vindi has been received. Während die Rechnung bei Vindi geprüft wird, zeigt sie We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. Bei einer stornierten Bestellung zeigt sie This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.

Ein neuer Zahlungsversuch für denselben Warenkorb verwendet die offene Vindi-Rechnung erneut, wenn Zahlungsart, Betrag und Umgebung gleich sind. Andernfalls wird die vorherige Rechnung bei Vindi storniert, bevor eine neue erstellt wird, sodass der Kunde nicht zweimal für denselben Warenkorb zahlen kann. Wurde die vorherige Rechnung inzwischen bezahlt, wird die Bestellung angelegt und keine neue Rechnung ausgestellt.

Wenn Vindi die Zahlung nicht starten kann, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel mit der Aufforderung, CPF / CNPJ, Rechnungsadresse (Straße, PLZ, Ort und Bundesstaat sind für Boleto Pflicht), E-Mail-Adresse oder Telefonnummer zu prüfen, oder mit dem Hinweis, dass Vindi vorübergehend nicht verfügbar ist. Der technische Grund wird im Protokoll festgehalten.

Der Webhook funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Ländersperre Ihres Shops blockiert.

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

Bestellungen und Erstattungen

Bestellstatus

No order yet: eine Kartenzahlung wurde begonnen und Vindi hat sie noch nicht bestätigt. Es existiert nur der Warenkorb.

Awaiting Vindi payment: eine Zahlung per Boleto, PIX oder BolePix steht aus (Notiz Awaiting ... payment at Vindi.). Die Bestellung wechselt zu Payment accepted, sobald Vindi die Rechnung als bezahlt meldet.

Payment accepted: die Zahlung wurde bestätigt. Die Zahlung wird mit der Vindi-Rechnungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Vindi-Rechnung, den Betrag und die Umgebung.

Vindi payment on hold: die Vindi-Rechnung wird geprüft, die bezahlte Rechnung passt nicht zur Bestellung (Währung, Betrag, Warenkorbcode oder Vindi-Kunde), oder die Rechnung wurde bezahlt, nachdem die Bestellung storniert worden war. Die Notiz erklärt dies, und ein bezahlter Betrag wird an der Bestellung erfasst. Prüfen Sie die Bestellung und den Lagerbestand und schließen Sie dann die Bestellung ab oder erstatten Sie die Zahlung.

Payment error: Vindi hat den Zahlungsversuch einer wartenden Bestellung abgelehnt. Die Notiz zeigt den Grund des Acquirers, sofern vorhanden. Der Kunde kann dieselbe Rechnung weiterhin bezahlen, und eine spätere Zahlung wechselt die Bestellung zu Payment accepted.

Canceled: die Rechnung einer wartenden Bestellung wurde bei Vindi storniert. Wenn Sie eine Bestellung im Shop stornieren, wird ihre offene Vindi-Rechnung ebenfalls storniert, sodass sie nicht mehr bezahlt werden kann. Ist das nicht möglich, bittet Sie eine Notiz, die Rechnung im Vindi-Dashboard zu stornieren.

Refunded: die Zahlung wurde über das Modul vollständig erstattet.

Wird für eine bereits bezahlte Bestellung eine zweite Rechnung bezahlt, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, eine Zahlung in Vindi zu erstatten.

Vindi-Zahlungsblock

Die Bestellseite zeigt einen Block Vindi payment mit der Vindi-Rechnung und -Belastung, der Umgebung (mit einem Abzeichen Sandbox bei Sandbox-Zahlungen), der Zahlungsart, dem Status, dem bezahlten und erstatteten Betrag, dem Erstattungsverlauf, allen Bills of this cart und den Vindi notes der Bestellung.

Erstattungen

Geben Sie im Block Vindi payment den Betrag ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Vindi. Bestätigen Sie die Frage Refund this amount through Vindi? This cannot be undone. Vollständige und teilweise Erstattungen von Kartenzahlungen und PIX-Zahlungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht erforderlich. Erstattungen sind auf den Betrag begrenzt, den Vindi tatsächlich eingezogen hat. Nach einer Abweichung können Sie also bis zu dem erstatten, was der Kunde bezahlt hat, nicht bis zur Bestellsumme. Die Erstattung wird in der Umgebung der Zahlung (Live oder Sandbox) gesendet, daher muss der API-Schlüssel dieser Umgebung gesetzt sein. Eine vollständige Erstattung storniert außerdem die Rechnung bei Vindi und setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht. Eine erfolgreiche Erstattung wird mit der Vindi-Belastung und dem Status dem Erstattungsverlauf und den Notizen hinzugefügt. Lehnen Vindi oder der Acquirer die Erstattung ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Erstattungen sind verfügbar, sobald Vindi die Rechnung als bezahlt gemeldet hat.

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

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite schicken kein Geld über Vindi zurück. Im Vindi-Dashboard vorgenommene Erstattungen gelangen über den Webhook charge_refunded und werden den Notizen hinzugefügt. Der Bestellstatus wird nicht automatisch geändert; erfassen Sie sie bei Bedarf in PrestaShop mit einer manuellen Erstattung.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Vindi Gateway ist der erste Block auf Modules > Module Manager > VibeFox Vindi Gateway > Configure, über den Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-vindi und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, nennt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nachdem sich die Shop-Adresse geändert hat oder Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel gilt für eine Domain: die Domain des Haupt-Shops, auch bei einer Multistore-Einrichtung. Das Entfernen des Schlüssels aus dem Shop gibt seinen 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. Der PrestaShop-Storefront erkennt nicht, dass Sie im Back Office angemeldet sind, daher ist die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber den Bestellvorgang nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen bleiben unberührt: bereits erstellte Rechnungen werden weiterhin über den Vindi-Webhook bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird während Ihrer Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach der Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Vindi erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, die Warenkorbwährung BRL ist, mindestens eine Zahlungsart unter 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. Prüfen Sie unter Payment > Preferences, ob das Modul für BRL, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ist erfolgt, aber es wurde keine Bestellung angelegt oder die Bestellung bleibt bei Awaiting Vindi payment: der Webhook funktioniert nicht. Prüfen Sie in 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 alle vier Ereignisse ausgewählt sind.

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

Der Webhook antwortet mit Verification failed, retry later: die Rechnung konnte nicht über die Vindi-API gelesen werden (zum Beispiel wurde der API-Schlüssel dieser Umgebung entfernt), der Warenkorb wurde im selben Moment von einer anderen Anfrage aktualisiert, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Vindi sendet die Benachrichtigung erneut. Das Protokoll zeigt den Grund.

Die Webhook-URL zeigt im Browser Method not allowed: das ist normal. Die URL akzeptiert nur Anfragen von Vindi.

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 Aufgeben der Bestellung einen Fehler: sehen Sie im Feld Log auf der Modulseite nach. Fehler werden auch dann protokolliert, wenn Debug log aus ist. Bei Boleto muss die Rechnungsadresse Straße, PLZ, Ort und Bundesstaat enthalten.

Bestellung ist Vindi payment on hold: lesen Sie die Notizen im Block Vindi payment (siehe Bestellstatus) und schließen Sie dann die Bestellung ab oder erstatten Sie die Zahlung.

Alte Sandbox-Bestellungen nach dem Wechsel auf Live: jede Zahlung 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 bleibt.

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

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Vindi Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall aktiviert, werden die Einstellungen, das Webhook-Token und die Protokolle entfernt. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Vindi-Rechnungen und -Erstattungen der Bestellungen sowie die Bestellstatus Awaiting Vindi payment und Vindi payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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