VibeFox Culqi 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.

Shop-Währung: Peruanischer Sol (PEN) oder US-Dollar (USD). Culqi akzeptiert keine anderen Währungen, und die Zahlungsart wird nur für Warenkörbe in PEN oder USD angezeigt.

Culqi-Konto: Sie benötigen den öffentlichen und den geheimen Schlüssel Ihres Culqi-Kontos. Integrations- (Test-) Schlüssel stammen von integ-panel.culqi.com, Produktions- (Live-) Schlüssel von mipanel.culqi.com, jeweils 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 wird nicht benötigt.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert 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. Klicken Sie nach Abschluss des Uploads auf Configure, oder suchen Sie VibeFox Culqi Payment 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. Fügen Sie die Integrationsschlüssel und für echte Zahlungen die Produktionsschlüssel ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Lassen Sie Test Mode während des Tests aktiviert und schalten Sie ihn zum Annehmen echter Zahlungen aus.

6. Stellen Sie sicher, dass PEN oder USD eine aktive Währung Ihres Shops ist.

Bei der Installation legt das Modul den Bestellstatus Culqi payment on hold an. PrestaShop bietet eine neue Zahlungsart für alle Währungen, Länder und Kundengruppen an. Sie können diese unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Culqi Payment > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Über den Feldern zeigt die Seite bei aktiviertem Testmodus Test mode is active: the integration keys are used and no real money is charged. an. Sie warnt, wenn das Gateway aktiviert ist, aber die Schlüssel des aktuellen Modus fehlen, und wenn keine Shop-Währung von Culqi unterstützt wird. In beiden Fällen wird die Zahlungsart an der Kasse ausgeblendet. Wenn Ihre Standardwährung weder PEN noch USD ist, weist die Seite darauf hin, dass Culqi nur für Warenkörbe in den unterstützten Währungen angeboten wird.

Culqi

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. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Credit/Debit Card or Yape (Culqi). Pflichtfeld.

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, zum Beispiel Live Secret Key must start with sk_live_ — the previous value was kept., und die übrigen Felder werden gespeichert.

Test Mode: Wenn aktiviert, werden die Testschlüssel (pk_test_ / sk_test_) verwendet und kein echtes Geld belastet. Standard: an. Schalten Sie ihn aus, um echte Zahlungen mit den Live-Schlüsseln anzunehmen. Solange er aktiv ist, sehen Kunden TEST MODE: No real charges will be made. unter der Zahlungsart.

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 an den Browser weitergegeben.

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 an den Browser weitergegeben.

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

Clear saved secret keys: Setzen Sie ein Häkchen bei Test Secret Key oder Live Secret Key und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlungsarten

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

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

Erweitert

Debug log: protokolliert API-Anfragen und Zahlungsschritte in logs/culqi_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler, einschließlich Kartenablehnungen mit ihrem Code, werden immer protokolliert. Schlüssel, Kartendaten 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 Gateway-Einstellungen, die Culqi-Belastungs- und Erstattungsdaten des Moduls sowie das Protokoll. Der Bestellstatus und die Culqi-Daten zu Bestellungen (Zahlungen, Notizen) bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Credit/Debit Card or Yape (Culqi)) und klickt auf den Button zum Absenden der Bestellung. Das Culqi-Checkout-Popup öffnet sich auf derselben Seite mit dem Namen Ihres Shops, der Warenkorbsumme und der Währung. Dort gibt der Kunde die Kartendaten ein oder zahlt mit Yape. Die Culqi-Skripte werden nur auf der Kassenseite geladen.

Culqi wandelt die Zahlungsdaten in ein einmalig verwendbares Token um, und das Token wird an Ihren Shop gesendet. Ihr Server erstellt die Belastung über die Culqi Charges API für die Warenkorbsumme in der Warenkorbwährung, sofort erfasst. Die Belastung erscheint im CulqiPanel als Cart und Warenkorbnummer, mit der E-Mail-Adresse des Kunden. Vor diesem Punkt existiert keine Bestellung. Die Bestellung wird erst als bezahlt markiert, nachdem Culqi sie bestätigt hat: Sie wird angelegt, wenn Culqi mit einer erfolgreichen Belastung antwortet, und der Kunde sieht die übliche Bestellbestätigungsseite.

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 Prüfung 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, und der Kunde sieht The payment window was closed before the payment was completed. Er kann die Bestellung dann erneut aufgeben. Der Warenkorb bleibt in all diesen Fällen erhalten. Fehlgeschlagene Versuche werden im Modul-Protokoll vermerkt, da noch keine Bestellung existiert.

Ein Warenkorb wird nie zweimal belastet. Sendet der Kunde erneut ab, während eine Zahlung für denselben Warenkorb läuft, sieht er This order is already being paid. Please wait a moment and check your email before trying again. Hat Culqi den Betrag belastet, die Bestellung aber nicht angelegt werden können, sieht der Kunde Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Die Belastung bleibt erhalten, und der nächste Versuch legt die Bestellung aus ihr an, ohne erneute Belastung.

Das Modul akzeptiert nur einmalige Zahlungen per Karte und Yape, sofort erfasst. 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

No order yet: Die Karte wurde abgelehnt, der Kunde hat das Culqi-Fenster geschlossen oder Culqi hat nicht geantwortet. Es existiert nur der Warenkorb. Das Modul-Protokoll enthält die Details.

