VibeFox Culqi for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

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

PHP: 8.0 oder neuer.

Shop-Währung: Peruanischer Sol (PEN) oder US-Dollar (USD). Culqi akzeptiert keine anderen Währungen, und bei jeder anderen Shop-Währung wird die Zahlungsart an der Kasse ausgeblendet.

Culqi-Konto: Sie benötigen den öffentlichen und den geheimen Schlüssel Ihres Culqi-Kontos. Integrationsschlüssel (Test) erhalten Sie auf integ-panel.culqi.com, Produktionsschlüssel (Live) auf mipanel.culqi.com, unter CulqiPanel > Desarrollo > API Keys. Der öffentliche Schlüssel wird vom Culqi-Popup im Browser verwendet. Der geheime Schlüssel wird nur auf Ihrem Server verwendet und nie an den Browser gesendet. Ein Webhook ist nicht nötig.

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 und klicken Sie auf Install Now. Sie können den Ordner wcp_culqi_payment auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Culqi > Manage, oder klicken Sie auf der Seite „Plugins“ 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. Fügen Sie die Integrationsschlüssel und für echte Zahlungen die Produktionsschlüssel ein (siehe Konfiguration).

6. Schalten Sie Enable/Disable ein. Lassen Sie Test Mode während des Testens eingeschaltet und entfernen Sie dann den Haken, um echte Zahlungen anzunehmen.

7. Stellen Sie sicher, dass die Shop-Währung PEN oder USD ist.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Culqi. Über den Feldern zeigt die Seite Test mode is active: the integration keys are used and no real money is charged., solange der Testmodus aktiv ist. Sie warnt Sie, wenn das Gateway aktiviert ist, aber die Schlüssel des aktuellen Modus fehlen, und wenn die Shop-Währung von Culqi nicht unterstützt wird. In beiden Fällen wird die Zahlungsart an der Kasse ausgeblendet. In der Liste der Zahlungsarten ist Culqi als einrichtungsbedürftig markiert, bis beide Schlüssel des aktuellen Modus gesetzt sind.

Allgemein

Enable/Disable: Enable Culqi Payment Gateway schaltet die Zahlungsart ein oder aus. Standard: aus.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: Credit/Debit Card or Yape (Culqi).

Description: der Text, der an der Kasse unter der Zahlungsart angezeigt wird. Standard: Pay securely with your credit/debit card or Yape via Culqi.

API-Schlüssel

Kopieren Sie die Schlüssel aus CulqiPanel > Desarrollo > API Keys: Integrationsschlüssel (Test) auf integ-panel.culqi.com, Produktionsschlüssel auf mipanel.culqi.com. Der Testmodus verwendet nur die Testschlüssel, der Live-Modus nur die Live-Schlüssel. Jeder Schlüssel muss mit dem Präfix seines Feldes beginnen. Ein Schlüssel mit falschem Präfix wird nicht gespeichert: Die Seite zeigt einen Fehler und behält den vorherigen Wert.

Test Mode: Use the Culqi integration (test) environment. Wenn aktiviert, werden die Testschlüssel (pk_test_ / sk_test_) verwendet, und es wird kein echtes Geld belastet. Standard: ein. Entfernen Sie den Haken, um mit den Live-Schlüsseln echte Zahlungen anzunehmen.

Test Public Key: der öffentliche Schlüssel der Integrationsumgebung. Er beginnt mit pk_test_.

Test Secret Key: der geheime Schlüssel der Integrationsumgebung. Er beginnt mit sk_test_ und wird nie mit dem Browser geteilt.

Live Public Key: der öffentliche Schlüssel der Produktionsumgebung. Er beginnt mit pk_live_.

Live Secret Key: der geheime Schlüssel der Produktionsumgebung. Er beginnt mit sk_live_ und wird nie mit dem Browser geteilt.

Wenn Sie von Version 1.0 aktualisieren, wird das einzelne Schlüsselpaar dieser Version anhand seines Präfixes in die Test- oder Live-Felder übernommen. Prüfen Sie die Schlüssel nach dem Update.

Zahlungsarten

Karten werden immer angeboten. Banküberweisung, Agenten, Wallets und Cuotéalo benötigen die Culqi Orders API und werden von diesem Plugin nicht angeboten.

Yape: Offer Yape in the Culqi popup zeigt Yape neben den Karten im Culqi-Fenster an. Standard: ein.

Erweitert

