VibeFox dLocal 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.

Shop-Zugang: Ihr Shop muss aus dem Internet erreichbar sein und im Live-Betrieb HTTPS verwenden, damit dLocal Go Zahlungsbenachrichtigungen zustellen kann.

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 Modul begrenzt sie nicht. dLocal Go entscheidet, welche Zahlungsmethoden für das Land des Kunden und die Warenkorbwährung angeboten werden. Es gelten nur die Zahlungsbeschränkungen von PrestaShop.

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 VibeFox dLocal Payment später in der Modulliste und klicken Sie 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 die Environment und tragen Sie API-Schlüssel und API-Secret dieser Umgebung ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung in Sandbox und wechseln Sie dann die Environment auf Production.

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

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox dLocal Payment > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Der Titel des ersten Abschnitts zeigt SANDBOX oder PRODUCTION. Solange API-Schlüssel und Secret der gewählten Umgebung nicht eingetragen sind, warnt die Seite, dass die Zahlungsmethode in der Kasse ausgeblendet ist, zum Beispiel Enter the sandbox API key and secret: until then the payment method is hidden at checkout. Ist Sandbox gewählt und die Zahlungsmethode aktiviert, erscheint Sandbox mode is active: payments are simulated, no money is charged.

dLocal Go

Enable/Disable: Enable dLocal Go schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden in der Kasse sehen. Er wird auch als Zahlungsmethode in der Bestellung gespeichert. Standard: dLocal Go. Pflichtfeld.

Description: der Text, der in der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay with local cards, bank transfer or cash via dLocal Go.

API-Zugangsdaten

Kopieren Sie API-Schlüssel und API-Secret aus dem dLocal-Go-Dashboard, Payment integration: dashboard-sbx.dlocalgo.com (Sandbox) oder dashboard.dlocalgo.com (Live). Der Abschnitt verlinkt beide Dashboards.

Environment: welche Zugangsdaten und welche dLocal-Go-Server für neue Zahlungen verwendet werden.

Erstattungen und Benachrichtigungen einer Zahlung verwenden immer die Zugangsdaten der Umgebung, in der die Zahlung erfolgt ist. Behalten Sie daher die Zugangsdaten der anderen Umgebung, solange deren Zahlungen noch offen sind oder erstattet werden können.

Sandbox API Key: Ihr API-Schlüssel für die dLocal-Go-Sandbox.

Sandbox API Secret: Ihr API-Secret für die dLocal-Go-Sandbox.

Production API Key: Ihr API-Schlüssel für die dLocal-Go-Live-Umgebung.

Production API Secret: Ihr API-Secret für die dLocal-Go-Live-Umgebung.

Gespeicherte Schlüssel und Secrets 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 credentials: Markieren Sie einen Schlüssel oder ein Secret und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlung

Default country: dLocal Go zeigt die Zahlungsmethoden des Landes des Kunden, übernommen aus der Rechnungsadresse, danach aus der Lieferadresse. Dieses Land wird verwendet, wenn der Warenkorb keines von beiden hat. Standard: Uruguay.

Auto-complete orders: setzt bezahlte Bestellungen auf Delivered statt auf Payment accepted. Der Status wird sofort mit einer einzigen Statusänderung gesetzt. Standard: aus.

Notifications (IPN): Die Benachrichtigungen informieren Ihren Shop, dass sich eine Zahlung oder Erstattung geändert hat. Das Modul sendet die Benachrichtigungs-URLs bei jeder Zahlung und jeder Erstattung an dLocal Go, daher muss im dLocal-Go-Dashboard nichts konfiguriert werden. Dieses Feld zeigt beide URLs:

Benachrichtigungen werden mit Ihrem API-Secret (HMAC-SHA256) geprüft. Benachrichtigungen ohne gültige Signatur werden abgelehnt. Eine Benachrichtigung muss mit den Zugangsdaten der Umgebung signiert sein, in der die Zahlung erfolgt ist. Danach werden Status, Betrag und Währung der Zahlung immer erneut über die API von dLocal Go abgerufen; dem Inhalt der Benachrichtigung wird nicht vertraut. Ohne Benachrichtigungen wird eine Bestellung nur angelegt, wenn der Kunde in den Shop zurückkehrt.

Erweitert

