VibeFox Khipu for PrestaShop — Hilfe

Voraussetzungen

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), Argentinischer Peso (ARS) oder Peruanischer Sol (PEN). Bei Warenkörben in anderen Währungen wird die Zahlungsmethode an der Kasse ausgeblendet.

Khipu-Konto: Sie benötigen die Receiver ID („Id de cobrador“), den API Key und den Secret Key Ihres Khipu-Sammelkontos. Sie finden sie in Ihrem Khipu-Konto unter dem Händlerprofil (khipu.com/merchant/profile). Alle drei sind erforderlich: Ohne den Secret Key kann keine Zahlung bestätigt werden. Im Khipu-Konto muss nichts konfiguriert werden.

Erreichbarer Shop: Khipu bestätigt Zahlungen, indem es Ihren Shop aufruft. Daher muss die Benachrichtigungs-URL aus dem Internet erreichbar sein, ohne Passwortschutz oder Firewall, die Khipu blockiert. Der Wartungsmodus des Shops blockiert sie nicht.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. 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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie VibeFox Khipu Gateway später in der Modulliste und klicken Sie auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel im Feld License key des Lizenzblocks oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie die Receiver ID, den API key und den Secret key Ihres Khipu-Sammelkontos ein (siehe Konfiguration).

5. Aktivieren Sie Enable / Disable und klicken Sie auf Save. Zum Testen verwenden Sie zunächst die Schlüssel eines Khipu-Entwicklerkontos und ersetzen Sie sie danach durch die Schlüssel Ihres Produktivkontos.

Bei der Installation legt das Modul den Bestellstatus Khipu payment on hold an. PrestaShop aktiviert das neue Zahlungsmodul standardmäßig für alle Währungen, Länder und Kundengruppen. Sie können dies unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Khipu Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Über den Feldern warnt die Seite, wenn Receiver ID, API key oder Secret key fehlt (Khipu wird dann an der Kasse nicht angeboten), und wenn die Standardwährung des Shops von Khipu nicht unterstützt wird.

Khipu

Enable / Disable: Enable Khipu payments schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Khipu. Erforderlich.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay by bank transfer with Khipu.

Khipu-Konto

Kopieren Sie die Receiver ID, den API key und den Secret key aus Ihrem Khipu-Sammelkonto (khipu.com/merchant/profile). Khipu hat keinen separaten Sandbox-Server, und das Modul hat keinen Testmodus-Schalter. Zum Testen verwenden Sie die Schlüssel eines Entwickler-Sammelkontos („desarrollo“): Es bezahlt über die Testbank DemoBank, und es wird kein echtes Geld bewegt. Wechseln Sie zu den Schlüsseln Ihres Produktiv-Sammelkontos, wenn Sie live gehen.

Receiver ID: Ihre Khipu-Receiver-ID („cobrador“). Zahlungen anderer Khipu-Konten werden abgelehnt.

API key: wird zum Anlegen von Zahlungen und zur Prüfung jeder Zahlung bei Khipu verwendet.

Secret key: wird zur Prüfung der Signatur (HMAC-SHA256) von Khipu-Zahlungsbenachrichtigungen verwendet. Ohne ihn kann keine Zahlung bestätigt werden.

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

Clear saved secrets: Aktivieren Sie das Kontrollkästchen bei API key oder Secret key und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlungsbenachrichtigungen

Notification URL: Khipu bestätigt Zahlungen, indem es die hier angezeigte URL aufruft. Mit aktivierten „Freundlichen URLs“ sieht sie so aus: https://your-shop/module/wcp_khipu_gateway/webhook, eventuell mit einem Sprachcode. Die URL wird bei jeder Zahlung automatisch übermittelt, daher müssen Sie in Ihrem Khipu-Konto nichts einrichten. Die URL muss jedoch aus dem Internet erreichbar sein.

Jede Benachrichtigung muss eine gültige Signatur haben, die mit Ihrem Secret key erstellt wurde. Benachrichtigungen ohne gültige Signatur werden abgelehnt. Das Modul vertraut dem Inhalt der Benachrichtigung nie: Es fragt den Zahlungsstatus bei Khipu ab und handelt auf Grundlage dessen, was Khipu meldet:

done: die Überweisung wurde bestätigt. Die Bestellung wird nach den Prüfungen von Receiver ID, Warenkorb und Betrag angelegt.

done, reversed: die Zahlung wurde rückgängig gemacht. Für einen unbezahlten Warenkorb wird keine Bestellung angelegt. Eine bezahlte Bestellung erhält eine Notiz, ihr Status wird nicht geändert.

