VibeFox Kushki 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: USD (Ecuador) oder COP (Kolumbien). Bei Warenkörben in anderen Währungen wird die Zahlungsart in der Kasse ausgeblendet.
HTTPS: Kushki verlangt, dass die Kasse im Live-Modus über HTTPS ausgeliefert wird.
Kushki-Konto: Sie benötigen die öffentliche und die private Merchant-ID Ihres Kushki-Testkontos (UAT) und Ihres Produktionskontos. Sie finden sie in der Kushki Console unter Developers > Credentials. Für den optionalen Webhook benötigen Sie außerdem den Webhook-Signaturschlüssel jedes Kontos (siehe Konfiguration).
VibeFox license key: erhältlich auf vibefox.net. 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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Kushki Payment in der Modulliste und klicken Sie auf Configure.
3. Geben 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 die öffentliche und die private Merchant-ID des Testkontos ein und lassen Sie Test mode aktiviert. Optional richten Sie in der Kushki Console den Webhook ein und fügen dessen Signaturschlüssel ein (siehe Konfiguration).
5. Aktivieren Sie Enable / Disable, klicken Sie auf Save und platzieren Sie eine Testbestellung. Wenn alles bereit ist, geben Sie die Live-Merchant-IDs (und die Live-Webhook-Signatur) ein und deaktivieren Sie Test mode.
Bei der Installation legt das Modul den Bestellstatus Kushki payment on hold an. PrestaShop weist einem neuen Zahlungsmodul die Währungen, Länder und Kundengruppen Ihres Shops zu. Prüfen Sie unter Payment > Preferences, ob das Modul für USD oder COP und für Ecuador oder Kolumbien erlaubt ist.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Kushki Payment > Configure. Jeder Abschnitt hat einen eigenen Button Save, der die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn die Zahlungsart aktiviert ist, aber die Merchant-IDs des aktuellen Modus fehlen (die Zahlungsart wird dann in der Kasse ausgeblendet), wenn die Standardwährung Ihres Shops nicht USD oder COP ist, wenn der Live-Modus ohne HTTPS genutzt wird und wenn für den aktuellen Modus kein Webhook-Signaturschlüssel hinterlegt ist. Solange der Testmodus aktiviert ist, zeigt sie Testmodus ist aktiviert: Die Kushki-Testumgebung wird verwendet, es wird kein echtes Geld belastet. Wenn Sie speichern, während die Zahlungsart aktiviert, aber die Merchant-IDs des aktuellen Modus fehlen, werden die Einstellungen gespeichert, und eine Meldung erinnert Sie daran, sie einzugeben. Leerzeichen um die IDs werden beim Speichern entfernt.
Kushki
Enable / Disable: Enable Kushki card payments schaltet die Zahlungsart ein oder aus. Standard: aus.
Title: der Name der Zahlungsart, den Kunden in der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Credit / debit card (Kushki). Pflichtfeld.
Description: der Text, der in der Kasse über dem Kartenformular angezeigt wird. Standard: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.
API-Zugangsdaten
Kopieren Sie die öffentliche und die private Merchant-ID aus der Kushki Console (Developers > Credentials). Test- (UAT) und Produktionskonten haben unterschiedliche IDs. Der Testmodus verwendet nur die Test-IDs, der Live-Modus nur die Live-IDs.
Test mode: nutzt die Kushki-Testumgebung (UAT): die Test-Merchant-IDs, das Test-Kartenformular und die Test-API gemeinsam. Es wird kein echtes Geld belastet, und in der Kasse wird das Abzeichen TEST MODE angezeigt. Standard: aktiviert. Deaktivieren Sie es, um echte Zahlungen anzunehmen. Erstattungen gehen immer in die Umgebung, in der die Zahlung erfolgt ist.
Test Public Merchant ID: die öffentliche Merchant-ID Ihres Kushki-Testkontos. Mit ihr wird das Kartenformular geladen.
Test Private Merchant ID: die private Merchant-ID Ihres Kushki-Testkontos. Sie wird serverseitig für Belastungen und Erstattungen verwendet.
Live Public Merchant ID: die öffentliche Merchant-ID Ihres Kushki-Produktionskontos.
Live Private Merchant ID: die private Merchant-ID Ihres Kushki-Produktionskontos. Halten Sie sie geheim.
Gespeicherte private Merchant-IDs und Webhook-Signaturen werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Gespeichert — leer lassen, um den Wert beizubehalten. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.
Webhook (empfohlen)
Zahlungen werden sofort durch die Antwort der Kushki-API bestätigt, daher ist der Webhook nicht erforderlich. Zusätzlich legt er die Bestellung für eine Zahlung an, deren Antwort verloren ging (zum Beispiel bei einem Timeout), und meldet Stornierungen und Erstattungen, die in der Kushki Console vorgenommen wurden. Fügen Sie in der Kushki Console (Webhooks) die unter Webhook URL angezeigte URL für Kartenzahlungen hinzu. Mit aktivierten freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_kushki_payment/webhook, gegebenenfalls mit einem Sprachcode wie /es/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. Tun Sie dies für das Testkonto und für das Produktionskonto.
Das Modul verarbeitet diese Kartenbenachrichtigungen:
Test webhook signature: der Webhook-Signaturschlüssel des Kushki-Testkontos (Console > Webhooks).
Live webhook signature: der Webhook-Signaturschlüssel des Kushki-Produktionskontos.
Clear saved secrets: markieren Sie eine private Merchant-ID oder eine Webhook-Signatur und klicken Sie auf Save, um sie zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Webhooks ohne gültige Signatur werden abgelehnt. Eine Benachrichtigung muss mit dem Schlüssel des Modus signiert sein, in dem die Zahlung erfolgt ist, sodass eine Testbenachrichtigung nie eine Live-Zahlung bestätigt. Ohne Signaturschlüssel werden alle Webhook-Benachrichtigungen abgelehnt, Zahlungen funktionieren aber weiterhin, weil sie durch die API-Antwort bestätigt werden.
Erweitert
Debug log: schreibt Kushki-Anfragen und Webhooks in logs/kushki_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler werden immer protokolliert. Protokolle enthalten nie Merchant-IDs, Kartentoken oder E-Mail-Adressen von Kunden. 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 das Deinstallieren des Moduls die Einstellungen und die Protokolle. Die Kushki-Zahlungsdaten (Belastungen und Erstattungen) und der Bestellstatus Kushki payment on hold bleiben immer erhalten, damit alte Bestellungen nach einer Neuinstallation noch erstattet werden können. Standard: aus.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Credit / debit card (Kushki)). Darunter erscheint das Kartenformular von Kushki mit der Warenkorbsumme in der Warenkorbwährung. Der Kunde gibt die Karte ein, wählt Ratenzahlungen, falls das Kushki-Formular sie anbietet, und drückt die Schaltfläche zum Bezahlen im Kushki-Formular.
Der PrestaShop-Button Place order bleibt sichtbar, weil er die Allgemeinen Geschäftsbedingungen enthält. Sind die Bedingungen bereits akzeptiert, wird die Zahlung nach der Bezahlen-Schaltfläche von Kushki automatisch übermittelt. Andernfalls sieht der Kunde Ihre Karte wurde von Kushki akzeptiert. Akzeptieren Sie die Allgemeinen Geschäftsbedingungen und klicken Sie auf „Place order“, um zu bezahlen. Drückt der Kunde Place order, ohne das Kushki-Formular zu benutzen, erscheint die Meldung Bitte geben Sie Ihre Kartendaten im Kushki-Formular ein und drücken Sie dessen Bezahlen-Schaltfläche.
Ihr Shop belastet die Karte danach serverseitig. Die Bestellung wird erst als bezahlt markiert, nachdem Kushki sie mit einer Ticketnummer bestätigt hat. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite mit Ihre Kartenzahlung wurde empfangen. Meldet Kushki einen Betrag oder eine Währung, werden diese mit dem Warenkorb verglichen. Eine Bestellung auf Wartestellung zeigt Ihre Zahlung wird geprüft. Wir aktualisieren Ihre Bestellung, sobald die Prüfung abgeschlossen ist.
Wird die Karte abgelehnt, wird keine Bestellung angelegt, und der Kunde kehrt zum Zahlungsschritt zurück, mit Ihre Zahlung wurde abgelehnt und dem Grund von Kushki, und kann eine andere Karte versuchen. Bei Netzwerk-, Schlüssel- oder Serverproblemen sieht der Kunde Die Zahlung kann im Moment nicht verarbeitet werden. Bitte versuchen Sie es in Kürze erneut oder wählen Sie eine andere Zahlungsart. Der technische Grund wird im Protokoll festgehalten. Ein zweiter Klick, während eine Zahlung verarbeitet wird, zeigt Für diese Bestellung wird bereits eine Zahlung verarbeitet. Bitte warten Sie einen Moment und prüfen Sie Ihren Bestellstatus.
Geht die Antwort von Kushki verloren (zum Beispiel bei einem Timeout), sieht der Kunde die allgemeine Meldung, der Belastungsversuch bleibt aber erhalten. Sobald der signierte Webhook die genehmigte Belastung meldet, wird die Bestellung angelegt. Ein Warenkorb, der bereits eine Bestellung hat, oder eine genehmigte Belastung, deren Bestellung noch nicht angelegt wurde, wird nie erneut belastet: Der Kunde sieht die Bestätigung dieser Bestellung. Zahlt der Kunde erneut, bevor ein Webhook eintrifft, ist dies eine neue Belastung; eine verspätete Genehmigung der ersten Belastung fügt dann nur eine Notiz über eine mögliche Doppelbelastung hinzu.
Der Webhook funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert. 3-D Secure, Betrugsregeln und die angebotenen Ratenzahlungen werden in der Kushki Console eingerichtet.
Das Modul unterstützt nur Kartenzahlungen mit einem Schritt. Es unterstützt keine Teilerstattungen, gespeicherten Karten oder Abonnements, keine Barzahlung, Banküberweisung (PSE) oder Debitkartenzahlungen per Weiterleitung und kein getrenntes Autorisieren und Erfassen.
Bestellungen und Erstattungen
Bestellstatus
No order yet: der Kunde hat nicht bezahlt, die Karte wurde abgelehnt, oder die Antwort von Kushki ging verloren und der Webhook ist noch nicht eingetroffen. Es existiert nur der Warenkorb.
Payment accepted: Kushki hat die Belastung bestätigt (durch die API-Antwort oder durch den Webhook). Die Zahlung wird mit der Kushki-Transaktionsreferenz (oder der Ticketnummer) als Transaktions-ID erfasst. Eine Notiz zeigt den Modus, die Kushki-Ticketnummer und die Referenz.
Kushki payment on hold: Kushki meldete einen Erfolg ohne Ticketnummer, meldete einen anderen Betrag oder eine andere Währung als der Warenkorb, oder der Warenkorb wurde während der Zahlung geändert. Die Notiz erklärt das. Prüfen Sie die Transaktion in der Kushki Console und versenden Sie die Bestellung oder erstatten Sie die Zahlung. Eine spätere signierte Genehmigung mit Ticketnummer und passendem Betrag setzt die Bestellung auf Payment accepted.
Payment error: der Webhook meldete, dass die Belastung einer Bestellung auf Wartestellung abgelehnt wurde.
Refunded: die Zahlung wurde über das Modul erstattet.
Meldet Kushki eine weitere genehmigte Belastung für eine Bestellung, die bereits bezahlt, storniert oder erstattet ist, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, auf eine Doppelbelastung zu prüfen und sie in der Kushki Console zu erstatten. Ein Webhook aus der Testumgebung für eine Live-Zahlung (oder umgekehrt) wird mit einer Notiz ignoriert.
Kushki-Zahlungsblock
Die Bestellseite zeigt einen Block Kushki payment mit Ticketnummer, Transaktionsreferenz, Umgebung (mit einem Abzeichen Test für Testzahlungen), Status der Belastung, belastetem Betrag und Bestellsumme, dem Erstattungsformular, dem Erstattungsverlauf und den Kushki notes der Bestellung.
Erstattungen
Kushki erstattet die gesamte Belastung, daher sind nur vollständige Erstattungen möglich. Im Block Kushki payment ist der von Kushki belastete Betrag bereits eingetragen. Geben Sie optional einen Grund ein und klicken Sie auf Refund via Kushki, und bestätigen Sie dann die Frage Die gesamte Zahlung über Kushki erstatten? Dies kann nicht rückgängig gemacht werden. Sie benötigen das Recht, Bestellungen zu bearbeiten. Bei jedem anderen Betrag zeigt das Modul Kushki erstattet nur die vollständige Zahlung. Geben Sie den gesamten belasteten Betrag ein an, und es wird nichts gesendet. Die Erstattung erfolgt in dem Betrag und der Währung, die Kushki belastet hat. Bei einer Betragsabweichung erhält der Kunde also zurück, was tatsächlich belastet wurde, nicht die Bestellsumme. Eine Zahlung kann einmal erstattet werden.
Die Erstattung wird in dem Modus gesendet, in dem die Zahlung erfolgt ist (Test oder Live), daher muss dessen private Merchant-ID gesetzt sein. Akzeptiert Kushki die Erstattung nicht, zeigt der Block Kushki-Erstattung fehlgeschlagen mit dem Kushki-Code und der Meldung an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit dem Kushki-Erstattungsticket hinzugefügt, und die Bestellung wird auf Refunded gesetzt. Erstattungen erfordern eine bestätigte Kushki-Belastung mit Ticketnummer.
Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsbuttons von PrestaShop auf der Bestellseite senden kein Geld über Kushki zurück. Stornierungen und Erstattungen, die in der Kushki Console vorgenommen wurden, kommen über den Webhook und werden den Notizen hinzugefügt. Der Bestellstatus wird nicht automatisch geändert.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Kushki Payment ist der erste Block auf Modules > Module Manager > VibeFox Kushki Payment > 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 gültig ist, und Ihre Domain) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: presta-payment-kushki 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 nachdem Sie einen Domain-Platz in Ihrem Konto freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.
Ein Schlüssel funktioniert auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-Konfiguration. Wenn Sie den Schlüssel aus dem Shop entfernen, wird sein Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.
Ohne aktiven Schlüssel wird Kushki Kunden in der Kasse nicht angezeigt. Versucht ein Kunde trotzdem zu bezahlen, sieht er This payment method is not available. Please choose another one. Die Storefront von PrestaShop weiß nicht, dass Sie im Back Office angemeldet sind; daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht an der Kasse testen. Eine Erinnerung erscheint in 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, Updates und Support benötigen jedoch eine Verlängerung. Der Status wird automatisch erneut geprüft, während Sie im Back Office arbeiten: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal wöchentlich. Ein Cron-Job ist nicht erforderlich. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
Kushki erscheint nicht in der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable aktiviert ist und der aktuelle Modus beide Merchant-IDs hat: die Test-IDs im Testmodus, die Live-IDs im Live-Modus. Prüfen Sie, ob die Warenkorbwährung USD oder COP ist. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist. Die Einstellungsseite zeigt eine Warnung, wenn die IDs fehlen.
Die Zahlung ging durch, aber es wurde keine Bestellung angelegt: die Antwort der Kushki-API ging verloren, zum Beispiel durch ein Timeout. Der Webhook legt die Bestellung für solche Zahlungen an. Prüfen Sie in der Kushki Console, ob die Webhook-URL genau der unter Webhook URL angezeigten entspricht, für das Konto des von Ihnen genutzten Modus, und ob der Signaturschlüssel dieses Kontos im passenden Feld steht (Test webhook signature oder Live webhook signature). Eine genehmigte Belastung ohne bezahlten Betrag und ohne Währung legt die Bestellung in Kushki payment on hold an.
Webhook answers Webhook signature not configured: keine der beiden Webhook-Signaturen ist gesetzt. Fügen Sie den Signaturschlüssel in die Einstellungen ein.
Webhook answers Invalid signature: der Signaturschlüssel gehört zu einem anderen Konto oder Modus, oder die Benachrichtigung wurde unterwegs verändert.
Webhook answers Order mismatch: die Benachrichtigung gehört nicht zu einer Belastung dieses Warenkorbs (falscher Versuchsschlüssel oder falsche Transaktion). Es wird nichts geändert.
Webhook answers Busy, retry later: die Bestellung wurde im selben Moment von einer anderen Anfrage verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Kushki kann die Benachrichtigung erneut senden. Fehler werden immer im Protokoll festgehalten.
Die Webhook-URL zeigt im Browser nur POST an: das ist normal. Die URL akzeptiert nur Benachrichtigungen von Kushki.
Das Kartenformular lädt nicht: der Kunde sieht Das Kushki-Kartenformular konnte nicht geladen werden. Bitte laden Sie die Seite neu oder wählen Sie eine andere Zahlungsart. Prüfen Sie die öffentliche Merchant-ID des aktuellen Modus.
Der Kunde sieht Diese Zahlungsart ist in diesem Shop nicht verfügbar. Bitte bezahlen Sie mit Karte.: im Kushki-Formular wurde eine Zahlungsart gewählt, die keine Karte ist. Das Modul belastet nur Karten.
Der Kunde sieht einen Fehler beim Bezahlen: aktivieren Sie das Debug log und prüfen Sie das Feld Log auf der Modulseite. Eine falsche oder fehlende private Merchant-ID führt zur allgemeinen Meldung, dass die Zahlung nicht verarbeitet werden konnte.
Der Kunde sieht Ihre Zahlung wurde empfangen, aber die Bestellung konnte nicht automatisch abgeschlossen werden: Kushki hat die Belastung genehmigt, aber PrestaShop konnte die Bestellung nicht anlegen. Das Protokoll zeigt den Grund. Der nächste Zahlungsversuch desselben Warenkorbs legt die Bestellung ohne eine neue Belastung an.
Erstattung schlägt mit einer Meldung zum Modus fehl: die Zahlung erfolgte im Test- oder Live-Modus, und die private Merchant-ID dieses Modus ist nicht gesetzt. Geben Sie sie ein und versuchen Sie es erneut.
Erstattung wird nicht angeboten, mit der Meldung Für diese Bestellung wurde keine Kushki-Ticketnummer gefunden: die Bestellung hat keine bestätigte Kushki-Belastung. Erstatten Sie sie in der Kushki Console.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Kushki Payment 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 und die Protokolle entfernt. Ist es deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Kushki-Zahlungsdaten (Belastungen und Erstattungen) und der Bestellstatus Kushki payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation noch erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Kushki-Ticketnummern und Transaktions-IDs.
Kushki ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Kushki verbunden noch wird es von Kushki unterstützt.