VibeFox Paymob 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.
Paymob-Konto: ein Händlerkonto in einem der unterstützten Länder: Ägypten, Vereinigte Arabische Emirate, Saudi-Arabien, Oman oder Pakistan. Sie benötigen vier Werte aus dem Paymob-Dashboard: den API key, die integration ID einer Online-Zahlungsintegration, die iFrame ID der Zahlungsseite und den HMAC secret.
Währung: Die Warenkorbwährung muss die Währung Ihres Paymob-Landes sein: EGP für Ägypten, AED für die Vereinigten Arabischen Emirate, SAR für Saudi-Arabien, OMR für Oman, PKR für Pakistan. Bei einer anderen Währung wird die Zahlungsmethode in der Kasse ausgeblendet. Paymob-Konten mit mehreren Währungen werden nicht unterstützt.
VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. 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 aus.
2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure oder suchen Sie VibeFox Paymob Pay 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. Wählen Sie das Paymob country und geben Sie API key, integration ID, iFrame ID und HMAC secret ein (siehe Konfiguration).
5. Stellen Sie im Paymob-Dashboard die Callback-URLs Ihrer Integration auf die URL ein, die auf der Seite Configure angezeigt wird (siehe Callbacks).
6. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung mit der ID einer Paymob-Testintegration und geben Sie danach die ID Ihrer Live-Integration ein.
Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Paymob payment und Paymob payment on hold. PrestaShop aktiviert ein neues Zahlungsmodul standardmäßig für alle Währungen, Länder und Kundengruppen. Sie können dies unter Payment > Preferences einschränken. Ein Land, das Sie später in Ihrem Shop aktivieren, muss dort ebenfalls für dieses Modul angehakt werden.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Paymob Pay > Configure. Jeder Bereich hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn einer der vier Paymob-Werte fehlt (bis dahin wird Paymob in der Kasse ausgeblendet), und wenn die Standardwährung des Shops vom gewählten Paymob-Land nicht akzeptiert wird. Ein Feld Callbacks zeigt die Callback-URL mit einer Schaltfläche Copy und einen Link zum Paymob-Dashboard des gewählten Landes.
Paymob
Enable/Disable: Enable Paymob schaltet die Zahlungsmethode ein oder aus. Standard: aus.
Title: der Name der Zahlungsmethode, den Kunden in der Kasse sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Paymob.
Description: der Text, der in der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely by card or mobile wallet on the Paymob payment page. Lassen Sie das Feld leer, wenn kein Text angezeigt werden soll.
Paymob-Konto
Alle Werte finden Sie in Ihrem Paymob-Händler-Dashboard. Es gibt keinen separaten Testmodus: Für Testzahlungen geben Sie die integration ID einer Integration im Testmodus ein. Keine andere Einstellung ändert sich.
Paymob country: das Land Ihres Paymob-Kontos. Es wählt den API- und Zahlungsseiten-Server aus, und die Warenkorbwährung muss die Währung dieses Landes sein. Standard: Egypt.
API key: im Paymob-Dashboard unter Settings > Account info > API Key.
Integration ID: im Paymob-Dashboard unter Developers > Payment Integrations: die numerische ID der Online-Integration für Karte oder Wallet. Die Zahlungsmethoden, die auf der Paymob-Seite angeboten werden, sind die dieser Integration.
iFrame ID: im Paymob-Dashboard unter Developers > iframes: die numerische ID des Zahlungs-iFrames.
HMAC secret: im Paymob-Dashboard unter Settings > Account info > HMAC. Erforderlich: Bestellungen werden nur dann als bezahlt angelegt, wenn die Callbacks mit diesem Secret signiert sind.
Integration ID und iFrame ID dürfen nur Ziffern enthalten. Leerzeichen werden entfernt. Jeder andere Wert wird beim Speichern abgelehnt, mit der Meldung, dass das Feld must contain digits only — the previous value was kept lautet. Die übrigen Felder werden gespeichert.
Der gespeicherte API key und der HMAC secret werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.
Clear saved secrets: Setzen Sie ein Häkchen bei API key oder HMAC secret und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Callbacks
Paymob meldet jede Transaktion an Ihren Shop. Öffnen Sie im Paymob-Dashboard Developers > Payment Integrations, wählen Sie Ihre Integration, klicken Sie auf Edit und setzen Sie sowohl Transaction processed callback als auch Transaction response callback auf die URL, die im Feld Callbacks angezeigt wird. Mit SEO-URLs sieht sie so aus: https://your-shop/module/wcp_paymob_pay/callback, eventuell mit einem Sprachcode wie /en/. Die URL wird in der Standardsprache des Shops erzeugt. Kopieren Sie sie mit der Schaltfläche Copy. Setzen Sie die URLs in jeder Integration, die Sie verwenden, einschließlich der Testintegration.
Der transaction processed callback wird vom Paymob-Server gesendet. Der transaction response callback bringt den Kunden zurück in Ihren Shop. Beide sind mit Ihrem HMAC secret signiert und werden vom Modul geprüft. Callbacks ohne gültige Signatur werden abgelehnt und ändern nichts. Wenn der Server-Callback verspätet oder verloren ist, bestätigt auch eine signierte Rückkehr des Kunden die Zahlung. Der Server-Callback funktioniert, während der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.
Erweitert
Debug log: schreibt die Zahlungsschritte und Callbacks in logs/paymob_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler und abgelehnte Callbacks werden immer protokolliert, auch wenn die Option aus ist. Schlüssel, Token und Kundendaten 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.
Clean uninstall: Ist die Option aktiviert, werden beim Deinstallieren des Moduls die Modul-Einstellungen und Protokolle gelöscht. Die für Bestellungen gespeicherten Paymob-IDs (Zahlungsversuche) und die Bestellstatus bleiben immer erhalten. Standard: aus.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Paymob) und bestätigt. Das Modul legt einen neuen Paymob-Auftrag über die Warenkorbsumme in der Warenkorbwährung an, übergibt Name, E-Mail-Adresse, Telefonnummer und Rechnungsadresse des Kunden an Paymob und leitet den Kunden auf die Zahlungsseite von Paymob für Ihr Land weiter. Dort bezahlt der Kunde mit einer Methode Ihrer Integration, beispielsweise mit Karte oder mobiler Geldbörse. Zu diesem Zeitpunkt existiert noch keine Bestellung.
Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Paymob die Zahlung mit einer signierten Transaktion bestätigt. Dann wird die Bestellung angelegt und der Kunde sieht die übliche Bestellbestätigungsseite. Eine ausstehende Zahlung (zum Beispiel Barzahlung oder Kiosk) oder eine autorisierte Zahlung legt die Bestellung ebenfalls an, in einem wartenden Status, und führt zur Bestellbestätigungsseite.
Wird die Bestellung zur gleichen Zeit durch den Paymob-Callback bestätigt, sieht der Kunde eine Seite mit Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. Bei einer ausstehenden Zahlung lautet der Text Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. Die Seite hat eine Schaltfläche Check again und eine Schaltfläche Back to checkout.
Wurde die Zahlung abgelehnt, kehrt der Kunde mit demselben Warenkorb zur Kasse zurück, mit der Meldung Your Paymob payment was not completed. Please try again or choose another payment method. Jeder neue Versuch legt einen eigenen Paymob-Auftrag an, sodass der Kunde den Warenkorb erneut bezahlen kann. Lässt sich die Rückmeldung von Paymob nicht prüfen, sieht der Kunde We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.
Kann Paymob die Zahlung nicht starten, bleibt der Kunde in der Kasse mit einer kurzen Meldung, zum Beispiel Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. oder Could not connect to Paymob. Please try again in a moment. Der technische Grund wird im Protokoll festgehalten.
Das Modul verarbeitet Einmalzahlungen auf der Paymob-Seite. Es gibt keine gespeicherten Karten, keine Abonnements, kein eingebettetes Kartenformular auf Ihrer Website und keine Erstattungen aus dem Back Office.
Bestellungen
Bestellstatus
No order yet: Der Kunde wurde zu Paymob geschickt und hat nicht bezahlt, die Zahlung wurde abgelehnt oder Paymob hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.
Payment accepted: Paymob hat die Zahlung bestätigt. Die Zahlung wird mit der Paymob-Transaktions-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Transaktion, den Betrag sowie den Kartentyp mit den letzten vier Ziffern.
Awaiting Paymob payment: Die Zahlung ist bei Paymob ausstehend, zum Beispiel eine Barzahlung oder eine Zahlung am Kiosk. Die Bestellung wechselt zu Payment accepted, wenn Paymob die Zahlung bestätigt.
Paymob payment on hold: Paymob hat den Betrag nur autorisiert und noch nicht eingezogen (ziehen Sie ihn im Paymob-Dashboard ein; die Bestellung wechselt zu Payment accepted, wenn der Capture-Callback eintrifft); oder der gezahlte Betrag bzw. die Währung weicht vom Warenkorb ab (zum Beispiel wurde der Warenkorb nach Beginn der Zahlung geändert); oder eine Zahlung ist für eine stornierte Bestellung eingegangen. Die Notiz nennt den Grund. Prüfen Sie die Bestellung und bearbeiten Sie sie oder erstatten Sie die Zahlung im Paymob-Dashboard.
Geht eine zweite erfolgreiche Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, das Duplikat im Paymob-Dashboard zu erstatten. Eine Zahlung für eine stornierte Bestellung, die zuvor bezahlt war, oder für eine erstattete Bestellung fügt nur eine Notiz hinzu: Die Bestellung wird nicht wieder geöffnet. Eine abgelehnte Zahlung für eine noch nicht bezahlte Bestellung fügt nur eine Notiz hinzu.
Paymob-Zahlungsblock
Die Bestellseite zeigt einen Block Paymob payment mit jedem Paymob-Versuch der Bestellung: den Paymob-Auftrag, die Händler-Bestellnummer und das Land, die Paymob-Transaktions-ID, den Status, den angeforderten Betrag, den von Paymob mit der Karte gemeldeten Betrag und die Meldung von Paymob. Darunter stehen die Notes des Moduls für diese Bestellung.
Erstattungen
Erstattungen aus dem Back Office werden nicht unterstützt. Erstatten oder stornieren Sie die Zahlung im Paymob-Dashboard. Meldet Paymob eine Erstattung oder Stornierung, wird der Bestellung eine Notiz hinzugefügt, und der Bestellstatus ändert sich nicht. Aktualisieren Sie die Bestellung manuell, zum Beispiel ihren Status oder mit einer Gutschrift.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Paymob Pay ist der erste Block auf Modules > Module Manager > VibeFox Paymob Pay > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zur erneuten Prüfung 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-paymob und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeitende 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-Konfiguration. 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 Paymob Kunden in der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde 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 vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt.
Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern aber 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. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
Paymob erscheint nicht in der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, alle vier Werte (API key, integration ID, iFrame ID, HMAC secret) ausgefüllt sind und die Warenkorbwährung die Währung des gewählten Paymob country ist. 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 erlaubt ist.
Die Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: Die Callbacks erreichen Ihren Shop nicht. Prüfen Sie, ob Transaction processed callback und Transaction response callback der verwendeten Integration genau der URL aus dem Feld Callbacks entsprechen und ob das HMAC secret zum selben Paymob-Konto gehört. Abgelehnte Callbacks werden als Warnungen im Protokoll festgehalten, auch wenn Debug log aus ist. Sehen Sie sich das Feld Log auf der Modulseite an.
Callback antwortet Invalid signature: Das HMAC secret in den Einstellungen passt nicht zum Paymob-Konto, oder es ist das Konto eines anderen Landes ausgewählt. Kopieren Sie das HMAC secret erneut.
Callback antwortet Not configured: Das HMAC secret ist leer. Geben Sie das Secret ein; Paymob wiederholt den Callback.
Callback antwortet locked oder retry: Die Bestellung wurde im selben Moment von einer anderen Anfrage aktualisiert, zum Beispiel der Rückkehr des Kunden, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). Paymob wiederholt den Callback. Der Grund wird im Protokoll festgehalten.
Das Öffnen der Callback-URL im Browser führt zur Kasse mit der Meldung could not verify: Das ist normal. Die URL akzeptiert nur signierte Anfragen von Paymob.
Der Kunde sieht einen Fehler bei der Auswahl von Paymob: Aktivieren Sie Debug log und sehen Sie im Protokoll nach. Paymob payments are temporarily unavailable bedeutet einen falschen API key oder einen fehlenden Wert. Paymob could not start the payment bedeutet, dass Paymob die Anfrage abgelehnt hat, zum Beispiel wegen einer falschen integration ID oder unvollständiger Rechnungsdaten. This order cannot be paid with Paymob bedeutet, dass die Bestellsumme null ist. Paymob does not accept payments in gefolgt von einer Währung bedeutet, dass die Warenkorbwährung nicht die Währung des gewählten Paymob-Landes ist.
Die Bestellung ist nach der Zahlung Paymob payment on hold oder Awaiting Paymob payment: Lesen Sie die Notizen im Block Paymob payment. Die Zahlung ist ausstehend (Barzahlung oder Kiosk), die Transaktion wurde nur autorisiert (ziehen Sie sie im Paymob-Dashboard ein), der Betrag oder die Währung stimmten nicht überein oder die Zahlung kam nach der Stornierung der Bestellung an.
Testzahlungen: Geben Sie die ID einer Paymob-Testintegration unter Integration ID ein und setzen Sie die Callback-URLs in dieser Integration. Für echte Zahlungen geben Sie die ID Ihrer Live-Integration erneut ein.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Paymob Pay und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Clean uninstall aktiviert, werden die Modul-Einstellungen und das Protokoll gelöscht. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Paymob-Zahlungsversuche der Bestellungen sowie die Bestellstatus Awaiting Paymob payment und Paymob payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Transaktions-IDs und Paymob-IDs.
Paymob ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Paymob verbunden und wird nicht von Paymob unterstützt.