VibeFox Hubtel for WooCommerce — Hilfe

Anforderungen

WordPress: 6.2 oder neuer.

WooCommerce: 8.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.

PHP: 8.0 oder neuer.

Währung: nur Ghana Cedi (GHS). Die Zahlungsmethode wird an der Kasse für andere Währungen ausgeblendet. Behalten Sie die Anzahl der Dezimalstellen in WooCommerce bei 2, da Hubtel in ganzen Pesewas abrechnet.

Hubtel-Konto: ein Hubtel-Geschäftskonto mit API-Schlüsseln (API ID und API Key) und der Händlerkontonummer (POS Sales ID). Die Schlüssel finden Sie im Hubtel-Business-Dashboard unter bo.hubtel.com unter Programmable keys.

IP-Whitelisting: Hubtel beantwortet Anfragen an seine Transaction Status API nur von freigeschalteten Server-IP-Adressen. Bitten Sie Hubtel (Ihren Kundenbetreuer oder support@hubtel.com), die öffentliche IP-Adresse Ihres Webservers freizuschalten. Bis dahin können Zahlungen nicht bestätigt werden und Bestellungen bleiben im Status „Zahlung ausstehend“.

Keine Testumgebung: Hubtel hat keine öffentliche Sandbox. Alle Zahlungen sind echt.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel gilt 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. Alternativ können Sie den Ordner wcp_hubtel_pay per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Hubtel > 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 API ID, den API Key und die Händlerkontonummer (POS Sales ID) ein.

6. Bitten Sie den Hubtel-Support, Ihre Server-IP für die Transaction Status API freizuschalten.

7. Aktivieren Sie Enable/Disable. Die Callback-URL wird bei jeder Zahlung an Hubtel übermittelt, sodass im Hubtel-Dashboard nichts eingerichtet werden muss.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Hubtel. Über den Feldern warnt die Seite, wenn API ID, API Key oder die Händlerkontonummer fehlen und wenn die Shopwährung nicht GHS ist. In beiden Fällen wird Hubtel an der Kasse ausgeblendet. Die Seite warnt Sie auch, wenn der Shop mehr als 2 Dezimalstellen verwendet. In der Liste der Zahlungsmethoden wird das Gateway als einrichtungsbedürftig markiert, bis die Zugangsdaten eingegeben sind.

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

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Mobile Money or card (Hubtel).

Description: der Text, der unter der Zahlungsmethode an der Kasse angezeigt wird. Standard: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Hubtel-API-Zugangsdaten

Kopieren Sie die API ID und den API Key aus Ihrem Hubtel-Business-Dashboard: bo.hubtel.com > Programmable keys. Die Händlerkontonummer ist die POS Sales ID Ihres Hubtel-Kontos. Der Abschnitt wiederholt auch den Hinweis zum IP-Whitelisting.

API ID (Client ID): die API ID Ihrer programmierbaren Schlüssel bei Hubtel.

API Key (Client Secret): der API Key Ihrer programmierbaren Schlüssel bei Hubtel. Halten Sie ihn geheim.

Merchant account number (POS Sales ID): Zahlungen werden auf dieses Hubtel-Konto eingezogen und damit abgeglichen.

Zahlungsbestätigung

Der Callback teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist. Die in diesem Abschnitt angezeigte Callback-URL wird mit jeder Zahlung an Hubtel gesendet, sodass im Hubtel-Dashboard nichts konfiguriert werden muss. Sie sieht aus wie https://your-site/wc-api/hubtel_pay/. Sie muss aus dem Internet erreichbar sein: kein Wartungsmodus, kein Passwortschutz und keine Firewall, die Hubtel blockiert.

Hubtel-Callbacks sind nicht signiert. Das Plugin übernimmt aus einem Callback nur die Zahlungsreferenz; die Referenz muss zu einer Bestellung Ihres Shops gehören. Status, Betrag und Transaktions-ID stammen immer von der Transaction Status API von Hubtel. Die Bestellung wird erst als bezahlt markiert, nachdem diese API die Zahlung und ihren Betrag bestätigt hat. Kann Hubtel nicht erreicht werden, wird die Zahlung automatisch im Hintergrund erneut geprüft, und Sie können sie auf der Bestellseite über Order actions > Check Hubtel payment status prüfen.

Erweitert

