VibeFox PayMongo for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 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: Philippinischer Peso (PHP). Die Zahlungsart wird ausgeblendet, wenn die Shop-Währung oder die Bestellwährung auf der Seite Pay for order nicht PHP ist.

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_...). Öffentliche Schlüssel werden nicht benötigt, da die Zahlungsseite von PayMongo gehostet wird. Die von Ihnen angebotenen Zahlungsmethoden müssen für Ihr PayMongo-Konto aktiviert sein.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel funktioniert auf einer 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 auch den Ordner wcp_paymongo_payment_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > PayMongo > 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. Fügen Sie Ihre geheimen PayMongo-Schlüssel ein, erstellen Sie die Webhooks und fügen Sie deren Signatur-Geheimnisse ein (siehe Konfiguration).

6. Wählen Sie die Zahlungsmethoden, aktivieren Sie Enable/Disable und speichern Sie. Testen Sie eine Zahlung mit eingeschaltetem Test mode und schalten Sie ihn danach aus.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > PayMongo. Oberhalb der Felder warnt Sie die Seite, wenn die Shop-Währung nicht PHP ist, wenn der aktuelle Modus keinen geheimen Schlüssel hat (dann wird PayMongo an der Kasse nicht angezeigt) oder kein Webhook-Geheimnis (dann werden Zahlungen nur bestätigt, wenn der Kunde zurückkehrt). Während der Testmodus aktiv ist, zeigt die Seite Test mode is on: no real payments are made. In der Liste der Zahlungsmethoden ist PayMongo als einrichtungsbedürftig markiert, bis der aktuelle Modus einen geheimen Schlüssel hat.

Allgemein

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

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: PayMongo (Card, GCash, GrabPay, Maya).

Description: der Text, der an der Kasse unter der Zahlungsart 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 PayMongo-Zahlungsseite angeboten werden. Wählen Sie nur Methoden aus, die für Ihr PayMongo-Konto aktiviert sind, sonst lehnt PayMongo die Kasse ab. Standard: Cards, GCash, GrabPay and Maya.

API-Schlüssel

Kopieren Sie die geheimen Schlüssel aus PayMongo Dashboard > Developers > API keys. Öffentliche 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, dass das Feld must start with das Präfix haben 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: an. 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_.

Webhook

Der Webhook teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist, auch dann, wenn der Kunde nach der Zahlung den Browser schließt. Erstellen Sie im PayMongo-Dashboard (oder über die PayMongo-API) für jeden Modus, Test und Live, einen Webhook mit der URL, die in diesem Abschnitt der Einstellungen angezeigt wird. Sie sieht etwa so aus: https://your-site/?wc-api=paymongo_p_webhook.

Wählen Sie diese Ereignisse aus:

Kopieren Sie das Signatur-Geheimnis (whsk_...) jedes Webhooks in Test webhook secret bzw. Live webhook secret. Webhooks ohne gültige Signatur werden abgelehnt, und der Modus des Ereignisses muss mit dem Modus der Signatur übereinstimmen. Jedes Ereignis wird vor einer Änderung der Bestellung erneut über die PayMongo-API geprüft. PayMongo sendet die Ereignisse des gesamten Kontos an jeden Webhook; Ereignisse zu Zahlungen, die nicht von diesem Shop erstellt wurden, werden ignoriert. Ohne Webhook werden Zahlungen nur bestätigt, wenn der Kunde in Ihren Shop zurückkehrt.

Bestellungen

Bestellstatus nach Zahlung: der Bestellstatus, der nach einer erfolgreichen Zahlung gesetzt wird. Der Status wird sofort gesetzt, ohne zweite Statusänderung.

Erweitert

Debug log: Log API calls and webhook events schreibt sie nach WooCommerce > Status > Logs, Quelle wcp_paymongo_payment_gateway. Fehler werden immer protokolliert. Schlüssel und Kundendaten werden nie protokolliert. Standard: aus.

Delete data on uninstall: Delete the settings and logs when the plugin is deleted. Auf Bestellungen gespeicherte PayMongo-IDs bleiben erhalten, weil sie für Erstattungen und die Buchhaltung benötigt werden. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig PayMongo (Card, GCash, GrabPay, Maya)) und gibt die Bestellung auf. Im Testmodus zeigt die Kasse Test mode: no real payment will be made. Das Plugin erstellt für den Bestellbetrag in PHP eine PayMongo-Checkout-Session mit einer Zeile Order # und der Bestellnummer und leitet den Kunden auf die PayMongo-Zahlungsseite 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.

Die Zahlungsart wird nur für Bestellungen ab 100,00 ₱ angezeigt. Ein geringerer Bestellbetrag kann nicht mit PayMongo bezahlt werden.

Nach der Zahlung kehrt der Kunde zur Seite Bestellung eingegangen Ihres Shops zurück. Die Bestellung wird erst als bezahlt markiert, wenn PayMongo die Zahlung bestätigt: Das Plugin fragt die PayMongo-API nach der Zahlung, wenn der Kunde zurückkehrt, und wenn der Webhook eingeht. Wenn PayMongo die Zahlung noch verarbeitet oder nicht erreichbar ist, landet der Kunde trotzdem auf der Seite Bestellung eingegangen, und der Webhook schließt die Bestellung später ab.

Bricht der Kunde auf der PayMongo-Seite ab oder schließt er die Zahlung nicht ab, gelangt er auf die Seite Pay for order mit der Meldung 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. Die Bestellung bleibt unbezahlt. Ein neuer Versuch prüft zuerst den vorherigen: Wurde sie inzwischen bezahlt, wird die Bestellung ohne neue Zahlung abgeschlossen; andernfalls läuft der vorherige PayMongo-Checkout-Link ab, sodass der Kunde nicht zweimal zahlen 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, sieht der Kunde eine kurze 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 den Bestellnotizen hinzugefügt.

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

