VibeFox Hubtel for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer mit der cURL-Erweiterung. Ohne sie lässt sich das Modul nicht installieren.

Währung: nur Ghana-Cedi (GHS). Die Zahlungsart wird in der Kasse bei anderen Währungen ausgeblendet. Behalten Sie bei der Währung GHS 2 Nachkommastellen bei, da Hubtel ganze Pesewas berechnet.

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-Geschäftsdashboard unter bo.hubtel.com unter Programmable keys.

IP-Freischaltung: Hubtel beantwortet die 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 es wird keine Bestellung angelegt.

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

Cron: Empfohlen wird ein Server-Cronjob, der die Cron-URL des Moduls alle 5 Minuten aufruft, für die Hintergrundprüfungen der Zahlungen (siehe Konfiguration).

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer 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 später VibeFox Hubtel Pay Gateway in der Modulliste und klicken Sie auf Configure.

3. Geben 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. Geben Sie API ID, API Key und Händlerkontonummer (POS Sales ID) ein.

5. Bitten Sie den Hubtel-Support, die IP Ihres Servers für die Transaction Status API freizuschalten.

6. Tragen Sie die auf der Seite Configure angezeigte Cron-URL in den Cron Ihres Servers ein.

7. Schalten Sie Enable/Disable ein und klicken Sie auf Save. Die Callback-URL wird bei jeder Zahlung an Hubtel übermittelt, daher muss im Hubtel-Dashboard nichts konfiguriert werden.

Bei der Installation legt das Modul den Bestellstatus Hubtel payment on hold an. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn API ID, API Key oder Händlerkontonummer fehlen und wenn die Standardwährung des Shops nicht GHS ist. In beiden Fällen wird Hubtel in der Kasse ausgeblendet. Außerdem warnt sie, wenn die Währung GHS mehr als 2 Nachkommastellen verwendet.

Hubtel

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

Title: der Name der Zahlungsart, den der Kunde in der Kasse sieht. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Mobile Money or card (Hubtel). Pflichtfeld: Ein leerer Titel führt zur Fehlermeldung Enter a title for the payment method.

Description: der Text, der in der Kasse unter der Zahlungsart angezeigt wird. Standard: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. Sie werden zu Hubtel weitergeleitet, um die Zahlung abzuschließen.

Hubtel-API-Zugangsdaten

Kopieren Sie API ID und API Key aus Ihrem Hubtel-Geschäftsdashboard: bo.hubtel.com > Programmable keys. Die Händlerkontonummer ist die POS Sales ID Ihres Hubtel-Kontos. Der Abschnitt wiederholt außerdem den Hinweis zur IP-Freischaltung.

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

API Key (Client Secret): der API Key Ihrer programmierbaren Hubtel-Schlüssel. Halten Sie ihn geheim. Der gespeicherte Schlüssel wird 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.

Merchant account number (POS Sales ID): Zahlungen werden auf dieses Hubtel-Konto eingezogen und dagegen geprüft.

Clear saved API Key: Setzen Sie den Haken und klicken Sie auf Save, um den gespeicherten API Key zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlungsbestätigung

Callback URL: Der Callback teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist. Diese URL wird bei jeder Zahlung an Hubtel übermittelt, daher muss im Hubtel-Dashboard nichts konfiguriert werden. Mit SEO-freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_hubtel_pay/callback, gegebenenfalls mit einem Sprachcode. Sie muss aus dem Internet erreichbar sein: kein Passwortschutz und keine Firewall, die Hubtel blockiert. Der Callback funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Hubtel-Callbacks sind nicht signiert. Das Modul übernimmt aus einem Callback nur die Zahlungsreferenz; die Referenz muss zu einer Zahlung Ihres Shops gehören. Status, Betrag und Transaktions-ID stammen immer aus der Hubtel Transaction Status API. Die Bestellung wird erst als bezahlt angelegt, nachdem diese API die Zahlung und ihren Betrag bestätigt hat.

Hintergrundprüfungen der Zahlungen (Cron): die Cron-URL mit einem geheimen Token. Rufen Sie sie alle 5 Minuten über den Cron Ihres Servers auf, zum Beispiel mit curl. Zahlungen ohne Bestätigung werden dann automatisch erneut bei Hubtel geprüft: 20 Minuten nachdem der Kunde zu Hubtel geschickt wurde, noch einmal nach einer Stunde, falls die Zahlung noch offen ist, und bis zu 5-mal mit wachsenden Abständen, wenn Hubtel nicht erreicht werden konnte. Halten Sie die URL geheim.

Erweitert

Debug log: protokolliert API-Aufrufe und Callbacks in logs/hubtel_p_debug.log.php im Modulordner. Die Datei ist aus dem Web nicht aufrufbar. Schlüssel und Kundendaten werden nicht protokolliert. Fehler und Warnungen werden immer protokolliert, auch wenn diese Option aus ist. Standard: aus.