pending or verifying: die Überweisung ist noch nicht endgültig. Das Modul antwortet „retry later“, und Khipu sendet die Benachrichtigung erneut.

Status after payment: der Bestellstatus, sobald Khipu die Zahlung bestätigt. Der Status wird sofort mit einer einzigen Statusänderung gesetzt.

Processing: die Bestellung erhält Payment accepted (Standard).

Completed: die Bestellung erhält Delivered.

Erweitert

Debug log: protokolliert API-Aufrufe und Benachrichtigungen in logs/wc_khp_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler werden immer protokolliert, auch wenn der Schalter aus ist. Schlüssel und Zahlerdaten werden nie geschrieben. 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: ist die Option aktiviert, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und das Protokoll. Bestelldaten (Khipu-Zahlungs-IDs der Bestellungen) bleiben immer erhalten. Standard: aus.

Kasse

An der Kasse wählt der Kunde die Zahlungsmethode (standardmäßig Khipu) mit ihrer Beschreibung und bestätigt die Bestellung. Das Modul legt eine Khipu-Zahlung für den Warenkorbbetrag in der Warenkorbwährung an und leitet den Kunden zur Khipu-Zahlungsseite weiter. Bei Khipu erscheint die Zahlung als Order # mit der Warenkorbnummer und dem Shopnamen, zusammen mit der Produktliste. Die E-Mail-Adresse des Kunden wird an Khipu übergeben, sofern sie gültig ist. Auf der Khipu-Seite bezahlt der Kunde per Banküberweisung von seiner eigenen Bank. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach der Zahlung kehrt der Kunde zu Ihrem Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Khipu sie bestätigt hat: durch die signierte Benachrichtigung oder durch eine Statusabfrage bei Khipu, wenn der Kunde zurückkehrt. Die Rückkehr selbst markiert nie etwas als bezahlt. Sobald die Bestellung angelegt ist, sieht der Kunde die übliche Bestellbestätigungsseite. Wenn die Bank die Überweisung noch prüft oder Khipu nicht erreichbar ist, zeigt eine Seite Payment confirmation den Text Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. mit den Schaltflächen Check again und Back to checkout. Lässt sich die letzte Khipu-Zahlung des Warenkorbs keiner Bestellung zuordnen (zum Beispiel, weil sie zu einer anderen Receiver ID gehört), kehrt der Kunde zur Kasse zurück, mit der Meldung We could not match this payment to an order. If you paid, please contact us.

Verlässt der Kunde die Khipu-Seite ohne zu zahlen oder wurde die Zahlung nicht abgeschlossen, kehrt er zur Kasse zurück, mit der Meldung The Khipu payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten. Ein neuer Versuch löscht die vorherige unbezahlte Khipu-Zahlung, sodass der alte Link nicht mehr bezahlt werden kann. Hat Khipu die vorherige Zahlung bereits erhalten, wird die Bestellung angelegt und keine neue Zahlung erstellt. Wird die vorherige Überweisung noch geprüft, sieht der Kunde Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.

Kann Khipu die Zahlung nicht anlegen, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. oder Khipu is temporarily unavailable. Please try again in a few minutes. Die Details werden im Protokoll festgehalten.

Die Benachrichtigung funktioniert, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Das Modul unterstützt nur einmalige Banküberweisungszahlungen. Erstattungen werden von PrestaShop aus nicht an Khipu gesendet, und es gibt keine Abonnements, gespeicherten Zahlungsmethoden oder Vorautorisierungen. Unbezahlte Zahlungen sind nicht mit einer Bestandsreservierung verknüpft.

Bestellungen

Bestellstatus

No order yet: der Kunde wurde zu Khipu weitergeleitet und hat nicht bezahlt, oder Khipu hat die Überweisung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted or Delivered: Khipu hat die Zahlung bestätigt. Der Status richtet sich nach Status after payment. Die Zahlung wird mit der Khipu-Zahlungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt Khipu payment verified. Payment ID: mit der Zahlungs-ID und dem Betrag.

Khipu payment on hold: Khipu hat eine Zahlung bestätigt, deren Betrag oder Währung nicht zur Bestellung passt (zum Beispiel wurde der Warenkorb geändert, nachdem die Zahlung begonnen hatte), oder die Zahlung ist eingegangen, nachdem die Bestellung storniert worden war. Der tatsächlich erhaltene Betrag wird an der Bestellung erfasst (nicht, wenn die Währung abweicht), und eine Notiz erklärt es. Prüfen Sie die Zahlung in Ihrem Khipu-Konto und schließen Sie dann die Bestellung ab oder erstatten Sie dem Kunden den Betrag. Geht für denselben Warenkorb später eine Zahlung mit dem richtigen Betrag ein, wechselt die Bestellung in den Status für bezahlte Bestellungen.

