VibeFox Flow 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.
Währung: Chilenischer Peso (CLP) oder US-Dollar (USD). Für Warenkörbe in anderen Währungen wird die Zahlungsmethode an der Kasse ausgeblendet. Stellen Sie für CLP die Nachkommastellen der CLP-Währung auf 0 unter International > Localization > Currencies ein, da Flow ganze Pesos berechnet.
Flow-Konto: Sie benötigen den API Key und den Secret Key Ihres Flow-Kontos, in Flow unter Mis datos, Datos técnicos. Für Tests erstellen Sie ein separates Sandbox-Konto auf sandbox.flow.cl und verwenden dessen Schlüssel. Sandbox- und Live-Schlüssel sind verschieden. Im Flow-Konto muss nichts konfiguriert werden.
Öffentliche Website: Die Bestätigungs-, Rückkehr- und Erstattungs-URLs Ihres Shops müssen aus dem Internet erreichbar sein, ohne Passwortschutz oder Firewall, die Flow blockiert. Der Wartungsmodus des Shops blockiert sie nicht.
VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel gilt für eine 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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie VibeFox Flow Gateway später in der Modulliste und klicken Sie dort auf Configure.
3. Fügen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Geben Sie den API Key und den Secret Key der Sandbox ein, aktivieren Sie Enable / Disable, klicken Sie auf Save und legen Sie eine Testbestellung an.
5. Um echte Zahlungen anzunehmen, tragen Sie die Live-Schlüssel ein und deaktivieren Sie Sandbox mode.
Bei der Installation legt das Modul zwei Bestellstatus an, Awaiting Flow payment und Flow 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.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Flow Gateway > Configure. Jeder Abschnitt mit Feldern hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn die Schlüssel des aktuellen Modus leer sind (Flow wird dann an der Kasse ausgeblendet), wenn die Standardwährung des Shops nicht CLP oder USD ist und wenn die CLP-Währung Nachkommastellen hat (stellen Sie deren Genauigkeit auf 0, damit Preise, Summen und Erstattungen exakt übereinstimmen). Im Sandbox-Modus zeigt sie Sandbox mode — payments go to sandbox.flow.cl, no real money is charged. an.
Flow.cl
Enable / Disable: Enable Flow.cl payments schaltet die Zahlungsmethode ein oder aus. Standard: off.
Title: der Name der Zahlungsmethode, den der Kunde an der Kasse sieht. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Flow. Pflichtfeld.
Description: der Text, der unter der Zahlungsmethode an der Kasse angezeigt wird. Standard: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.
Flow-API-Zugangsdaten
Kopieren Sie den API Key und den Secret Key aus Ihrem Flow-Konto (Mis datos, Datos técnicos): Live-Schlüssel von www.flow.cl, Sandbox-Schlüssel von sandbox.flow.cl (ein separates Sandbox-Konto).
Sandbox mode: verwendet die Flow-Sandbox (sandbox.flow.cl) und die Sandbox-Schlüssel. Im Sandbox-Modus wird kein echtes Geld belastet. Standard: on. Deaktivieren Sie ihn und tragen Sie die Live-Schlüssel ein, um echte Zahlungen anzunehmen. Erstattungen verwenden immer die Umgebung, in der die Bestellung bezahlt wurde.
Sandbox API Key: der API Key Ihres Kontos auf sandbox.flow.cl.
Sandbox Secret Key: der Secret Key Ihres Kontos auf sandbox.flow.cl. Er wird zum Signieren jeder Anfrage verwendet.
Live API Key: der API Key Ihres Kontos auf www.flow.cl.
Live Secret Key: der Secret Key Ihres Kontos auf www.flow.cl. Halten Sie ihn geheim.
Gespeicherte Schlüssel werden nie erneut 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.
Benachrichtigungen
Das Modul sendet bei jeder Zahlung und Erstattung drei URLs an Flow, daher muss im Flow-Konto nichts konfiguriert werden. Das Feld Flow URLs dieses Abschnitts listet sie auf. Mit freundlichen URLs sehen sie so aus:
Die Bestätigung enthält nur ein Zahlungstoken. Das Modul sucht das Token unter den von ihm erstellten Zahlungen, fragt Flow mit einer signierten Anfrage in der Umgebung, in der die Zahlung erstellt wurde, nach dem Zahlungsstatus und übernimmt nur die Antwort von Flow. Eine Zahlung, die dieser Shop nicht erstellt hat, wird ohne Anfrage an Flow abgelehnt. Ohne die Bestätigung wird die Bestellung angelegt, wenn der Kunde von Flow zurückkehrt.
Erweitert
Debug log: schreibt API-Aufrufe und Benachrichtigungen in logs/flw_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Schlüssel und Kundendaten werden nie protokolliert. Fehler werden immer protokolliert, auch bei ausgeschaltetem Debug log. Standard: off.
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 seine Einstellungen und das Protokoll. In Bestellungen gespeicherte Flow-Daten bleiben erhalten. Standard: off.
Bestellvorgang
Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Flow) und sieht die Beschreibung. Im Sandbox-Modus zeigt sie SANDBOX MODE — Zahlungen gehen an die Flow-Sandbox. Es werden keine echten Belastungen vorgenommen. Nach der Bestätigung durch den Kunden legt das Modul eine Flow-Zahlung über den Gesamtbetrag des Warenkorbs in der Warenkorbwährung an, mit dem Betreff Cart # plus der Warenkorbnummer und dem Shopnamen, und leitet den Kunden zur Zahlungsseite von Flow weiter. Die E-Mail-Adresse des Kunden wird an Flow übergeben. Dort wählt der Kunde eine in Ihrem Flow-Konto aktivierte Zahlungsmethode. Zu diesem Zeitpunkt existiert noch keine Bestellung.
Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Flow die Zahlung bestätigt hat: durch die Bestätigung oder durch eine signierte Statusanfrage, wenn der Kunde zurückkehrt. Danach wird die Bestellung angelegt, und der Kunde sieht die Standardbestellbestätigungsseite mit Your payment with Flow has been received. Hat der Kunde einen Servipag- oder Multicaja-Zahlungsbeleg erstellt, wird die Bestellung in Awaiting Flow payment angelegt, und die Seite zeigt Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. Schlägt die Zahlung einer Belegbestellung später fehl oder wird sie abgebrochen, zeigt die Seite Your Flow payment was not completed. Please contact us about this order. Stimmte der Betrag nicht überein, zeigt die Seite Your Flow payment was received and is being reviewed by the shop.
Wenn Flow bei der Rückkehr des Kunden nicht erreichbar ist oder eine andere Anfrage in diesem Moment die Bestellung anlegt, bittet eine Seite Payment confirmation den Kunden, nicht erneut zu zahlen, und bietet Check again und Back to checkout an.
Wurde die Zahlung abgelehnt, kehrt der Kunde zur Kasse zurück, mit Your Flow payment was rejected. Please try again or choose another payment method. Hat der Kunde die Flow-Seite ohne Zahlung verlassen, lautet die Meldung The Flow payment was not completed. You can try again or choose another payment method. Konnte das Ergebnis nicht geprüft werden, lautet die Meldung We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. Der Warenkorb bleibt erhalten, und jeder neue Versuch erstellt eine neue Flow-Zahlung, die an den Warenkorb gebunden ist.
Kann Flow die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel Could not connect to Flow. Please try again in a moment. Die Details stehen im Protokoll.
Wird ein Gutschein im Warenkorb zwischen Zahlung und Bestätigung ungültig, entfernt PrestaShop ihn aus der Bestellung. Die Bestellung wird dann auf Flow payment on hold gesetzt, mit einer Notiz, weil der Kunde den Preis mit Rabatt bezahlt hat.
Das Modul akzeptiert nur einmalige Zahlungen. Es bietet keine gespeicherten Karten, Abonnements, wiederkehrenden Belastungen oder Zahlungslinks und wählt keine Flow-Zahlungsmethode vor. Flow kann einen bereits erstellten Zahlungslink nicht stornieren: Zahlt ein Kunde einen alten Link, nachdem der Warenkorb bereits bezahlt wurde, erhält die Bestellung eine Notiz mit der Aufforderung, die doppelte Zahlung in Flow zu erstatten.
Bestellungen und Erstattungen
Bestellstatus
No order yet: Der Kunde wurde zu Flow weitergeleitet und hat nicht gezahlt, oder Flow hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.
Payment accepted: Flow hat die Zahlung als bezahlt gemeldet, und Betrag und Währung stimmen überein. Die Zahlung wird mit der Flow-Bestellnummer als Transaktions-ID erfasst; eine Notiz zeigt Betrag, Flow-Bestellnummer und Zahlungsmethode.
Awaiting Flow payment: Der Kunde hat einen Servipag- oder Multicaja-Zahlungsbeleg erstellt. Die Bestellung wechselt zu Payment accepted, sobald Flow die Zahlung bestätigt.
Flow payment on hold: Flow hat einen anderen Betrag oder eine andere Währung als den Bestellgesamtbetrag gemeldet (zum Beispiel wurde der Warenkorb nach Beginn der Zahlung geändert), ein Gutschein wurde entfernt, oder eine Zahlung ist für eine stornierte Bestellung eingegangen. Die von Flow eingezogene Zahlung wird erfasst, und die Notiz erläutert dies. Prüfen Sie die Bestellung und versenden Sie sie oder erstatten Sie die Zahlung.
Payment error: Flow hat die Belegzahlung einer wartenden Bestellung abgelehnt.
Canceled: Die Belegzahlung einer wartenden Bestellung wurde in Flow annulliert.
Refunded: Die Zahlung wurde über das Modul vollständig erstattet.
Geht eine weitere Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, die doppelte Zahlung in Ihrem Flow-Konto zu erstatten. Eine erstattete Bestellung wird nie wieder geöffnet.
Flow-Zahlungsblock
Die Bestellseite zeigt einen Block Flow payment mit der Flow-Bestellnummer und Zahlungsmethode, der commerceOrder-Referenz, dem Zahlungsstatus, dem gezahlten und erstatteten Betrag, einem Sandbox-Kennzeichen für Sandbox-Zahlungen, dem Erstattungsverlauf und den Flow notes der Bestellung.
Erstattungen
Geben Sie im Block Flow payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Flow. Bestätigen Sie die Frage Refund this amount via Flow? Flow e-mails the customer to complete the refund. Voll- und Teilerstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten. Erstattungen sind auf den Betrag begrenzt, den Flow tatsächlich eingezogen hat; nach einer Betragsabweichung können Sie also bis zu dem erstatten, was der Kunde bezahlt hat, nicht bis zum Bestellgesamtbetrag. CLP-Erstattungen müssen ganze Beträge sein. Die Erstattung wird an die Umgebung gesendet, in der die Zahlung erfolgt ist (Sandbox oder Live), daher müssen deren Schlüssel eingetragen sein, und der Kunde braucht eine gültige E-Mail-Adresse. Lehnt Flow die Erstattung ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine erfolgreiche Anfrage wird dem Erstattungsverlauf und den Notizen mit der Flow-Erstattungsnummer und dem Status hinzugefügt. Eine Vollerstattung setzt die Bestellung auf Refunded. Eine Teilerstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Flow die Zahlung bestätigt hat.
Spätere Statusänderungen der Erstattung durch Flow werden den Notizen hinzugefügt. Lehnt Flow eine Erstattung später ab oder storniert sie, vermerkt die Notiz, dass das Geld nicht an den Kunden zurückgegeben wurde, und der Betrag kann erneut erstattet werden. Das Modul erstellt keine Gutschriften. Die standardmäßigen PrestaShop-Erstattungsschaltflächen auf der Bestellseite senden kein Geld über Flow zurück. Im Flow-Dashboard erstellte Erstattungen werden nicht in PrestaShop importiert.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Flow Gateway ist der erste Block auf Modules > Module Manager > VibeFox Flow Gateway > Configure, oberhalb der Einstellungen. Fügen 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-flow 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. Nach einer Änderung der Shopadresse oder nachdem 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 Hauptshops, 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 Flow 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 weiß nicht, dass Sie im Back Office angemeldet sind, daher wird die Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.
Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern 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. Es ist kein Cron-Job nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
Flow wird an der Kasse nicht angezeigt: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, die Schlüssel des aktuellen Modus ausgefüllt sind (Sandbox-Schlüssel im Sandbox-Modus, Live-Schlüssel im Live-Modus) und die Warenkorbwährung CLP oder USD ist. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe zugelassen ist.
Die Zahlung war erfolgreich, aber es wurde keine Bestellung angelegt: Die Flow-Bestätigung erreicht Ihren Shop nicht, und der Kunde ist nicht zurückgekehrt. Prüfen Sie, ob die unter Flow URLs angezeigte Bestätigungs-URL aus dem Internet erreichbar ist und nicht durch Passwortschutz oder Firewall blockiert wird. Aktivieren Sie Debug log und sehen Sie im Feld Log auf der Modulseite nach.
Die Bestätigung antwortet Payment does not belong to the order: Das Token gehört nicht zu einer von diesem Shop erstellten Zahlung, oder Flow hat dafür eine andere Referenz gemeldet. Es wird nichts geändert.
Die Bestätigung antwortet Gateway not configured: Die Schlüssel der Umgebung der Zahlung sind leer. Geben Sie sie erneut ein. Flow wiederholt die Bestätigung.
Die Bestätigung antwortet Flow API unavailable or Busy, retry: Die Statusanfrage an Flow ist fehlgeschlagen, oder die Bestellung wurde im selben Moment von einer anderen Anfrage angelegt. Flow wiederholt die Bestätigung.
Der Kunde sieht Flow payments are not available at the moment: Die Schlüssel fehlen, oder Flow hat sie abgelehnt. Prüfen Sie den API Key und den Secret Key des aktuellen Modus.
Der Kunde sieht A valid billing email is required for Flow payments: Flow benötigt die E-Mail-Adresse des Kunden.
Der Kunde sieht The order total is too small to be paid with Flow: Der Gesamtbetrag des Warenkorbs rundet in der Warenkorbwährung auf null.
Der Kunde hat bezahlt, aber die Bestellung ist Awaiting Flow payment oder Flow payment on hold: Lesen Sie die Notizen im Block Flow payment. Der Kunde hat einen Barzahlungsbeleg erstellt, der noch nicht bezahlt ist, oder Betrag bzw. Währung, die Flow meldet, stimmen nicht mit der Bestellung überein. CLP-Summen mit Nachkommastellen werden auf ganze Pesos gerundet; stellen Sie daher die Genauigkeit von CLP auf 0.
Erstattung schlägt mit einer Meldung zu den Sandbox- oder Live-Schlüsseln fehl: Die Bestellung wurde in dieser Umgebung bezahlt, und deren Schlüssel sind leer. Geben Sie sie ein und versuchen Sie es erneut.
Erstattung schlägt mit Flow accepts CLP refunds in whole units only fehl: Geben Sie einen ganzen Betrag ein.
Für Entwickler listet die README die Hooks actionWcpFlowSupportedCurrencies (Währungen, für die die Zahlungsmethode angeboten wird) und actionWcpFlowPaymentSubject (der an Flow gesendete Zahlungsbetreff).
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Flow 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 Moduleinstellungen und das Protokoll entfernt. Ist es deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Flow-Zahlungs- und Erstattungsdaten sowie die Bestellstatus Awaiting Flow payment und Flow payment on hold bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
Flow ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Flow verbunden und wird von Flow weder unterstützt noch empfohlen.