Debug log: Log API calls and callbacks nach WooCommerce > Status > Logs, Quelle wcp_hubtel_pay, ohne Schlüssel oder Kundendaten. Fehler werden immer protokolliert. Standard: aus.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Mobile Money or card (Hubtel)) und gibt die Bestellung auf. Das Plugin erstellt einen Hubtel-Checkout über den Bestellbetrag in GHS und leitet den Kunden zur Hubtel-Zahlungsseite weiter. Die Zahlung wird dort als Order #, die Bestellnummer und der Name Ihrer Website angezeigt. Auf der Hubtel-Seite zahlt der Kunde mit MTN MoMo, Telecel Cash, AirtelTigo Money, einer Visa- oder Mastercard-Karte oder GhQR. Jeder Klick auf Place order oder Pay erzeugt einen neuen Zahlungsversuch mit eigener Referenz, und ältere Hubtel-Seiten derselben Bestellung bleiben zahlbar.

Nach der Zahlung kehrt der Kunde auf die Seite „Bestellung erhalten“ zurück. Die Bestellung wird erst als bezahlt markiert, nachdem Hubtel dies über die Transaction Status API bestätigt: durch den Callback, durch die Prüfung bei Rückkehr des Kunden, durch eine Hintergrundprüfung oder durch die Bestellaktion. Ein Callback und eine Rückkehr, die im selben Moment eintreffen, werden nacheinander verarbeitet, sodass die Bestellung nie zweimal abgeschlossen wird. Hat Hubtel die Zahlung noch nicht bestätigt, zeigt die Seite We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Wurde die Bestellung in Wartestellung gesetzt, zeigt sie Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Klickt der Kunde auf der Hubtel-Seite auf Cancel, prüft das Plugin zunächst, ob die Zahlung trotzdem erfolgt ist. Wenn nicht, kehrt der Kunde mit der Meldung The Hubtel payment was cancelled. You can try again or choose another payment method. auf die Seite Pay for order zurück.

Kann Hubtel die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel Could not connect to Hubtel. Please try again in a moment., Hubtel could not start the payment. Please try again or choose another payment method. oder bei falschen Zugangsdaten Hubtel payments are not available at the moment. Please choose another payment method. Die Details werden im Protokoll erfasst.

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

Das Plugin bietet keine Erstattungen aus WooCommerce, keine Abonnements, keine gespeicherten Karten und keine Auswahl des Zahlungskanals innerhalb von WooCommerce.

Bestellungen

Bestellstatus

Pending payment: Der Kunde wurde zu Hubtel weitergeleitet und hat noch nicht bezahlt, oder Hubtel hat die Zahlung noch nicht bestätigt.

Processing: Die Zahlung wurde bestätigt. Bestellungen, die nur virtuelle herunterladbare Produkte enthalten, wechseln zu Fertiggestellt, dem Standard von WooCommerce. Die Bestellnotiz zeigt den Betrag, die Hubtel-Transaktion, die Zahlungsmethode und die Referenz. Die Transaktions-ID entspricht der Transaktions-ID von Hubtel.

On hold: Hubtel hat einen bezahlten Betrag gemeldet, der vom Bestellbetrag abweicht, oder die Bestellung lautet nicht auf GHS (Hinweis Hubtel amount/currency mismatch); oder eine Zahlung ging für eine bereits stornierte Bestellung ein. Die Bestellung wurde nicht als bezahlt markiert. Prüfen Sie die Zahlung im Hubtel-Dashboard und schließen Sie die Bestellung manuell ab oder erstatten Sie sie.

Failed: Hubtel hat gemeldet, dass der letzte Zahlungsversuch einer ausstehenden Bestellung fehlgeschlagen ist, und die Transaction Status API bestätigt, dass sie nicht bezahlt ist. Der Kunde kann es über die Bestellung erneut versuchen. Ein Fehlschlag, der nur über einen Callback gemeldet wird, setzt eine Bestellung niemals auf fehlgeschlagen.

Wird ein weiterer Versuch einer bereits bezahlten Bestellung ebenfalls bezahlt, bleibt die Bestellung unverändert. Ein Hinweis fordert Sie auf, das Duplikat in Ihrem Hubtel-Dashboard zu erstatten. Eine stornierte oder erstattete Bestellung wird niemals automatisch wiedereröffnet. Wenn Hubtel eine Zahlung als erstattet meldet, wird der Bestellung eine Notiz hinzugefügt.

Zahlungsprüfungen