Das Plugin nimmt einmalige Zahlungen auf der PayMongo-Seite entgegen. Es gibt kein Kartenformular auf Ihrer eigenen Kasse, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen, keine Ratenzahlungen und keine getrennte Autorisierung und Erfassung.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Der Kunde wurde zu PayMongo weitergeleitet und hat noch nicht bezahlt, oder PayMongo hat die Zahlung noch nicht bestätigt. Eine Notiz verzeichnet jeden für die Bestellung erstellten PayMongo-Checkout. Während PayMongo eine Zahlung verarbeitet, weist eine Notiz darauf hin.

Processing or Completed: Die Zahlung wurde bestätigt. Der Status richtet sich nach Order status after payment. Die Bestellnotiz zeigt die PayMongo-Zahlung, den Betrag, die Methode und den Modus. Die Transaktions-ID ist die PayMongo-Zahlungs-ID (pay_...). Der Bestellbildschirm zeigt den PayMongo-Checkout, die Zahlungsabsicht und den Modus unter der Rechnungsadresse.

On hold: Der bezahlte Betrag oder die Währung weicht von der Bestellung ab (Notiz amount/currency mismatch); oder eine Zahlung erfolgte im Testmodus, während der Shop im Live-Modus ist, daher ist kein Geld eingegangen; oder die Zahlung kam an, nachdem die Bestellung storniert wurde, zum Beispiel durch das Zeitlimit der Lagerreservierung. Die Bestellnotiz erklärt es. Prüfen Sie die Bestellung und bearbeiten Sie sie oder erstatten Sie die Zahlung.

Failed: Ein signierter payment.failed-Webhook meldete, dass der letzte Zahlungsversuch einer ausstehenden Bestellung fehlgeschlagen ist. Die Notiz zeigt den PayMongo-Fehlercode und die Meldung. Der Kunde kann erneut zahlen.

Geht für eine bereits bezahlte Bestellung eine zweite Zahlung 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 stornierte oder erstattete Bestellung, die bezahlt war, wird nie wieder geöffnet.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via PayMongo (Card, GCash, GrabPay, Maya) (die Schaltfläche zeigt den Titel Ihrer Zahlungsart). Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird mit dem geheimen Schlüssel des Modus gesendet, in dem die Zahlung erfolgte (Test oder Live); dieser Schlüssel muss daher eingetragen sein. Akzeptiert PayMongo die Erstattung nicht, zeigt WooCommerce den Fehler an und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit der PayMongo-Erstattungs-ID und dem Status in den Bestellnotizen vermerkt.

Im PayMongo-Dashboard vorgenommene Erstattungen werden nicht nach WooCommerce übernommen. Erstatten Sie stattdessen aus der WooCommerce-Bestellung oder legen Sie in WooCommerce eine manuelle Erstattung an.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > PayMongo. 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 auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt deren 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. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert mit (unlicensed — visible to admins only), damit 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 begonnene Zahlungen werden weiterhin bestätigt und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, Updates und Support erfordern jedoch eine Verlängerung. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

PayMongo erscheint nicht an der Kasse: 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), die Shop-Währung PHP ist und der Bestellbetrag mindestens 100,00 ₱ beträgt. Entwickler können das Minimum mit dem Filter paymongo_p_minimum_amount ändern.

Die Zahlung ist erfolgt, aber die Bestellung bleibt auf Pending payment: 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 in den Einstellungen angezeigten entspricht und ob die 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 dieses 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 signiert oder umgekehrt. Prüfen Sie, dass jeder Webhook zum richtigen Modus gehört.

Der Webhook antwortet Temporary error: Die Zahlung konnte nicht über die PayMongo-API geprüft werden, oder die Bestellung wurde im selben Moment von einer anderen Anfrage verarbeitet. PayMongo wiederholt den Webhook automatisch.

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 Aufgeben der Bestellung einen Fehler: Öffnen Sie die Bestellnotizen oder sehen Sie unter WooCommerce > Status > Logs nach, Quelle wcp_paymongo_payment_gateway. Ein falscher geheimer Schlüssel führt zur Meldung, dass die Zahlungsart vorübergehend nicht verfügbar ist. Eine Zahlungsmethode, die für Ihr PayMongo-Konto nicht aktiviert ist, führt dazu, dass PayMongo die Kasse ablehnt; entfernen Sie sie aus Payment methods.

Testzahlungen in einem Live-Shop: Eine Testzahlung, die eingeht, während der Shop im Live-Modus ist, setzt die Bestellung auf Wartend, mit einer Notiz, dass kein Geld eingegangen ist. Echte Zahlungen werden immer erkannt, auch nach dem Wechsel zurück in den Testmodus, und werden mit dem Live-Schlüssel erstattet.

Bestellung nach der Zahlung auf On hold: Lesen Sie die Bestellnotiz. Der bezahlte Betrag oder die Währung wich von der Bestellung ab, die Zahlung war eine Testzahlung oder sie kam, nachdem die Bestellung storniert wurde. Bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung.

Erstattung schlägt mit einer Meldung zum Modus fehl: Die Zahlung erfolgte im Test- oder Live-Modus, und der geheime Schlüssel dieses Modus ist nicht eingetragen. Tragen Sie ihn ein und versuchen Sie es erneut.

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

Deinstallation

Das Deaktivieren des Plugins behält alle Daten. Zum 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 temporären Daten und die Protokolle werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Transaktions-IDs und PayMongo-IDs.

PayMongo ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist nicht mit PayMongo verbunden und wird nicht von PayMongo unterstützt.