Geht eine Zahlung für eine Bestellung ein, die bereits bezahlt oder nach der Zahlung geschlossen wurde, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, die Zahlung dem Kunden zu erstatten, wenn es sich um eine zweite Zahlung handelt. Meldet Khipu eine bezahlte Zahlung als rückgängig gemacht, erhält die Bestellung eine Notiz, und ihr Status wird nicht geändert.

Khipu-Zahlungsblock

Die Bestellseite zeigt einen Block Khipu payment mit den Khipu-Zahlungsversuchen des Bestellwarenkorbs (Datum, Betrag, Khipu-Zahlungs-ID, Khipu-Status und Ergebnis), eine Warnung Manual review, solange die Bestellung Khipu payment on hold ist, und die Khipu notes der Bestellung. Der Block ist nur lesbar.

Erstattungen

Erstattungen werden von PrestaShop aus nicht an Khipu gesendet, da Khipu über seine API keine Erstattung anbietet. Erstatten Sie dem Kunden den Betrag über Ihr Khipu-Konto oder per Banküberweisung und erfassen Sie die Erstattung danach manuell in PrestaShop.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Khipu Gateway ist der erste Block unter Modules > Module Manager > VibeFox Khipu Gateway > Configure, oberhalb der Einstellungen. Geben 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 gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-khipu 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 einen Domainplatz 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 für eine Domain: der Domain des Hauptshops, auch bei einer Multistore-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne einen aktiven Schlüssel wird Khipu Kunden an der Kasse nicht angezeigt. Versucht ein Kunde dennoch 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 Zahlungsmethode 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 Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird während der Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cronjob ist nicht nötig. Beim Deinstallieren oder Zurücksetzen des Moduls werden Lizenzschlüssel und Lizenzstatus immer entfernt.

Fehlerbehebung

Khipu erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und Receiver ID, API key und Secret key alle eingetragen sind. Die Warenkorbwährung muss CLP, ARS oder PEN sein. Die Einstellungsseite zeigt eine Warnung, wenn etwas fehlt. 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: Khipu bestätigt eine Überweisung, nachdem die Bank sie geprüft hat. Die Bestellung wird angelegt, wenn die Khipu-Benachrichtigung eingeht oder wenn der Kunde auf Check again klickt. Prüfen Sie, ob Ihr Shop unter der in Notification URL angezeigten URL aus dem Internet erreichbar ist (kein Passwortschutz und keine Firewall, die Khipu blockiert), und sehen Sie im Feld Log der Modulseite nach.

Die Benachrichtigung meldet Secret key not configured: Der Secret key ist leer. Tragen Sie ihn ein. Khipu sendet die Benachrichtigung erneut.

Die Benachrichtigung meldet Invalid signature, Missing signature or Malformed signature: Der Secret key gehört nicht zu dem Sammelkonto, dessen Schlüssel Sie verwenden, oder die Anfrage stammt nicht von Khipu.

Die Benachrichtigung meldet Order not found or Payment does not belong to this order: Die Zahlung ging an eine andere Receiver ID oder galt einem anderen Warenkorb. Prüfen Sie die Receiver ID.

Die Benachrichtigung meldet Payment not final yet or Verification unavailable: Die Überweisung wird noch geprüft, oder Khipu war nicht erreichbar. Khipu sendet die Benachrichtigung erneut.

Die Benachrichtigung meldet Busy, retry later or Order could not be created, retry later: Die Bestellung wurde im selben Moment von einer anderen Anfrage bestätigt, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Khipu sendet die Benachrichtigung erneut. Der Grund steht im Protokoll.

Bestellung ist Khipu payment on hold: Lesen Sie die Notizen im Block Khipu payment. Betrag oder Währung passten nicht zur Bestellung, oder die Zahlung ging ein, nachdem die Bestellung storniert worden war.

Der Kunde sieht „Khipu payments are not available right now“: Der API key fehlt oder ist falsch. Prüfen Sie die Schlüssel in Ihrem Khipu-Konto.

Wenn Ihr Khipu-Konto eine andere Währung akzeptiert, zum Beispiel EUR für Khipu Spanien, können Entwickler sie mit dem Hook actionWcpKhipuSupportedCurrencies hinzufügen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Khipu 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 Gateway-Einstellungen und das Protokoll entfernt. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Khipu-Zahlungsversuche und der Bestellstatus Khipu payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Khipu ist eine Marke ihres jeweiligen Inhabers. Dieses Modul steht in keiner Verbindung zu Khipu und wird nicht von Khipu unterstützt.