Debug log: Log API requests and payment steps schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_culqi_payment. Fehler werden immer protokolliert. Schlüssel, Kartendaten und Kundendaten werden nie protokolliert. Standard: aus.

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted. Das Deaktivieren des Plugins löscht nie etwas. In Bestellungen gespeicherte Culqi-Daten bleiben immer erhalten. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Credit/Debit Card or Yape (Culqi)) und klickt auf die Schaltfläche zum Aufgeben der Bestellung. Das Culqi-Checkout-Popup öffnet sich auf derselben Seite mit dem Namen Ihres Shops, der Bestellsumme und der Währung. Dort gibt der Kunde die Kartendaten ein oder bezahlt mit Yape. Solange der Testmodus aktiv ist, zeigt die Zahlungsart TEST MODE: No real charges will be made.

Culqi wandelt die Zahlungsdaten in ein Einmal-Token um, und das Kassenformular wird mit diesem Token an Ihren Shop gesendet. Ihr Server erstellt die Belastung mit der Culqi Charges API für die Bestellsumme in der Bestellwährung, mit der Bestellnummer in der Beschreibung der Belastung. Die Bestellung wird erst als bezahlt markiert, nachdem Culqi die Belastung bestätigt hat und der belastete Betrag sowie die Währung mit der Bestellung übereinstimmen. Danach gelangt der Kunde auf die Seite „Bestellung erhalten“.

Verlangt die Bank 3-D Secure, sieht der Kunde Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. Nach der Authentifizierung wird die Belastung automatisch erneut gesendet. Wird die Verifizierung nicht abgeschlossen, sieht der Kunde The 3-D Secure verification was not completed. Please try again or use another card.

Wird die Karte abgelehnt, sieht der Kunde die Meldung von Culqi, zum Beispiel Payment failed: gefolgt vom Grund, und kann es mit einer anderen Karte erneut versuchen. Antwortet Culqi nicht, sieht der Kunde We could not confirm your payment with Culqi. Please check your email or contact us before trying again. Schließt der Kunde das Culqi-Fenster, wird nichts belastet, der Kunde sieht The payment window was closed before the payment was completed. und kann die Bestellung erneut aufgeben.

Die Zahlungsart 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.

Das Plugin akzeptiert nur einmalige Karten- und Yape-Zahlungen, die sofort erfasst werden. Es bietet keine PagoEfectivo- oder CIP-Codes, keine Bank-App, keine Agenten, keine Wallets und kein Cuotéalo, keine gespeicherten Karten, keine Abonnements oder Ratenzahlungen, keine Culqi-Webhooks und keine getrennte Autorisierung und Erfassung.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Die Bestellung wurde erstellt, aber noch nicht belastet, oder Culqi hat nicht geantwortet. In diesem Fall steht in einer Notiz Culqi did not confirm the charge. Prüfen Sie in CulqiPanel, ob es eine Belastung zu dieser Bestellung gibt, bevor Sie eine weitere Zahlung akzeptieren.

Processing: Die Zahlung wurde bestätigt (Standard von WooCommerce; Bestellungen mit ausschließlich virtuellen, herunterladbaren Produkten werden auf „Abgeschlossen“ gesetzt). Die Bestellnotiz zeigt die Culqi-Belastungs-ID, den Modus (Test oder Live) und ob 3-D Secure verwendet wurde. Die Transaktions-ID ist die Culqi-Belastungs-ID.

On hold: Culqi hat eine Belastung gemeldet, deren Betrag oder Währung nicht zur Bestellung passt, oder eine Zahlung, die autorisiert, aber nicht erfasst wurde. Die Bestellnotiz erklärt dies und zeigt die Belastungs-ID. Prüfen Sie die Belastung in CulqiPanel und schließen Sie die Bestellung manuell ab oder erstatten Sie sie.

Failed: Die Karte wurde abgelehnt. Die Bestellnotiz zeigt den Grund, den Ablehnungscode und die Belastungs-ID. Der Kunde kann mit einer anderen Karte erneut bezahlen.

Eine Bestellung, die bereits bezahlt ist oder bereits eine Culqi-Belastung hat, einschließlich einer Bestellung in Wartestellung, wird nie erneut belastet. Pro Bestellung wird immer nur eine Zahlungsanfrage gleichzeitig verarbeitet.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Culqi. Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird mit den Schlüsseln des Modus gesendet, in dem die Zahlung erfolgte (Test oder Live), auch wenn Sie den Modus inzwischen gewechselt haben; der geheime Schlüssel dieses Modus muss also gesetzt sein. Akzeptiert Culqi die Erstattung nicht, zeigt WooCommerce den Fehler an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird den Bestellnotizen mit der Culqi-Erstattungs-ID, dem Betrag und dem Grund hinzugefügt.