Etwa 20 Minuten nachdem der Kunde zu Hubtel weitergeleitet wurde, fragt eine Hintergrundprüfung (WooCommerce Action Scheduler) bei Hubtel nach der Zahlung, falls der Callback verloren ging und der Kunde nicht zurückgekehrt ist. Ein unbezahlter Versuch wird nach einer Stunde noch einmal geprüft. Kann die Hubtel-API nicht erreicht werden, wird die Prüfung mit zunehmenden Abständen bis zu 5-mal wiederholt.

Die Bestellaktion Check Hubtel payment status prüft die neuesten Versuche der Bestellung (bis zu 5, die neueste zuerst), wendet das Ergebnis an und fügt eine Notiz mit dem Status jedes Versuchs hinzu.

Erstattungen

Erstattungen aus WooCommerce werden nicht unterstützt. Erstatten Sie die Zahlung im Hubtel-Dashboard und legen Sie anschließend eine manuelle Erstattung in WooCommerce an.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Hubtel. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, beispielsweise das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain. Verwenden Sie Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um ihn von dieser Website zu entfernen. Der Link Manage licenses and domains in your account öffnet Ihr Konto auf vibefox.net.

Ein Schlüssel gilt 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 Hubtel den Kunden an der Kasse nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin, markiert als (unlicensed — visible to admins only), sodass Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Eine Erinnerung erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt.

Läuft eine Lizenz ab, funktioniert das Plugin weiter, aber für Updates und Support ist eine Verlängerung erforderlich. Der Status wird automatisch im Hintergrund erneut überprüft.

Fehlerbehebung

Hubtel erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, API ID, API Key und die Händlerkontonummer ausgefüllt sind und die Währung GHS ist. Auf der Seite Pay for order zählt die Bestellwährung. Die Einstellungsseite zeigt eine Warnung, wenn die Zugangsdaten oder die Währung nicht stimmen.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt im Status „Zahlung ausstehend“: Die Zahlung konnte nicht bestätigt werden. Öffnen Sie WooCommerce > Status > Logs, Quelle wcp_hubtel_pay. HTTP 401 oder 403 bei der Statusprüfung bedeutet, dass die API-Schlüssel falsch sind oder die Server-IP nicht von Hubtel freigeschaltet wurde. Prüfen Sie auch, ob die Callback-URL aus dem Internet erreichbar ist. Öffnen Sie nach der Behebung die Bestellung und führen Sie Order actions > Check Hubtel payment status aus. Die Hintergrundprüfungen bestätigen die Bestellung ebenfalls, sobald Hubtel antwortet.

Der Callback antwortet mit „Unknown reference“: Die Zahlungsreferenz gehört zu keiner Bestellung dieses Shops.

Der Callback antwortet mit „Payment status unavailable“: Die Transaction Status API konnte nicht erreicht werden oder hat die Anfrage abgelehnt. Die Zahlung wird im Hintergrund erneut geprüft.

Die Bestellung ist in Wartestellung mit einem Hinweis auf Abweichung bei Betrag oder Währung: Hubtel hat einen bezahlten Betrag gemeldet, der vom Bestellbetrag abweicht, oder die Bestellung lautet nicht auf GHS. Prüfen Sie die Zahlung im Hubtel-Dashboard und schließen Sie die Bestellung manuell ab oder erstatten Sie sie.

Der Kunde sieht beim Aufgeben der Bestellung einen Fehler: Schalten Sie Debug log ein und prüfen Sie das Protokoll. Falsche API-Schlüssel führen zu Hubtel payments are not available at the moment. Ein Verbindungsproblem führt zu Could not connect to Hubtel.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Wenn der Schlüssel beispielsweise bereits auf einer anderen Domain verwendet wird, geben Sie einen Platz in Ihrem Konto auf vibefox.net 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. Kann der Lizenzserver nicht erreicht werden, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.

Für Entwickler: Der Filter hubtel_p_icon ändert das Symbol der Zahlungsmethode, und hubtel_p_payment_description ändert die Zahlungsbeschreibung auf der Hubtel-Seite (bis zu 100 Zeichen).

Deinstallation

Beim Deaktivieren des Plugins bleiben alle Daten erhalten; nur ausstehende Hintergrund-Zahlungsprüfungen werden abgebrochen. 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 Gateway-Einstellungen, die plugin-eigenen Optionen, ausstehende Hintergrundprüfungen und die Protokolle werden nur entfernt, wenn Delete data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Die bei Bestellungen gespeicherten Hubtel-Daten sind der Zahlungsverlauf und bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Hubtel ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Hubtel verbunden noch von Hubtel empfohlen.