VibeFox Kushki for WooCommerce — Hilfe
Anforderungen
WordPress: 6.0 oder neuer.
WooCommerce: 8.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.
PHP: 8.0 oder neuer.
Shopwährung: USD (Ecuador) oder COP (Kolumbien). Für andere Währungen wird die Zahlungsmethode an 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 Produktivkontos. 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-Lizenzschlüssel: wird auf vibefox.net gekauft. 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 und klicken Sie auf Install Now. Sie können den Ordner wcp_kushki_payment auch per FTP nach /wp-content/plugins/ hochladen.
2. Klicken Sie auf Activate.
3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Kushki > Manage oder klicken Sie auf der Plugins-Seite unter dem Plugin-Namen auf Settings.
4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.
5. Geben Sie die öffentliche und die private Test-Merchant-ID ein und lassen Sie Test mode aktiviert. Optional richten Sie den Webhook in der Kushki Console ein und fügen dessen Signaturschlüssel ein (siehe Konfiguration).
6. Aktivieren Sie Enable / Disable und führen Sie eine Testbestellung durch. Wenn alles bereit ist, tragen Sie die Live-Merchant-IDs (und die Live-Webhook-Signatur) ein und deaktivieren Test mode.
Konfiguration
Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Kushki. Oberhalb der Felder warnt die Seite, wenn die Zahlungsmethode aktiviert ist, aber die Merchant-IDs des aktuellen Modus fehlen (die Zahlungsmethode wird dann an der Kasse ausgeblendet), wenn die Shopwährung nicht unterstützt wird, wenn der Live-Modus ohne HTTPS verwendet wird und wenn im aktuellen Modus keine Webhook-Signatur hinterlegt ist. Solange der Testmodus aktiv ist, zeigt sie Test mode is on: the Kushki test environment is used, no real money is charged. an. Wenn Sie speichern, während die Zahlungsmethode aktiviert, aber die Merchant-IDs des aktuellen Modus nicht eingetragen sind, erinnert ein Fehler daran, sie einzutragen. Leerzeichen um die IDs werden beim Speichern entfernt.
Allgemein
Enable / Disable: Enable Kushki card payments schaltet die Zahlungsmethode ein oder aus. Standard: aus.
Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Credit / debit card (Kushki).
Description: der Text über dem Kartenformular an der Kasse. 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 Produktivkonten haben unterschiedliche IDs. Der Testmodus verwendet nur die Test-IDs, der Live-Modus nur die Live-IDs.
Test mode: Use the Kushki test (UAT) environment schaltet Merchant-IDs, Kartenformular und API gemeinsam auf die Kushki-Testumgebung um. Es wird kein echtes Geld belastet, und an der Kasse wird ein Abzeichen TEST MODE angezeigt. Standard: ein. Deaktivieren Sie es, um echte Zahlungen anzunehmen.
Test Public Merchant ID: die öffentliche Merchant-ID Ihres Kushki-Testkontos. Sie lädt das Kartenformular.
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-Produktivkontos.
Live Private Merchant ID: die private Merchant-ID Ihres Kushki-Produktivkontos. Halten Sie sie geheim.
Webhook (empfohlen)
Zahlungen werden sofort durch die Antwort der Kushki-API bestätigt, daher ist der Webhook nicht erforderlich. Er bestätigt zusätzlich Zahlungen, 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 URL hinzu, die in diesem Abschnitt der Einstellungen für Kartenzahlungen angezeigt wird. Sie hat die Form https://your-site/wc-api/webhook_kushki_p/. Tun Sie dies für das Testkonto und für das Produktivkonto.
Das Plugin verarbeitet diese Kartenbenachrichtigungen:
Test webhook signature: der Webhook-Signaturschlüssel des Kushki-Testkontos (Console > Webhooks).
Live webhook signature: der Webhook-Signaturschlüssel des Kushki-Produktivkontos.
Webhooks ohne gültige Signatur werden abgelehnt. Ohne Signaturschlüssel werden alle Webhook-Benachrichtigungen abgelehnt, Zahlungen funktionieren aber weiterhin, weil sie durch die API-Antwort bestätigt werden.
Erweitert
Debug log: Log API calls and webhooks schreibt Kushki-Anfragen und Webhooks in WooCommerce > Status > Logs, Quelle wcp_kushki_payment. Fehler werden immer protokolliert. Protokolle enthalten nie Merchant-IDs, Kartentoken oder E-Mail-Adressen von Kunden. Standard: aus.
Delete data on uninstall: wenn aktiviert, entfernt das Löschen des Plugins die Einstellungen und Protokolle. Bestellungen und ihre Kushki-Referenzen bleiben erhalten. Standard: aus.
Kasse
Der Kunde wählt die Zahlungsmethode (standardmäßig Credit / debit card (Kushki)). Darunter erscheint das Kushki-Kartenformular mit dem Bestellbetrag in der Bestellwährung. Auf der Seite Pay for order verwendet das Formular den Bestellbetrag. Der Kunde gibt die Karte ein, wählt Ratenzahlungen, falls das Kushki-Formular sie anbietet, und drückt den Bezahlen-Button innerhalb des Kushki-Formulars.
In der klassischen Kasse wird der WooCommerce-Button Place order ausgeblendet, solange Kushki ausgewählt ist: Nachdem die Karte akzeptiert wurde, wird die Bestellung automatisch abgeschickt. Im Kassen-Block drückt der Kunde ebenfalls den Bezahlen-Button innerhalb des Kushki-Formulars. Versucht der Kunde, die Bestellung ohne dies abzuschicken, wird die Meldung Please enter your card details in the Kushki form and press its pay button. angezeigt.
Ihr Shop belastet die Karte danach serverseitig. Die Bestellung wird erst als bezahlt markiert, wenn Kushki sie mit einer Ticketnummer bestätigt, und der Kunde gelangt direkt zur Bestellbestätigungsseite. Meldet Kushki einen genehmigten Betrag oder eine genehmigte Währung, werden diese mit der Bestellung verglichen.
Wird die Karte abgelehnt, sieht der Kunde Your payment was declined mit dem Grund von Kushki und kann im selben Formular eine andere Karte versuchen. Bei Netzwerk-, Schlüssel- oder Serverproblemen sieht der Kunde The payment could not be processed right now. Please try again in a moment or choose another payment method. Der technische Grund wird den Bestellnotizen und dem Protokoll hinzugefügt. Ein zweiter Klick, während eine Zahlung verarbeitet wird, zeigt A payment for this order is already being processed. Please wait a moment and check your order status.
Die Zahlungsmethode funktioniert in der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel. 3-D Secure, Betrugsregeln und die angebotenen Ratenzahlungen werden in der Kushki Console eingerichtet.
Das Plugin unterstützt nur Kartenzahlungen mit einem Schritt. Es hat keine Teilerstattungen, gespeicherte Karten, Abonnements oder Add payment method, keine Barzahlung, Banküberweisung (PSE) oder Debitkartenzahlungen per Weiterleitung und kein getrenntes Autorisieren und Erfassen.
Bestellungen und Erstattungen
Bestellstatus
Pending payment: die Bestellung wurde angelegt, und die Karte wurde noch nicht belastet.
Processing: Kushki hat die Belastung bestätigt (durch die API-Antwort oder durch den Webhook). Bestellungen mit nur virtuellen, herunterladbaren Produkten werden auf Completed gesetzt, dem WooCommerce-Standard. Die Bestellnotiz zeigt den Modus, die Kushki-Ticketnummer und die Referenz. Die Transaktions-ID ist die Kushki-Transaktionsreferenz (oder die Ticketnummer).
On hold: Kushki hat einen Erfolg ohne Ticketnummer gemeldet oder einen anderen Betrag oder eine andere Währung als die Bestellung. Die Bestellnotiz erklärt dies. Prüfen Sie die Transaktion in der Kushki Console und führen Sie die Bestellung aus oder erstatten Sie die Zahlung.
Failed: die Karte wurde abgelehnt oder die Belastung konnte nicht durchgeführt werden. Die Bestellnotiz zeigt den Kushki-Code und die Meldung. Der Kunde kann erneut bezahlen.
Meldet ein Webhook eine weitere genehmigte Belastung für eine bereits bezahlte, stornierte oder erstattete Bestellung, wird die Bestellung nicht verändert. Eine Notiz fordert Sie auf, eine Doppelbelastung zu prüfen und in der Kushki Console zu erstatten. Ein Webhook aus der Testumgebung für eine Live-Bestellung (oder umgekehrt) wird mit einer Notiz ignoriert.
Erstattungen
Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den vollen Bestellbetrag ein und klicken Sie auf Refund via Credit / debit card (Kushki) (die Schaltfläche zeigt Ihren Title). Kushki erstattet die gesamte Zahlung, daher werden nur vollständige Erstattungen akzeptiert. Bei einem Teilbetrag zeigt das Plugin Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. Eine Zahlung kann einmal erstattet werden.
Die Erstattung wird im Modus gesendet, in dem die Zahlung erfolgt ist (Test oder Live), daher muss die private Merchant-ID dieses Modus eingetragen sein. Akzeptiert Kushki die Erstattung nicht, zeigt WooCommerce den Fehler an und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit dem Kushki-Erstattungsticket den Bestellnotizen hinzugefügt.
In der Kushki Console vorgenommene Stornierungen und Erstattungen kommen per Webhook an und werden den Bestellnotizen hinzugefügt. Sie werden nicht automatisch als WooCommerce-Erstattungen erfasst.
Lizenzschlüssel
Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Kushki. 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 Kushki 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 Zahlungsmethode weiterhin, mit dem Zusatz (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Auf der Plugins-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind nicht betroffen: Webhooks werden weiter verarbeitet und Erstattungen funktionieren.
Läuft eine Lizenz ab, arbeitet das Plugin weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.
Fehlerbehebung
Kushki erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und der aktuelle Modus beide Merchant-IDs hat: die Test-IDs im Testmodus, die Live-IDs im Live-Modus. Prüfen Sie, dass die Shopwährung (oder die Bestellwährung auf der Seite Pay for order) USD oder COP ist. Die Einstellungsseite zeigt für jedes dieser Probleme eine Warnung an.
Die Zahlung ist erfolgt, aber die Bestellung ist Failed oder bleibt bei Pending payment: die Antwort der Kushki-API ging verloren, zum Beispiel durch ein Timeout. Der Webhook bestätigt solche Zahlungen. Prüfen Sie in der Kushki Console, dass die Webhook-URL genau der in den Einstellungen angezeigten entspricht, für das Konto des von Ihnen verwendeten Modus, und dass der Signaturschlüssel dieses Kontos im passenden Feld steht (Test webhook signature oder Live webhook signature). Eine genehmigte Belastung ohne den bezahlten Betrag und die Währung setzt die Bestellung stattdessen auf Wartestellung.
Webhook meldet Webhook signature not configured: keine der beiden Webhook-Signaturen ist eingetragen. Fügen Sie den Signaturschlüssel in den Einstellungen ein.
Webhook meldet Invalid signature: der Signaturschlüssel gehört zu einem anderen Konto oder Modus, oder die Benachrichtigung wurde unterwegs verändert.
Webhook meldet Order mismatch: die Benachrichtigung gehört nicht zu dieser Bestellung (falscher Bestellschlüssel oder falsche Transaktion). Die Bestellung wird nicht verändert.
Webhook meldet Busy, retry later: die Bestellung wurde im selben Moment von einer anderen Anfrage verarbeitet. Kushki kann die Benachrichtigung erneut senden.
Das Kartenformular lädt nicht: der Kunde sieht The Kushki card form could not be loaded. Please reload the page or choose another payment method. Prüfen Sie die öffentliche Merchant-ID des aktuellen Modus.
Der Kunde sieht This payment option is not available in this store. Please pay by card.: im Kushki-Formular wurde eine Zahlungsoption gewählt, die keine Karte ist. Das Plugin belastet nur Karten.
Der Kunde sieht beim Bezahlen einen Fehler: öffnen Sie die Bestellnotizen oder aktivieren Sie das Debug log und sehen Sie unter WooCommerce > Status > Logs (Quelle wcp_kushki_payment) nach. Eine falsche oder fehlende private Merchant-ID führt zur allgemeinen Meldung, dass die Zahlung nicht verarbeitet werden konnte.
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 eingetragen. Tragen Sie sie ein und versuchen Sie es erneut.
Erstattung schlägt mit No Kushki ticket number found for this order fehl: die Bestellung hat keine bestätigte Kushki-Belastung. Erstatten Sie sie in der Kushki Console.
Andere Währungen: Entwickler können die Währungsliste auf eigenes Risiko mit dem Filter kushki_p_supported_currencies ändern. Die Währung muss in Ihrem Kushki-Konto aktiviert 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. Hat sich die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.
Deinstallation
Beim Deaktivieren des Plugins bleiben alle Daten erhalten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Die Einstellungen der Zahlungsmethode und die Protokolle werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Kushki-Ticketnummern und Transaktions-IDs.
Kushki ist eine Marke des jeweiligen Inhabers. Dieses Plugin ist nicht mit Kushki verbunden und wird von Kushki nicht empfohlen.