Log: zeigt die aktuelle 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 eingeschaltet, entfernt die Deinstallation des Moduls dessen Einstellungen und Protokoll. Die für Bestellungen gespeicherten Hubtel-Daten und der Bestellstatus Hubtel payment on hold bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Mobile Money or card (Hubtel)) und bestätigt. Das Modul erstellt einen Hubtel-Checkout für den Warenkorbbetrag in GHS und leitet den Kunden auf die Hubtel-Zahlungsseite weiter. Die Zahlung erscheint dort als Cart #, mit der Warenkorbnummer und dem Namen Ihres Shops. Auf der Hubtel-Seite zahlt der Kunde mit MTN MoMo, Telecel Cash, AirtelTigo Money, einer Visa- oder Mastercard-Karte oder GhQR. Zu diesem Zeitpunkt existiert noch keine Bestellung. Jede Bestätigung im Zahlungsschritt erstellt einen neuen Zahlungsversuch mit eigener Referenz, und ältere Hubtel-Seiten desselben Warenkorbs bleiben zahlbar.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Hubtel sie über die Transaction Status API bestätigt: durch den Callback, durch die Prüfung bei der Rückkehr des Kunden, durch eine Hintergrundprüfung oder über die Schaltfläche auf der Bestellseite. Ein Callback und eine Rückkehr, die im selben Moment eintreffen, werden nacheinander verarbeitet, sodass die Bestellung nie doppelt angelegt wird. Der Kunde sieht danach die übliche Bestellbestätigungsseite. Wurde die Bestellung in Wartestellung gesetzt, zeigt die Seite Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Wenn Hubtel die Zahlung bei der Rückkehr des Kunden noch nicht bestätigt hat, zeigt eine Seite Payment confirmation die Meldung 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. mit den Schaltflächen Check again und Back to checkout. Die Bestellung wird angelegt, sobald Hubtel die Zahlung bestätigt. Hat Hubtel diesen Zahlungsversuch bereits als fehlgeschlagen gemeldet, kehrt der Kunde mit The Hubtel payment was not completed. You can try again or choose another payment method. zur Kasse zurück. Der Warenkorb bleibt erhalten.

Drückt der Kunde auf der Hubtel-Seite auf Cancel, prüft das Modul zuerst, ob die Zahlung trotzdem erfolgt ist. Falls nicht, kehrt der Kunde mit The Hubtel payment was cancelled. You can try again or choose another payment method. zur Kasse zurück. Der Warenkorb bleibt erhalten. Eine spätere Zahlung über die abgebrochene Hubtel-Seite wird weiterhin akzeptiert.

Kann Hubtel die Zahlung nicht starten, bleibt der Kunde in der Kasse mit einer kurzen 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 gehen ins Protokoll.

Das Modul unterstützt keine Erstattungen aus PrestaShop, keine Abonnements, keine gespeicherten Karten und keine Auswahl des Zahlungskanals innerhalb des Shops.

Bestellungen

Bestellstatus

No order yet: Der Kunde wurde zu Hubtel geschickt und hat nicht bezahlt, oder Hubtel hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted: Die Zahlung wurde für den genauen Warenkorbbetrag in GHS bestätigt. Sie wird mit der Hubtel-Transaktions-ID erfasst, und eine Notiz zeigt Betrag, Hubtel-Transaktion, Zahlungsart und Referenz.

Hubtel payment on hold: Hubtel hat einen bezahlten Betrag gemeldet, der vom Warenkorbbetrag abweicht, oder der Warenkorb ist nicht in GHS. Die Bestellung wurde nicht als bezahlt markiert; der tatsächlich von Hubtel eingezogene Betrag wird als Zahlung erfasst, und eine Notiz erklärt die Abweichung. Prüfen Sie die Zahlung im Hubtel-Dashboard und bearbeiten Sie die Bestellung oder erstatten Sie sie manuell. Wird ein späterer Versuch desselben Warenkorbs mit dem richtigen Betrag bezahlt, wechselt die Bestellung zu Payment accepted.

Wird ein Versuch einer bereits bezahlten Bestellung ebenfalls bezahlt, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, das Duplikat in Ihrem Hubtel-Dashboard zu erstatten. Eine Zahlung zu einer stornierten oder erstatteten Bestellung fügt eine Notiz hinzu, und die Bestellung wird nie automatisch wieder geöffnet. Meldet Hubtel eine Zahlung als erstattet, wird der Bestellung eine Notiz hinzugefügt.

Hubtel-Zahlungsblock

Die Bestellseite zeigt einen Block Hubtel payment mit allen Zahlungsversuchen des Bestellwarenkorbs: Datum, Referenz, Hubtel-Zahlungsseite, Betrag, Hubtel-Status, Transaktion und Ergebnis. Darunter stehen die Hubtel notes der Bestellung, die neuesten zuerst.