Debug log: schreibt Anfragen und Benachrichtigungen von dLocal Go in logs/dlocal_p_debug.log.php im Modulordner. Die Datei kann nicht aus dem Web geöffnet werden. API-Zugangsdaten und personenbezogene Daten werden nicht protokolliert. Fehler und Warnungen werden immer geschrieben; die übrigen Einträge nur, solange diese Option aktiv ist. 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: Wenn aktiviert, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und das Protokoll. Die Zahlungsdaten der Bestellungen (dLocal-Zahlungen und -Erstattungen) und der Bestellstatus dLocal payment on hold bleiben immer erhalten, damit bestehende Bestellungen weiter funktionieren. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig dLocal Go). Im Sandbox-Modus zeigt die Kasse Sandbox mode: no real payment is made. unter der Zahlungsmethode an. Nach der Bestätigung erstellt das Modul eine Zahlung bei dLocal Go über den Warenkorbbetrag in der Warenkorbwährung, mit Land, Name, E-Mail und Telefonnummer des Kunden, und leitet den Kunden auf die Zahlungsseite von dLocal Go weiter. Dort zahlt der Kunde mit einer Methode seines Landes. Die Zahlung erscheint auf der Seite von dLocal Go als Order # und Warenkorb-Nummer. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach dem Bezahlen kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn dLocal Go bestätigt: durch die signierte Benachrichtigung oder durch eine serverseitige Anfrage an die API von dLocal Go, wenn der Kunde zurückkehrt. Dann wird die Bestellung angelegt, und der Kunde sieht die Standard-Bestellbestätigungsseite mit Your payment with dLocal Go has been received. Wurde die Bestellung in Wartestellung gesetzt, zeigt die Seite Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. Hat dLocal Go die Zahlung noch nicht bestätigt (zum Beispiel ein noch nicht bezahlter Bargeld-Gutschein, oder dLocal Go war nicht erreichbar), bittet eine Seite Payment confirmation den Kunden, nicht erneut zu zahlen, und bietet Check again und Back to checkout an. Die Bestellung wird angelegt, sobald dLocal Go die Zahlung bestätigt.

Verlässt der Kunde die Seite von dLocal Go ohne zu zahlen, kehrt er zur Kasse 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. Der Warenkorb bleibt erhalten. Jeder neue Versuch erstellt eine neue Zahlung bei dLocal Go; ein älterer Zahlungslink desselben Warenkorbs kann weiterhin bezahlt werden und erstellt dann die Bestellung.

Kann dLocal Go die Zahlung nicht starten, bleibt der Kunde in der Kasse mit einer kurzen Meldung, zum Beispiel dLocal could not start the payment: gefolgt vom Grund, den dLocal angibt. Das passiert auch, wenn das Land des Kunden und die Warenkorbwährung in Ihrem dLocal-Go-Konto nicht freigeschaltet sind. Lehnt dLocal Go Ihre Zugangsdaten ab, sieht der Kunde This payment method is temporarily unavailable. Please choose another payment method or contact us. Der technische Grund wird im Protokoll festgehalten.

Die Benachrichtigungen funktionieren auch, während der Shop im Wartungsmodus ist, und werden nicht von der Länderbeschränkung Ihres Shops blockiert.

Das Modul nimmt nur Einmalzahlungen auf der Seite von dLocal Go an. Es gibt kein Kartenformular auf Ihrer Website, keine gespeicherten Karten, keine Abonnements und keine getrennte Autorisierung und Erfassung.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Der Kunde wurde zu dLocal Go weitergeleitet und hat noch nicht bezahlt, oder die Zahlung ist bei dLocal Go noch ausstehend. Es existiert nur der Warenkorb.

Payment accepted or Delivered: Die Zahlung wurde bestätigt. Die Bestellung steht auf „Zahlung akzeptiert“ oder bei aktivem Auto-complete orders auf „Zugestellt“. Die Zahlung wird mit der dLocal-Zahlungs-ID als Transaktions-ID verbucht, und eine Notiz zeigt die Umgebung und die Zahlungs-ID.

dLocal payment on hold: dLocal Go hat einen anderen Betrag oder eine andere Währung gemeldet als den Warenkorbbetrag (zum Beispiel wurde der Warenkorb in einem anderen Tab geändert, nachdem die Zahlung begonnen hatte), oder die Zahlung kam erst, nachdem die Bestellung storniert worden war. Die Notiz erklärt es. Vergleichen Sie mit dem dLocal-Go-Dashboard und bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung.

Refunded: Die Zahlung wurde über das Modul vollständig erstattet.

Eine abgelehnte, abgelaufene oder abgebrochene Zahlung ändert nie eine bestehende Bestellung. Trifft eine zweite Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, die doppelte Zahlung im dLocal-Go-Dashboard zu erstatten.

Zahlungsblock von dLocal Go

Die Bestellseite zeigt einen Block dLocal Go payment mit der dLocal-Zahlungs-ID, der Umgebung (mit einem Sandbox-Kennzeichen für Testzahlungen), dem Zahlungsstatus, dem von dLocal Go berechneten Betrag und dem erstatteten Betrag, dem Erstattungsformular, dem Erstattungsverlauf und den dLocal Go notes der Bestellung.

Erstattungen

Im Block dLocal Go payment geben Sie den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken auf Refund via dLocal Go. Bestätigen Sie die Frage Refund this amount through dLocal Go? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; Zugriff auf die Modulseiten ist nicht nötig. Erstattungen erfolgen in dem Betrag und der Währung, die dLocal Go berechnet hat. Nach einer Abweichung von Betrag oder Währung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich gezahlt hat, nicht bis zur Bestellsumme. Die Erstattung wird an die Umgebung der Zahlung gesendet, mit deren Zugangsdaten. Lehnt dLocal Go die Erstattung ab, zeigt der Block den Fehler, und es wird keine Erstattung verbucht. Eine angenommene Erstattung wird dem Erstattungsverlauf und den Notizen mit Erstattungs-ID, Status und Grund hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht.

