VibeFox dLocal for WooCommerce — Hilfe
Anforderungen
WordPress: 5.8 oder neuer.
WooCommerce: 7.0 oder neuer, installiert und aktiv.
PHP: 8.0 oder neuer. Das Plugin lässt sich mit einer älteren PHP- oder WordPress-Version nicht aktivieren.
Erreichbarkeit der Website: Ihre Website muss aus dem Internet erreichbar sein und im Live-Betrieb HTTPS verwenden, damit dLocal Go Zahlungsbenachrichtigungen zustellen kann. Eine Firewall, der Wartungsmodus oder eine Basic-Authentifizierung können sie blockieren.
dLocal-Go-Konto: Sie benötigen den API-Schlüssel und das API-Secret aus dem dLocal-Go-Dashboard, Bereich Payment integration: dashboard-sbx.dlocalgo.com für Sandbox, dashboard.dlocalgo.com für Live. Sandbox und Live verwenden unterschiedliche Zugangsdaten. Die Enterprise-API dLocal Payments (Zugangsdaten X-Login / X-Trans-Key) ist ein anderes Produkt und wird nicht unterstützt.
Länder und Währungen: Das Plugin schränkt sie nicht ein. dLocal Go entscheidet, welche Zahlungsmethoden für das Land des Kunden und die Shop-Währung angeboten werden.
VibeFox-Lizenzschlüssel: erhältlich 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 den Ordner wcp_dlocal_payment auch per FTP nach /wp-content/plugins/ hochladen.
2. Klicken Sie auf Activate. WooCommerce muss aktiv sein.
3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > dLocal Go > 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. Wählen Sie das Environment und fügen Sie den API-Schlüssel und das API-Secret dieser Umgebung ein (siehe Konfiguration).
6. Schalten Sie Enable/Disable ein und speichern Sie. Testen Sie eine Zahlung in der Sandbox und stellen Sie dann Environment auf Production um.
Konfiguration
Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > dLocal Go. Der Seitentitel zeigt SANDBOX oder PRODUCTION. Solange der API-Schlüssel und das Secret der ausgewählten Umgebung nicht eingegeben sind, weist die Seite darauf hin, dass die Zahlungsmethode an der Kasse ausgeblendet ist. Solange Sandbox ausgewählt und das Gateway aktiviert ist, zeigt sie Sandbox mode is active: payments are simulated, no money is charged. In der Liste der Zahlungsmethoden ist dLocal Go als einrichtungsbedürftig markiert, bis die Zugangsdaten gesetzt sind, und zeigt in der Sandbox Test mode.
Allgemein
Enable/Disable: Enable dLocal Go schaltet die Zahlungsmethode ein oder aus. Standard: aus.
Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: dLocal Go.
Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay with local cards, bank transfer or cash via dLocal Go.
API-Zugangsdaten
Kopieren Sie den API-Schlüssel und das API-Secret aus dem dLocal-Go-Dashboard, Payment integration: dashboard-sbx.dlocalgo.com (Sandbox) oder dashboard.dlocalgo.com (Live). Alle Felder für Zugangsdaten sind Passwortfelder.
Environment: welche Zugangsdaten und welche dLocal-Go-Server verwendet werden.
Sandbox API Key: Ihr dLocal-Go-API-Schlüssel für die Sandbox.
Sandbox API Secret: Ihr dLocal-Go-API-Secret für die Sandbox.
Production API Key: Ihr dLocal-Go-API-Schlüssel für den Live-Betrieb.
Production API Secret: Ihr dLocal-Go-API-Secret für den Live-Betrieb.
Zahlung
Default country: dLocal Go zeigt die Zahlungsmethoden des Landes des Kunden, das aus der Rechnungsadresse und danach aus der Lieferadresse übernommen wird. Dieses Land wird verwendet, wenn die Bestellung keine von beiden hat. Standard: Uruguay.
Auto-complete orders: Set paid orders to "Completed" instead of "Processing". Der Status wird sofort gesetzt, mit nur einem Satz E-Mails. Standard: aus.
Benachrichtigungen (IPN)
Die Benachrichtigungen teilen Ihrem Shop mit, dass sich eine Zahlung oder eine Erstattung geändert hat. Das Plugin sendet die Benachrichtigungs-URLs bei jeder Zahlung und Erstattung an dLocal Go, sodass im dLocal-Go-Dashboard nichts konfiguriert werden muss. Dieser Bereich der Einstellungen zeigt beide URLs:
Benachrichtigungen werden mit Ihrem API-Secret verifiziert (HMAC-SHA256). Benachrichtigungen ohne gültige Signatur werden abgelehnt. Danach werden Status, Betrag und Währung der Zahlung immer erneut über die dLocal-Go-API abgerufen; dem Inhalt der Benachrichtigung wird nicht vertraut. Ohne Benachrichtigungen wird eine Bestellung nur aktualisiert, wenn der Kunde in den Shop zurückkehrt.
Erweitert
Debug log: Log API requests and notifications schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_dlocal_payment, ohne API-Zugangsdaten oder personenbezogene Daten. Fehler werden immer protokolliert. Standard: aus.
Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). Standard: aus.
Kasse
Der Kunde wählt die Zahlungsmethode (standardmäßig dLocal Go) und sendet die Bestellung ab. Das Plugin erstellt eine dLocal-Go-Zahlung über den Gesamtbetrag der Bestellung in der Bestellwährung, mit Land, Name, E-Mail-Adresse und Telefonnummer des Kunden, und leitet den Kunden auf die Zahlungsseite von dLocal Go weiter. Dort bezahlt der Kunde mit einer Methode seines Landes. Auf der Seite von dLocal Go erscheint die Zahlung als Order # mit der Bestellnummer. Im Sandbox-Modus zeigt die Kasse unter der Zahlungsmethode Sandbox mode: no real payment is made.
Nach der Zahlung kehrt der Kunde auf die Seite „Bestellung erhalten“ Ihres Shops zurück. Die Bestellung wird erst als bezahlt markiert, wenn dLocal Go sie bestätigt: durch die signierte Benachrichtigung oder durch eine serverseitige Anfrage an die dLocal-Go-API, wenn der Kunde auf dieser Seite ankommt.
Verlässt der Kunde die Seite von dLocal Go ohne Zahlung, kehrt er zur Kasse (oder zur Seite Pay for order) zurück und sieht The payment at dLocal Go was not completed. You can try again or choose another payment method. Wurde die Zahlung abgelehnt oder ist sie abgelaufen, lautet die Meldung Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. Stellt sich heraus, dass die Zahlung bereits erfolgt ist, wird der Kunde auf die Seite „Bestellung erhalten“ weitergeleitet. Ein älterer Zahlungslink derselben Bestellung kann nach einem erneuten Versuch weiterhin bezahlt werden.
Kann dLocal Go die Zahlung nicht starten, sieht der Kunde eine kurze Meldung ohne technische Details, zum Beispiel dLocal could not start the payment: gefolgt vom Grund von dLocal, und kann eine andere Methode wählen. Das passiert auch, wenn das Land des Kunden und die Shop-Währung in Ihrem dLocal-Go-Konto nicht freigeschaltet sind. Der technische Grund wird ins Protokoll geschrieben.
Die Zahlungsmethode funktioniert in der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist kompatibel mit der WooCommerce High-Performance Order Storage (HPOS).
Das Plugin akzeptiert nur Einmalzahlungen auf der Seite von dLocal Go. Es bietet kein Kartenformular auf Ihrer Website, keine gespeicherten Karten, keine Abonnements und keine getrennte Autorisierung und Erfassung.
Bestellungen und Erstattungen
Bestellstatus
Pending payment: Der Kunde wurde zu dLocal Go weitergeleitet und hat noch nicht bezahlt, oder die Zahlung ist bei dLocal Go ausstehend (zum Beispiel ein noch nicht bezahlter Bargeld-Gutschein). Jeder neue Zahlungsversuch wird in der Bestellung mit seiner dLocal-Zahlungs-ID, dem Betrag und der Umgebung vermerkt.
Processing or Completed: Die Zahlung wurde bestätigt. Die Bestellung ist „In Bearbeitung“ (WooCommerce-Standard) oder „Fertiggestellt“, wenn Auto-complete orders eingeschaltet ist. Die Transaktions-ID ist die dLocal-Zahlungs-ID.
On hold: dLocal Go hat einen anderen Betrag oder eine andere Währung als den Gesamtbetrag der Bestellung gemeldet, oder die Zahlung ist eingegangen, nachdem die Bestellung storniert wurde. Die Bestellnotiz erklärt dies. Gleichen Sie mit dem dLocal-Go-Dashboard ab und führen Sie die Bestellung aus oder erstatten Sie die Zahlung.
Failed: Der letzte Zahlungsversuch wurde abgelehnt oder ist abgelaufen. Der Kunde kann es erneut versuchen.
Cancelled: dLocal Go hat den letzten Zahlungsversuch als storniert gemeldet.
Nur der letzte Zahlungsversuch kann eine unbezahlte Bestellung fehlschlagen lassen oder stornieren. Eine bezahlte Bestellung wird nie durch eine alte Benachrichtigung wieder geöffnet. Geht eine zweite Zahlung für eine bereits bezahlte Bestellung ein, wird die Bestellung nicht geändert. Eine Notiz bittet Sie, die doppelte Zahlung im dLocal-Go-Dashboard zu erstatten.
Erstattungen
Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via dLocal Go. Vollständige und teilweise Erstattungen werden für Bestellungen unterstützt, die über dLocal Go bezahlt wurden. Die Erstattung wird an die Umgebung gesendet, in der die Zahlung erfolgt ist, mit den Zugangsdaten dieser Umgebung. Wenn dLocal Go die Erstattung nicht annimmt, zeigt WooCommerce den Fehler an und es wird keine Erstattung erfasst. Eine angenommene Erstattung wird mit Erstattungs-ID und Status den Bestellnotizen hinzugefügt.
dLocal Go meldet anschließend den endgültigen Erstattungsstatus über die Erstattungsbenachrichtigung, und er wird den Bestellnotizen hinzugefügt. Lehnt dLocal Go eine bereits angenommene Erstattung später ab oder storniert sie, warnt die Notiz, dass das Geld nicht an den Kunden zurückgezahlt wurde. Prüfen Sie die dafür erfasste WooCommerce-Erstattung: Löschen Sie sie und erstatten Sie erneut, oder erstatten Sie dem Kunden auf andere Weise.
Erstattungen im dLocal-Go-Dashboard werden nicht als WooCommerce-Erstattungen erfasst und fügen in der Regel keine Bestellnotiz hinzu. Legen Sie bei Bedarf eine manuelle Erstattung in WooCommerce ohne Refund via dLocal Go an.
Lizenzschlüssel
Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > dLocal Go. 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. 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 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 dLocal Go 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 Zahlungsmethode weiterhin, markiert mit (unlicensed — visible to admins only), sodass 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 gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.
Wenn eine Lizenz abläuft, funktioniert das Plugin weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.
Fehlerbehebung
dLocal Go erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und der API-Schlüssel und das API-Secret des ausgewählten Environment gesetzt sind. Die Einstellungsseite zeigt eine Warnung, wenn sie fehlen.
Die Zahlung ist durchgegangen, aber die Bestellung bleibt bei „Zahlung ausstehend“: dLocal Go konnte die Benachrichtigungs-URL nicht erreichen (Firewall, Wartungsmodus, Basic-Authentifizierung), und der Kunde ist nicht auf die Seite „Bestellung erhalten“ zurückgekehrt. Prüfen Sie WooCommerce > Status > Logs, Quelle wcp_dlocal_payment, und die Zahlung im dLocal-Go-Dashboard. Sobald eine Benachrichtigung eingeht oder der Kunde die Seite „Bestellung erhalten“ öffnet, wird die Bestellung aktualisiert.
Die Benachrichtigung antwortet mit Missing signature oder Invalid signature: Der API-Schlüssel und das Secret in den Einstellungen gehören nicht zu dem Konto, das die Benachrichtigung gesendet hat. Benachrichtigungen werden mit den Zugangsdaten beider Umgebungen geprüft, sodass Zahlungen, die vor dem Umstellen von Environment gestartet wurden, weiterhin bestätigt werden, solange die Zugangsdaten ihrer Umgebung in den Einstellungen bleiben.
Die Benachrichtigung antwortet mit Gateway not configured: Die Zugangsdaten der ausgewählten Umgebung fehlen. dLocal Go wiederholt die Benachrichtigung.
Die Benachrichtigung antwortet mit API verification failed: Die dLocal-Go-API war nicht erreichbar, um die Zahlung abzurufen. dLocal Go wiederholt die Benachrichtigung.
Die Benachrichtigung antwortet mit Order not found: Die Zahlung gehört nicht zu einer Bestellung dieses Shops, sie wurde zum Beispiel von einer anderen Website mit demselben dLocal-Go-Konto erstellt.
Der Kunde sieht This payment method is temporarily unavailable: dLocal Go hat den API-Schlüssel oder das Secret abgelehnt. Prüfen Sie die Zugangsdaten der ausgewählten Umgebung.
Die Bestellung ist nach der Zahlung „In Wartestellung“: Lesen Sie die Bestellnotiz. Der bezahlte Betrag oder die Währung wich von der Bestellung ab, oder die Zahlung ging ein, nachdem die Bestellung storniert wurde. Führen Sie die Bestellung aus oder erstatten Sie die Zahlung.
Die Erstattung schlägt mit einer Meldung über fehlende Zugangsdaten fehl: Die Zahlung erfolgte in der anderen Umgebung, und deren Zugangsdaten sind nicht gesetzt. Geben Sie sie ein und versuchen Sie es erneut.
Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Wird 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.
Für Entwickler listet die Plugin-Dokumentation die Filter dlocal_p_payment_data, dlocal_p_currency_decimals und dlocal_p_icon auf.
Deinstallation
Beim Deaktivieren des Plugins bleiben alle Daten erhalten. 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 und die Protokolle werden nur entfernt, wenn Delete data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
dLocal ist eine Marke des jeweiligen Inhabers. Dieses Plugin ist nicht mit dLocal verbunden und wird nicht von dLocal unterstützt.