Die Schaltfläche Check Hubtel payment status prüft die neuesten Versuche der Bestellung (bis zu 5, die neuesten zuerst, und hält an, sobald die Bestellung bezahlt ist), wendet das Ergebnis an und fügt eine Notiz mit dem Status jedes Versuchs hinzu. Das Ergebnis wird im Block angezeigt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Module-Seiten ist nicht nötig. Die Schaltfläche ist verfügbar, sobald die Bestellung existiert. Ein bezahlter Warenkorb ohne Bestellung wird durch den Callback, die Rückkehr des Kunden oder den Cron bestätigt.

Erstattungen

Erstattungen aus PrestaShop werden nicht unterstützt. Erstatten Sie die Zahlung im Hubtel-Dashboard und erfassen Sie die Erstattung anschließend in PrestaShop. Die üblichen Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Hubtel zurück.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Hubtel Pay Gateway ist der erste Block auf Modules > Module Manager > VibeFox Hubtel Pay Gateway > 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 gültig 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-hubtel 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 Shop-Adresse oder nachdem Sie in Ihrem Konto einen Domain-Platz 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 auf einer Domain: der 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 Hubtel den Kunden in der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Die 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, es an der Kasse aber nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden auch durch die Hintergrundprüfungen weiterhin bestätigt.

Wenn eine Lizenz abläuft, 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 der Eingabe des Schlüssels, danach einmal pro Woche. Für die Lizenzprüfung ist kein Cronjob nötig. Beim Deinstallieren oder Zurücksetzen des Moduls werden immer der Lizenzschlüssel und der Lizenzstatus entfernt.

Fehlerbehebung

Hubtel erscheint nicht in der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, API ID, API Key und Händlerkontonummer ausgefüllt sind und die Warenkorbwährung GHS ist. Prüfen Sie unter Payment > Preferences, ob das Modul für GHS, das Land des Kunden und die Kundengruppe erlaubt ist. Die Einstellungsseite zeigt eine Warnung, wenn die Zugangsdaten oder die Währung falsch sind.

Die Zahlung ist erfolgt, aber es wurde keine Bestellung angelegt: Die Zahlung konnte nicht bestätigt werden. Schalten Sie Debug log ein und prüfen Sie das Feld Log auf der Modulseite. HTTP 401 oder 403 bei der Statusprüfung bedeutet, dass die API-Schlüssel falsch sind oder die Server-IP nicht von Hubtel freigeschaltet ist. Prüfen Sie außerdem, ob die Callback-URL aus dem Internet erreichbar ist und die Cron-URL aufgerufen wird. Sobald Hubtel antwortet, legt der nächste Callback, die nächste Hintergrundprüfung oder die nächste Rückkehr des Kunden die Bestellung an.

Der Callback antwortet Unknown reference: Die Zahlungsreferenz gehört zu keiner Zahlung dieses Shops.

Der Callback antwortet Payment status unavailable: Die Transaction Status API war nicht erreichbar oder hat die Anfrage abgelehnt, oder der Warenkorb wurde im selben Moment von einer anderen Anfrage bestätigt. Die Zahlung wird nach 5 Minuten im Hintergrund erneut geprüft.

Der Callback antwortet Gateway not configured: API ID, API Key oder Händlerkontonummer fehlen. Ergänzen Sie sie; die Zahlung wird im Hintergrund erneut geprüft.

Der Callback antwortet Invalid request oder Invalid ClientReference: Die Anfrage enthielt keinen gültigen Hubtel-Callback.

Die Callback-URL zeigt im Browser Method not allowed: Das ist normal. Die URL akzeptiert nur Anfragen von Hubtel.

Die Cron-URL antwortet Forbidden: Das Token in der URL ist falsch. Kopieren Sie die Cron-URL genau so, wie sie in den Einstellungen angezeigt wird.

Bestellung ist Hubtel payment on hold: Lesen Sie die Notizen im Block Hubtel payment (siehe Bestellstatus), prüfen Sie die Zahlung im Hubtel-Dashboard und bearbeiten Sie die Bestellung oder erstatten Sie sie manuell.

Der Kunde sieht einen Fehler bei der Auswahl von Hubtel: 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. Ein Warenkorb in einer anderen Währung führt zu Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method.

Für Entwickler: Der Hook actionWcpHubtelPayIcon ändert das Symbol der Zahlungsart, und actionWcpHubtelPayPaymentDescription ändert die Zahlungsbeschreibung auf der Hubtel-Seite (bis zu 100 Zeichen).

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Hubtel Pay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall eingeschaltet, werden die Einstellungen und das Protokoll dieses Moduls entfernt. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die für Bestellungen gespeicherten Hubtel-Daten und der Bestellstatus Hubtel payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Hubtel ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Hubtel verbunden noch wird es von Hubtel unterstützt.