Anschließend meldet dLocal Go den endgültigen Erstattungsstatus über die Erstattungsbenachrichtigung, und er wird den Notizen hinzugefügt. Lehnt oder storniert dLocal Go später eine Erstattung, die es angenommen hatte, warnt die Notiz, dass das Geld nicht an den Kunden zurückgegangen ist. Erstatten Sie dem Kunden erneut oder auf anderem Weg.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden über dLocal Go kein Geld zurück. Erstattungen, die im dLocal-Go-Dashboard vorgenommen werden, werden in PrestaShop nicht als Erstattungen erfasst und erzeugen meist keine Notiz. Aktualisieren Sie die Bestellung bei Bedarf manuell.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox dLocal Payment ist der erste Block auf Modules > Module Manager > VibeFox dLocal Payment > 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-dlocal 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 Haupt-Shops, 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 dLocal Go 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 Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht in der Kasse testen. Ein Hinweis erscheint unter Modules > Module Manager auf dem Reiter 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 automatisch erneut geprüft, während Sie im Back Office arbeiten: 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

dLocal Go erscheint nicht in der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und API-Schlüssel und API-Secret der gewählten Environment eingetragen sind. Die Einstellungsseite zeigt eine Warnung, wenn sie fehlen. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe freigegeben ist.

Die Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: dLocal Go konnte die Benachrichtigungs-URL nicht erreichen (Firewall, Basisauthentifizierung, keine öffentliche Adresse), und der Kunde ist nicht in den Shop zurückgekehrt. Aktivieren Sie Debug log, sehen Sie im Feld Log nach und prüfen Sie die Zahlung im dLocal-Go-Dashboard. Sobald eine Benachrichtigung eintrifft oder der Kunde Check again öffnet, wird die Bestellung angelegt.

Die Benachrichtigung antwortet Missing signature oder Invalid signature: API-Schlüssel und Secret in den Einstellungen gehören nicht zu dem Konto, das die Benachrichtigung gesendet hat. Benachrichtigungen werden mit den Zugangsdaten der Umgebung der Zahlung geprüft; Zahlungen, die vor einem Wechsel der Environment begonnen wurden, werden daher weiterhin bestätigt, solange die Zugangsdaten ihrer Umgebung in den Einstellungen bleiben.

Die Benachrichtigung antwortet Gateway not configured: Die Zugangsdaten der Umgebung der Zahlung fehlen. Tragen Sie sie ein; dLocal Go wiederholt die Benachrichtigung.

Die Benachrichtigung antwortet API verification failed: Die API von dLocal Go konnte nicht erreicht werden, um die Zahlung zu lesen. dLocal Go wiederholt die Benachrichtigung.

Die Benachrichtigung antwortet Temporarily unavailable: Die Bestellung wurde gerade von einer anderen Anfrage bestätigt, oder die Bestellung konnte nicht angelegt werden (zum Beispiel ist das Modul deaktiviert). dLocal Go wiederholt die Benachrichtigung. Der Grund steht im Protokoll.

Die Benachrichtigung antwortet Order not found: Die Zahlung gehört nicht zu einem Warenkorb dieses Shops, zum Beispiel weil sie von einer anderen Website mit demselben dLocal-Go-Konto erstellt wurde.

Der Kunde sieht This payment method is temporarily unavailable: dLocal Go hat API-Schlüssel oder Secret abgelehnt. Prüfen Sie die Zugangsdaten der gewählten Umgebung.

Der Kunde sieht Payment gateway is not properly configured: Die Zugangsdaten der gewählten Umgebung fehlen.

Bestellung ist nach der Zahlung dLocal payment on hold: Lesen Sie die Notizen im Block dLocal Go payment. Der bezahlte Betrag oder die Währung wich vom Warenkorb ab, oder die Zahlung kam, nachdem die Bestellung storniert wurde. Bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung.

Erstattung schlägt mit einer Meldung über fehlende Zugangsdaten fehl: Die Zahlung wurde in der anderen Umgebung getätigt, und deren Zugangsdaten sind nicht eingetragen. Tragen Sie sie ein und versuchen Sie es erneut.

Für Entwickler listet die Dokumentation des Moduls die Hooks actionWcpDlocalPaymentData und actionWcpDlocalCurrencyDecimals auf.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox dLocal Payment und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall aktiviert, werden die Gateway-Einstellungen und das Protokoll entfernt. Ist es deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die dLocal-Zahlungen und -Erstattungen der Bestellungen sowie der Bestellstatus dLocal payment on hold bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation weiter erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

dLocal ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit dLocal verbunden und wird von dLocal nicht unterstützt oder empfohlen.