VibeFox PayMongo 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.
Währung: philippinischer Peso (PHP). PayMongo wird an der Kasse nur für Warenkörbe in PHP angezeigt. Wenn die Standardwährung Ihres Shops nicht PHP ist, warnt Sie die Einstellungsseite, und Kunden müssen auf PHP umstellen, um PayMongo zu sehen.
PayMongo-Konto: Sie benötigen die geheimen API-Schlüssel Ihres PayMongo-Kontos und einen Webhook für jeden Modus (siehe Konfiguration). Verwendet werden nur die geheimen Schlüssel (sk_test_..., sk_live_...) und die Signatur-Geheimnisse der Webhooks (whsk_...). Die öffentlichen Schlüssel werden nicht benötigt, da die Zahlungsseite von PayMongo gehostet wird. Die Zahlungsmethoden, die Sie anbieten, müssen für Ihr PayMongo-Konto aktiviert sein.
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 aus.
2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox PayMongo Payment Gateway in der Modulliste und klicken Sie auf Configure.
3. Geben Sie Ihren VibeFox-Lizenzschlüssel im Feld License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Fügen Sie Ihre geheimen PayMongo-Schlüssel ein, legen Sie die Webhooks in PayMongo an und fügen Sie deren Signatur-Geheimnisse ein (siehe Konfiguration).
5. Wählen Sie die Zahlungsmethoden, aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung bei aktiviertem Test mode und schalten Sie ihn danach wieder aus.
Bei der Installation legt das Modul zwei Bestellstatus an, Awaiting PayMongo payment und PayMongo payment on hold. Prüfen Sie unter Payment > Preferences, ob das Modul für den philippinischen Peso, die Länder Ihrer Kunden und deren Kundengruppen zugelassen ist.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt Sie die Seite, wenn die Standardwährung des Shops nicht PHP ist, wenn für den aktuellen Modus kein geheimer Schlüssel hinterlegt ist (PayMongo wird dann nicht an der Kasse angezeigt) oder kein Webhook-Geheimnis (Zahlungen werden dann nur bestätigt, wenn der Kunde in Ihren Shop zurückkehrt). Außerdem zeigt die Seite Test mode is on: no real payments are made. an, solange der Testmodus aktiv ist.
PayMongo
Enable/Disable: Enable PayMongo 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: PayMongo (Card, GCash, GrabPay, Maya). Pflichtfeld.
Description: der Text, der unter der Zahlungsmethode an der Kasse angezeigt wird. Standard: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.
Payment methods: die Methoden, die auf der Checkout-Seite von PayMongo angeboten werden. Wählen Sie nur Methoden aus, die für Ihr PayMongo-Konto aktiviert sind, sonst lehnt PayMongo den Checkout ab. Ist keine ausgewählt, werden die Standardmethoden verwendet. Standard: Cards, GCash, GrabPay and Maya.
API-Schlüssel
Kopieren Sie die geheimen Schlüssel aus dem PayMongo Dashboard > Developers > API keys. Die öffentlichen Schlüssel werden nicht benötigt. Jeder Schlüssel muss mit dem erwarteten Präfix beginnen. Ein Wert mit falschem Präfix wird nicht gespeichert: Die Seite zeigt an, dass das Feld must start with das Präfix enthalten muss, und dass The previous value was kept.
Test mode: Enable test mode (no real payments). Neue Zahlungen verwenden die Testschlüssel. Frühere Zahlungen behalten den Modus, in dem sie erfolgt sind, daher verwenden Statusprüfungen und Erstattungen den passenden Schlüssel. Standard: ein. Schalten Sie ihn aus, um echte Zahlungen anzunehmen.
Test secret key: der geheime Schlüssel des Testmodus. Er beginnt mit sk_test_.
Test webhook secret: das Signatur-Geheimnis des Webhooks im Testmodus. Es beginnt mit whsk_.
Live secret key: der geheime Schlüssel des Live-Modus. Er beginnt mit sk_live_.
Live webhook secret: das Signatur-Geheimnis des Webhooks im Live-Modus. Es beginnt mit whsk_.
Gespeicherte Schlüssel und Geheimnisse werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. an. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.
Clear saved secrets: Setzen Sie ein Häkchen bei einem Schlüssel oder Geheimnis und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Webhook
Der Webhook teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist, auch wenn der Kunde nach dem Bezahlen den Browser schließt. Legen Sie für jeden Modus, Test und Live, einen Webhook im PayMongo-Dashboard (oder über die PayMongo-API) mit der URL an, die in diesem Abschnitt unter Webhook URL angezeigt wird. Mit aktivierten SEO-URLs sieht sie etwa so aus: https://your-shop/module/wcp_paymongo_payment_gateway/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen.
Wählen Sie diese Ereignisse aus (sie sind auch in diesem Abschnitt aufgeführt):
Kopieren Sie das Signatur-Geheimnis (whsk_...) jedes Webhooks in Test webhook secret oder Live webhook secret. Webhooks ohne gültige Signatur werden abgelehnt. Die Signatur wird mit dem Geheimnis des eigenen Modus geprüft, und der Modus des Ereignisses muss dazu passen, sodass ein Test-Webhook nie eine Live-Zahlung bestätigt. Jedes Ereignis wird vor dem Anlegen oder Ändern einer Bestellung über die PayMongo-API mit dem geheimen Schlüssel des Zahlungsmodus erneut geprüft. PayMongo sendet die Ereignisse des gesamten Kontos an jeden Webhook; Ereignisse von Zahlungen, die nicht in diesem Shop gestartet wurden, werden ignoriert. Ohne Webhook wird eine Bestellung nur angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.
Bestellungen
Order status after payment: der Bestellstatus, der nach einer erfolgreichen Zahlung gesetzt wird.
Zahlungen, die noch verarbeitet werden, warten im Status Awaiting PayMongo payment. Abweichungen bei Betrag oder Währung sowie Testzahlungen in einem Live-Shop landen immer in PayMongo payment on hold.
Erweitert
Debug log: protokolliert die Aufrufe der PayMongo-API und die Webhook-Ereignisse in logs/paymongo_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Fehler und Warnungen werden immer protokolliert, auch wenn der Schalter aus ist. Schlüssel und Kundendaten werden nie protokolliert. 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 aktiv, werden beim Deinstallieren des Moduls die Einstellungen und das Protokoll gelöscht. Die für Bestellungen gespeicherten PayMongo-IDs, die Erstattungen und die Bestellstatus des Moduls bleiben immer erhalten, da sie für Erstattungen und die Buchhaltung benötigt werden. Standard: aus.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig PayMongo (Card, GCash, GrabPay, Maya)) und sieht deren Beschreibung. Im Testmodus zeigt die Kasse außerdem Test mode: no real payment will be made. an. PayMongo wird nur für Warenkörbe in PHP mit einer Summe von mindestens 100,00 ₱ angeboten.
Nach der Bestätigung legt das Modul eine PayMongo Checkout Session für die Warenkorbsumme in PHP an, mit einer Zeile Cart # und der Warenkorbnummer, und leitet den Kunden auf die Checkout-Seite von PayMongo weiter. Name, E-Mail-Adresse, Telefonnummer und Rechnungsadresse des Kunden werden an PayMongo übergeben. Dort wählt der Kunde eine der ausgewählten Methoden und bezahlt. 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, nachdem PayMongo die Zahlung bestätigt hat: Das Modul fragt die PayMongo-API nach der Zahlung, wenn der Kunde zurückkommt und wenn der Webhook eintrifft. Dann wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite mit Your PayMongo payment has been received. Wenn PayMongo die Zahlung bei der Rückkehr des Kunden noch verarbeitet, wird die Bestellung im Status Awaiting PayMongo payment angelegt, und die Seite zeigt PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. Schlägt diese Zahlung später fehl, zeigt die Seite Your PayMongo payment was not completed. Please contact us about this order. Wenn PayMongo bei der Rückkehr des Kunden nicht erreichbar ist, erscheint eine Seite Payment confirmation, die den Kunden bittet, nicht erneut zu bezahlen, und eine Schaltfläche Check again zeigt; der Webhook legt die Bestellung an, sobald er eintrifft.
Bricht der Kunde auf der PayMongo-Seite ab oder schließt er die Zahlung nicht ab, kehrt er zur Kasse zurück mit You cancelled the PayMongo payment. You can try again or choose another payment method. oder Your PayMongo payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten. Ein neuer Versuch prüft zuerst den vorherigen: Wurde dieser inzwischen bezahlt, wird die Bestellung ohne neue Zahlung angelegt. Andernfalls verfällt der vorherige PayMongo-Checkout-Link, sodass der Warenkorb nicht doppelt bezahlt werden kann. Solange die vorherige Zahlung noch verarbeitet wird, sieht der Kunde Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.
Kann PayMongo die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel The payment could not be started. Please try again or choose another payment method. oder PayMongo could not be reached. Please try again in a moment. Der technische Grund wird im Protokoll festgehalten.
Der Webhook funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.
Das Modul nimmt einmalige Zahlungen auf der Seite von PayMongo entgegen. Auf Ihrer eigenen Kasse gibt es keine Kartenfelder, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen, keine Ratenzahlungen und keine getrennte Autorisierung und Erfassung.
Bestellungen und Erstattungen
Bestellstatus
No order yet: Der Kunde wurde zu PayMongo weitergeleitet und hat noch nicht bezahlt, oder PayMongo hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.
Payment accepted or Delivered: Die Zahlung wurde bestätigt. Der Status richtet sich nach Order status after payment. Die Zahlung wird mit der PayMongo-Zahlungs-ID (pay_...) als Transaktions-ID erfasst, und eine Notiz zeigt die Zahlung, den Betrag, die Methode, den Modus und die Art der Bestätigung (Webhook oder Rückkehr).
Awaiting PayMongo payment: Der Kunde ist zurückgekehrt, während PayMongo die Zahlung noch verarbeitete. Die Bestellung wechselt in den bezahlten Status, sobald PayMongo die Zahlung bestätigt.
PayMongo payment on hold: Der bezahlte Betrag oder die Währung weicht von der Warenkorbsumme ab (zum Beispiel wurde der Warenkorb in einem anderen Tab geändert, nachdem die Zahlung begonnen hatte); oder eine Zahlung wurde im Testmodus getätigt, während der Shop im Live-Modus war, sodass kein Geld eingegangen ist und keine Zahlung erfasst wird; oder die Zahlung kam erst an, nachdem die Bestellung storniert worden war. Die Notiz erklärt es. Prüfen Sie die Bestellung und bearbeiten Sie sie oder erstatten Sie die Zahlung.
Payment error: Ein signierter Webhook payment.failed meldete, dass der letzte Zahlungsversuch einer Bestellung im Status Awaiting PayMongo payment fehlgeschlagen ist. Die Notiz zeigt den Fehlercode und die Meldung von PayMongo. Wenn dieselbe Zahlung später erfolgreich ist, wechselt die Bestellung in den bezahlten Status.
Refunded: Die Zahlung wurde über das Modul vollständig erstattet.
Geht eine zweite Zahlung für eine bereits bezahlte Bestellung ein, zum Beispiel über einen alten Checkout-Link, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, die doppelte Zahlung im PayMongo-Dashboard zu erstatten. Eine bezahlte und danach stornierte oder erstattete Bestellung wird nie wieder geöffnet.
PayMongo-Zahlungsblock
Die Bestellseite zeigt einen Block PayMongo payment mit der PayMongo-Zahlungs-ID und der Methode, dem Payment Intent, dem Checkout, dem Modus, dem Status, dem bezahlten und dem erstatteten Betrag, einem Kennzeichen Test mode für Testzahlungen, den PayMongo-Notizen der Bestellung und dem Erstattungsverlauf.
Erstattungen
Geben Sie im Block PayMongo payment den Betrag ein (vorausgefüllt wird der noch nicht erstattete Betrag), optional einen Grund, und klicken Sie auf Refund via PayMongo. Bestätigen Sie die Frage Refund this amount through PayMongo? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt, mit höchstens zwei Dezimalstellen. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig. Erstattungen sind auf den Betrag begrenzt, den PayMongo tatsächlich eingezogen hat. Nach einer Betragsabweichung können Sie daher bis zu dem Betrag erstatten, den der Kunde bezahlt hat, nicht die Bestellsumme. Die Erstattung wird mit dem geheimen Schlüssel des Modus gesendet, in dem die Zahlung erfolgt ist (Test oder Live), daher muss dieser Schlüssel hinterlegt sein. Der Grund, den Sie eingeben, wird als Erstattungsnotiz an PayMongo übermittelt. Akzeptiert PayMongo die Erstattung nicht, zeigt der Block den Fehler an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der PayMongo-Erstattungs-ID und dem Status hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht.
Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite überweisen kein Geld über PayMongo zurück. Erstattungen, die im PayMongo-Dashboard vorgenommen werden, werden nicht nach PrestaShop übernommen. Erstatten Sie stattdessen über den Bestellblock oder aktualisieren Sie die Bestellung manuell.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox PayMongo Payment Gateway ist der erste Block auf Modules > Module Manager > VibeFox PayMongo Payment 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, 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-paymongo 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 einen Domain-Platz 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: die Domain des Hauptshops, auch in einem Multistore-Setup. 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 PayMongo Kunden an 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 Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht an der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.
Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen jedoch eine Verlängerung. Der Status wird während Ihrer 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 Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
PayMongo wird an der Kasse nicht angezeigt: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, der aktuelle Modus einen geheimen Schlüssel hat (Test secret key im Testmodus, Live secret key im Live-Modus), der Warenkorb in PHP ist und die Summe mindestens 100,00 ₱ beträgt. 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 ist erfolgt, aber es wurde keine Bestellung angelegt: Der Webhook funktioniert nicht, und der Kunde ist nicht in den Shop zurückgekehrt. Prüfen Sie im PayMongo-Dashboard, ob im verwendeten Modus ein Webhook existiert, ob seine URL genau der unter Webhook URL angezeigten entspricht und ob alle drei Ereignisse ausgewählt sind. Prüfen Sie, ob sein Signatur-Geheimnis im passenden Feld steht (Test webhook secret oder Live webhook secret).
Der Webhook antwortet Invalid signature: Das Signatur-Geheimnis für diesen Modus fehlt oder gehört zu einem anderen Webhook. Fügen Sie das Signatur-Geheimnis des Webhooks in das Feld seines Modus ein.
Der Webhook antwortet Mode mismatch: Ein Testereignis wurde als Live-Ereignis signiert oder umgekehrt. Prüfen Sie, ob jeder Webhook zum richtigen Modus gehört.
Der Webhook antwortet Temporary error: Die Zahlung konnte nicht über die PayMongo-API geprüft werden, zum Beispiel weil der geheime Schlüssel des Zahlungsmodus fehlt. PayMongo wiederholt den Webhook automatisch.
Der Webhook antwortet Busy, retry: 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). PayMongo wiederholt den Webhook automatisch. Der Grund steht im Log.
Der Webhook antwortet Ignored: Das Ereignis gehört zu einer Zahlung, die nicht in diesem Shop gestartet wurde, oder zu einem anderen Modus. Es wird nichts verändert.
Die Webhook-URL zeigt im Browser Method not allowed: Das ist normal. Die URL akzeptiert nur Anfragen von PayMongo.
Der Wert wurde nicht gespeichert: Ein Schlüssel wurde in das falsche Feld eingefügt. Geheime Schlüssel beginnen mit sk_test_ oder sk_live_, Webhook-Geheimnisse mit whsk_.
Der Kunde sieht beim Wählen von PayMongo einen Fehler: Sehen Sie im Feld Log auf der Modulseite nach. Ein falscher geheimer Schlüssel führt zur Meldung, dass die Zahlungsmethode vorübergehend nicht verfügbar ist. Eine Zahlungsmethode, die für Ihr PayMongo-Konto nicht aktiviert ist, lässt PayMongo den Checkout ablehnen; entfernen Sie sie unter Payment methods.
Testzahlungen in einem Live-Shop: Eine Testzahlung, die eintrifft, während der Shop im Live-Modus ist, setzt die Bestellung auf PayMongo payment on hold mit einer Notiz, dass kein Geld eingegangen ist. Echte Zahlungen werden immer erkannt, auch nach dem Zurückschalten in den Testmodus, und mit dem Live-Schlüssel erstattet.
Bestellung nach der Zahlung im Status PayMongo payment on hold: Lesen Sie die Notizen im Block PayMongo payment (siehe Bestellstatus) und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.
Erstattung schlägt mit einer Meldung zum Modus fehl: Die Zahlung wurde im Test- oder Live-Modus getätigt, und der geheime Schlüssel dieses Modus ist nicht hinterlegt. Geben Sie ihn ein und versuchen Sie es erneut.
Entwickler können die Daten der Checkout Session mit dem Hook actionPaymongoPCheckoutSessionData ändern.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox PayMongo Payment Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall aktiv, werden die Einstellungen und das Protokoll gelöscht. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die PayMongo-IDs der Bestellungen, die Erstattungen und die Bestellstatus Awaiting PayMongo payment und PayMongo payment on hold bleiben immer erhalten, sodass bereits zuvor bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
PayMongo ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit PayMongo verbunden und wird nicht von PayMongo unterstützt.