In CulqiPanel vorgenommene Erstattungen werden nicht zurück an WooCommerce synchronisiert. Legen Sie bei Bedarf in WooCommerce eine manuelle Erstattung ohne Refund via Culqi an.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben auf WooCommerce > Settings > Payments > Culqi. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status an, 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 Konto auf vibefox.net.

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 Konto auf vibefox.net frei.

Ohne aktiven Schlüssel wird Culqi den Kunden an der Kasse nicht angezeigt. Wird eine Zahlung trotzdem gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, gekennzeichnet mit (unlicensed — visible to admins only), sodass Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Auf der Seite „Plugins“ und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind nicht betroffen: Erstattungen funktionieren weiterhin.

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

Fehlerbehebung

Culqi erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, beide Schlüssel des aktuellen Modus gesetzt sind (Test Public Key und Test Secret Key im Testmodus, Live Public Key und Live Secret Key im Live-Modus) und die Shop-Währung PEN oder USD ist. Die Einstellungsseite zeigt in jedem dieser Fälle eine Warnung an.

Die Zahlung ging durch, aber die Bestellung bleibt auf Pending payment: Das Plugin verwendet keine Webhooks. Die Belastung wird nur durch die Antwort von Culqi an Ihren Server bestätigt. Hat Culqi nicht rechtzeitig geantwortet, steht in der Bestellnotiz Culqi did not confirm the charge. Suchen Sie die Belastung dieser Bestellung in CulqiPanel und schließen Sie die Bestellung, falls sie existiert, manuell ab.

Die Bestellung ist nach der Zahlung On hold: Lesen Sie die Bestellnotiz. Der belastete Betrag oder die Währung wich von der Bestellung ab, oder die Zahlung wurde nicht erfasst. Prüfen Sie die Belastung in CulqiPanel (ihre ID steht in der Notiz) und schließen Sie die Bestellung dann ab oder erstatten Sie sie.

Der Schlüssel wird nicht gespeichert: Der Fehler besagt, dass das Feld mit einem Präfix beginnen muss, zum Beispiel sk_live_. Jedes Feld akzeptiert nur Schlüssel seines eigenen Typs und Modus: pk_test_, sk_test_, pk_live_ oder sk_live_.

Der Kunde sieht Payment gateway misconfiguration. Please contact the store owner.: Die Schlüssel des aktuellen Modus fehlen, oder Culqi hat den geheimen Schlüssel abgelehnt. Prüfen Sie die Schlüssel in den Einstellungen.

Der Kunde sieht Payment token is invalid. Please try again.: Das Token aus dem Culqi-Fenster gehört zum anderen Modus, zum Beispiel nach dem Umschalten von Test Mode, während die Kassenseite geöffnet war. Der Kunde sollte die Seite neu laden und erneut bezahlen.

Das Culqi-Fenster öffnet sich nicht: Der Kunde sieht The Culqi payment window could not be loaded. Please reload the page and try again. Prüfen Sie, ob Skripte von js.culqi.com und 3ds.culqi.com auf Ihrer Kassenseite nicht blockiert werden, zum Beispiel durch ein Optimierungs-Plugin.

Der Kunde sieht This order is already being paid: Eine andere Zahlungsanfrage für dieselbe Bestellung lief im selben Moment. Der Kunde sollte warten und seine E-Mails prüfen, bevor er es erneut versucht.

Die Erstattung schlägt mit einer Meldung zu den Schlüsseln fehl: Die Zahlung erfolgte im Test- oder Live-Modus, und der geheime Schlüssel dieses Modus ist nicht gesetzt. Geben Sie ihn ein und versuchen Sie es erneut.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Wird der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, geben Sie in Ihrem Konto auf vibefox.net einen Platz frei und klicken Sie auf Check now. Hat sich die Website-Adresse 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.

Für Entwickler: Die Plugin-Dokumentation listet die Filter culqi_p_supported_currencies, culqi_p_charge_data, culqi_p_icon und culqi_p_lock_timeout auf.

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 Gateway-Einstellungen und die Protokolle werden nur entfernt, wenn Delete Data on Uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Culqi ist eine Marke des jeweiligen Inhabers. Dieses Plugin ist nicht mit Culqi verbunden und wird von Culqi nicht empfohlen.