Payment accepted: Die Belastung wurde bestätigt und stimmt mit dem Warenkorb überein. Die Zahlung wird mit der Culqi-Belastungs-ID (chr_...) als Transaktions-ID erfasst, und eine Notiz zeigt den Modus (Test oder Live) und ob 3-D Secure verwendet wurde.

Culqi payment on hold: Culqi hat eine Belastung gemeldet, deren Betrag oder Währung nicht zum Warenkorb passt, oder eine Zahlung, die autorisiert, aber nicht erfasst wurde. Die Notiz erklärt dies und zeigt die Belastungs-ID. Eine erfasste Belastung in der Warenkorbwährung wird als Zahlung über den tatsächlich belasteten Betrag verbucht. Prüfen Sie die Belastung im CulqiPanel und liefern Sie dann die Bestellung aus oder erstatten Sie die Zahlung.

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

Trifft eine zweite Belastung für einen Warenkorb ein, der bereits eine Bestellung hat, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, die Belastung im CulqiPanel zu prüfen und bei Bedarf zu erstatten.

Culqi-Zahlungsblock

Die Bestellseite zeigt einen Block Culqi payment mit der Belastungs-ID, dem belasteten Betrag (mit 3-D Secure, falls verwendet), einem Badge Test für Testzahlungen, einem Prüfhinweis für Bestellungen in Wartestellung, den bezahlten und erstatteten Beträgen sowie dem Erstattungsverlauf.

Erstattungen

Geben Sie im Block Culqi payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Culqi. Bestätigen Sie die Frage Refund this amount through Culqi? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Module ist nicht erforderlich. Erstattungen erfolgen in dem Betrag und in der Währung, die Culqi belastet hat. Nach einer Betragsabweichung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat, nicht die Bestellsumme. Die Erstattung wird mit den Schlüsseln des Modus gesendet, in dem die Zahlung erfolgte (Test oder Live), auch wenn Sie seitdem den Modus gewechselt haben. Daher muss der geheime Schlüssel dieses Modus gesetzt sein. Lehnt Culqi die Erstattung ab, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Bestellnotizen mit der Culqi-Erstattungs-ID, dem Betrag und Ihrem Grund hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine Teilerstattung ändert den Status nicht.

Das Modul erstellt keine Gutschriften. Die üblichen Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Culqi zurück. In CulqiPanel vorgenommene Erstattungen werden nicht nach PrestaShop übertragen. Aktualisieren Sie die Bestellung bei Bedarf manuell.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Culqi Payment ist der erste Block auf Modules > Module Manager > VibeFox Culqi 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 maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz aktiv 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-culqi 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 in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert 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 Culqi Kunden an der Kasse nicht angezeigt. Versucht ein Kunde trotzdem eine Zahlung, sieht er 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 Zahlungsart auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber nicht an der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support benötigen 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. Beim Deinstallieren oder Zurücksetzen des Moduls werden der Lizenzschlüssel und der Lizenzstatus immer entfernt.

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 Warenkorbwährung PEN oder USD ist. Die Einstellungsseite zeigt eine Warnung, wenn Schlüssel fehlen. 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 wurde durchgeführt, aber es wurde keine Bestellung angelegt: Das Modul verwendet keine Webhooks. Die Belastung wird nur durch die Antwort von Culqi an Ihren Server bestätigt. Hat Culqi nicht rechtzeitig geantwortet, steht im Modul-Protokoll Culqi did not confirm the charge mit der Warenkorbnummer. Suchen Sie die Belastung mit dieser cart_id im CulqiPanel. Hat der Kunde die Meldung gesehen, dass die Bestellung nicht abgeschlossen werden konnte, legt der nächste Zahlungsversuch desselben Warenkorbs die Bestellung an, ohne erneut zu belasten.

Bestellung nach der Zahlung im Status Culqi payment on hold: Lesen Sie die Notiz in der Bestellung. Der belastete Betrag oder die Währung wich vom Warenkorb ab, oder die Zahlung wurde nicht erfasst. Prüfen Sie die Belastung im CulqiPanel (die ID steht in der Notiz) und liefern Sie dann die Bestellung aus oder erstatten Sie die Zahlung.

Der Schlüssel wird nicht gespeichert: Die Fehlermeldung besagt, dass das Feld mit einem Präfix beginnen muss, zum Beispiel sk_live_. Jedes Feld akzeptiert nur Schlüssel seines 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 Wechsel 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 Cache- oder Optimierungsmodul.

Der Kunde sieht Security check failed. Please reload the page and try again.: Die Kassenseite war zu lange oder in einer anderen Sitzung geöffnet. Ein Neuladen der Seite behebt das.

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

Eine Karte wurde abgelehnt, und Sie möchten den Grund wissen: Schauen Sie im Feld Log auf der Modulseite nach. Ablehnungen werden mit dem Culqi-Ablehnungscode protokolliert, auch wenn Debug log ausgeschaltet ist.

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

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Culqi 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 Gateway-Einstellungen, die Culqi-Belastungs- und Erstattungsdaten des Moduls sowie das Protokoll entfernt. Zuvor bezahlte Bestellungen können dann nicht mehr über die Bestellseite erstattet werden. Ist die Option ausgeschaltet, bleibt alles für eine spätere Neuinstallation erhalten. Der Bestellstatus Culqi payment on hold bleibt immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Culqi ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Culqi verbunden und wird von Culqi weder unterstützt noch empfohlen.