VibeFox Khipu for WooCommerce — Hilfe

Voraussetzungen

WordPress: 6.0 oder höher.

WooCommerce: 8.0 oder höher, installiert und aktiv. Ohne WooCommerce verweigert das Plugin die Aktivierung.

PHP: 8.0 oder höher.

Shop-Währung: Chilenischer Peso (CLP), Argentinischer Peso (ARS) oder Peruanischer Sol (PEN). Die Zahlungsart wird an der Kasse ausgeblendet, wenn der Shop oder die Bestellung auf der Seite Pay for order eine andere Währung verwendet.

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

Erreichbare Website: Khipu bestätigt Zahlungen, indem es Ihren Shop aufruft. Die Website muss daher aus dem Internet erreichbar sein (kein Wartungsmodus, keine Basic Authentication und keine Firewall, die Khipu blockiert).

VibeFox-Lizenzschlüssel: gekauft auf vibefox.net. Ein Schlüssel funktioniert für eine 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_khipu_gateway auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Khipu > 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. Geben Sie die Receiver ID, den API key und den Secret key Ihres Khipu-Sammelkontos ein (siehe Konfiguration).

6. Schalten Sie Enable / Disable ein und speichern Sie. Um zunächst zu testen, verwenden Sie die Schlüssel eines Khipu-Entwicklerkontos und ersetzen Sie sie anschließend durch die Schlüssel Ihres Produktivkontos.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Khipu. Oberhalb der Felder warnt Sie die Seite, wenn die Receiver ID, der API Key oder der Secret Key fehlt (Khipu wird dann an der Kasse nicht angeboten) und wenn die Shop-Währung nicht unterstützt wird. In der Liste der Zahlungsarten ist Khipu als einrichtungsbedürftig markiert, bis alle drei Schlüssel eingegeben sind.

Allgemein

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

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: Khipu.

Description: der Text, der an der Kasse unter der Zahlungsart 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 Plugin hat keinen Schalter für einen Testmodus. Verwenden Sie zum Testen die Schlüssel eines Entwickler-Sammelkontos („desarrollo“): Es wird über die Testbank DemoBank bezahlt, und es wird kein echtes Geld bewegt. Wenn Sie live gehen, wechseln Sie zu den Schlüsseln Ihres Produktiv-Sammelkontos.

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

API key: wird verwendet, um Zahlungen zu erstellen und jede Zahlung bei Khipu zu prüfen.

Secret key: wird verwendet, um die Signatur (HMAC-SHA256) der Khipu-Zahlungsbenachrichtigungen zu prüfen. Ohne ihn kann keine Zahlung bestätigt werden.

Zahlungsbenachrichtigungen

Khipu bestätigt Zahlungen, indem es die in diesem Abschnitt der Einstellungen angezeigte Benachrichtigungs-URL aufruft. Sie sieht aus wie https://your-site/wc-api/webhook_wc_khipu/. Die URL wird bei jeder Zahlung automatisch mitgesendet, in Ihrem Khipu-Konto ist also nichts zu konfigurieren, aber die URL muss aus dem Internet erreichbar sein.

Jede Benachrichtigung muss eine gültige Signatur tragen, die mit Ihrem Secret key erstellt wurde. Benachrichtigungen ohne gültige Signatur werden abgelehnt. Danach fragt das Plugin den Zahlungsstatus bei Khipu ab und handelt nach der Meldung von Khipu:

done: Die Überweisung wurde bestätigt. Die Bestellung wird als bezahlt markiert, nachdem Receiver ID, Bestellung und Betrag geprüft wurden.

done, reversed: Die Zahlung wurde rückgängig gemacht. Eine unbezahlte Bestellung wird nicht als bezahlt markiert. Eine bezahlte Bestellung erhält eine Notiz, ihr Status wird nicht geändert.

pending or verifying: Die Überweisung ist noch nicht abgeschlossen. Das Plugin antwortet mit „retry later“, und Khipu sendet die Benachrichtigung erneut.

Status after payment: der Bestellstatus, sobald Khipu die Zahlung bestätigt. Der Status wird sofort gesetzt, mit einer Statusänderung und einem Satz E-Mails.

Processing: WooCommerce entscheidet (Standard). Virtuelle Bestellungen mit Downloads werden automatisch abgeschlossen.

Completed: Jede bezahlte Bestellung erhält den Status Abgeschlossen.

Erweitert

Debug log: Log API calls and notifications in WooCommerce > Status > Logs, Quelle wcp_khipu_gateway. Fehler werden immer protokolliert. Schlüssel und Zahlerdaten werden nie geschrieben. Standard: aus.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Bestelldaten (Khipu-Zahlungs-IDs in Bestellungen) werden immer behalten. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Khipu) und gibt die Bestellung auf. Das Plugin erstellt eine Khipu-Zahlung über den Bestellbetrag in der Bestellwährung, mit der Bestellnummer, dem Shop-Namen und den bestellten Artikeln, und leitet den Kunden auf die Khipu-Zahlungsseite weiter. Die Rechnungs-E-Mail wird an Khipu übergeben, wenn sie gültig ist. Auf der Khipu-Seite bezahlt der Kunde per Banküberweisung von seiner eigenen Bank und wählt dort zwischen den Überweisungsarten, die Khipu anbietet.

Nach der Zahlung kehrt der Kunde zur Bestellbestätigungsseite Ihres Shops zurück. Die Bestellung wird erst als bezahlt markiert, nachdem Khipu die Überweisung bestätigt hat: durch die signierte Benachrichtigung oder durch eine Statusabfrage bei Khipu, wenn der Kunde die Bestellbestätigungsseite öffnet. Die Rückkehr allein markiert eine Bestellung nie als bezahlt. Solange die Überweisung nicht bestätigt ist, zeigt die Seite Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.

Verlässt der Kunde die Khipu-Seite, ohne zu bezahlen, landet er auf der Seite Pay for order mit der Meldung The Khipu payment was not completed. You can try again or choose another payment method. 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 abgeschlossen 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.

Bei aktivierter Bestandsverwaltung verfällt die Khipu-Zahlung zusammen mit der WooCommerce-Zeit Hold stock (minutes), sodass der Kunde eine bereits stornierte Bestellung nicht bezahlen kann.

Kann Khipu die Zahlung nicht erstellen, sieht der Kunde eine kurze 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 ins Log geschrieben.

Die Zahlungsart funktioniert an der klassischen Kasse, im Checkout-Block und auf der Seite Pay for order. Sie ist mit dem WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin verarbeitet nur einmalige Banküberweisungen. Erstattungen aus WooCommerce werden nicht unterstützt, und es gibt keine Abonnements, gespeicherten Zahlungsarten oder Vorautorisierungen.

Bestellungen

Bestellstatus

Pending payment: Der Kunde wurde zu Khipu weitergeleitet und hat noch nicht bezahlt, oder Khipu hat die Überweisung noch nicht bestätigt. Die Bestellnotiz zeigt die Khipu-Zahlungs-ID.

Processing or Completed: Khipu hat die Zahlung bestätigt. Der Status richtet sich nach Status after payment. Die Bestellnotiz zeigt die Khipu-Zahlungs-ID, und die Transaktions-ID ist die Khipu-Zahlungs-ID.

On hold: Khipu hat eine Zahlung gemeldet, deren Betrag oder Währung nicht zur Bestellung passt, oder die Zahlung ist eingegangen, nachdem die Bestellung storniert wurde (zum Beispiel nach Ablauf der Wartezeit für die Bestandsreservierung). Die Bestellnotiz erläutert dies. Prüfen Sie die Zahlung in Ihrem Khipu-Konto und schließen Sie die Bestellung ab oder erstatten Sie dem Kunden den Betrag.

Geht eine Zahlung für eine Bestellung ein, die bereits bezahlt oder nach der Zahlung geschlossen wurde, wird die Bestellung nicht geändert. Eine Notiz bittet Sie, den Betrag an den Kunden zu erstatten, wenn es sich um eine zweite Zahlung handelt.

Erstattungen

Erstattungen werden nicht aus WooCommerce an Khipu gesendet. Erstatten Sie den Kunden aus Ihrem Khipu-Konto oder per Banküberweisung und erfassen Sie die Erstattung anschließend manuell in WooCommerce.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben in WooCommerce > Settings > Payments > Khipu. 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 für eine Domain. Das Entfernen des Schlüssels von einer Website gibt den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Khipu 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, markiert 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: Bereits gestartete Zahlungen werden weiterhin bestätigt.

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

Fehlerbehebung

Khipu erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und die Receiver ID, der API key und der Secret key alle eingegeben sind. Die Shop-Währung muss CLP, ARS oder PEN sein. Die Einstellungsseite zeigt eine Warnung, wenn etwas fehlt.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt auf „Zahlung ausstehend“: Khipu bestätigt eine Überweisung erst, nachdem die Bank sie geprüft hat. Die Bestellung wird aktualisiert, wenn die Khipu-Benachrichtigung eintrifft oder wenn der Kunde die Bestellbestätigungsseite öffnet. Prüfen Sie, ob Ihre Website unter der in den Einstellungen angezeigten Benachrichtigungs-URL aus dem Internet erreichbar ist (kein Wartungsmodus, keine Basic Authentication und keine Firewall, die Khipu blockiert), und sehen Sie unter WooCommerce > Status > Logs, Quelle wcp_khipu_gateway, nach.

Benachrichtigung antwortet mit Secret key not configured: Der Secret key ist leer. Geben Sie ihn ein. Khipu sendet die Benachrichtigung erneut.

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

Benachrichtigung antwortet mit Payment does not belong to this order: Die Zahlung wurde an eine andere Receiver ID oder für eine andere Bestellung geleistet. Prüfen Sie die Receiver ID.

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

Die Bestellung steht auf „In Wartestellung“: Lesen Sie die Bestellnotiz. Der Betrag oder die Währung passte nicht zur Bestellung, oder die Zahlung ist eingegangen, nachdem die Bestellung storniert wurde.

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.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Wenn der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet wird, geben Sie einen Platz in Ihrem vibefox.net-Konto frei und klicken Sie auf Check now. Wenn sich die Website-Adresse geändert hat, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Wenn der Lizenzserver nicht erreichbar ist, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.

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

Deinstallation

Beim Deaktivieren des Plugins bleiben alle Daten erhalten. Um es zu entfernen, deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Die Einstellungen des Gateways und die Logs 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.

Khipu ist eine Marke des jeweiligen Inhabers. Dieses Plugin ist mit Khipu weder verbunden noch von Khipu empfohlen.