VibeFox PagSeguro 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: brasilianische Real (BRL). Die Zahlungsart wird an der Kasse ausgeblendet, wenn die Währung des Shops (bzw. auf der Seite „Pay for order“ die Währung der Bestellung) nicht BRL ist.

HTTPS: Ihre Website muss über HTTPS aus dem Internet erreichbar sein, damit PagBank Zahlungsbenachrichtigungen zustellen kann.

PagBank-Konto: ein Produktionstoken für echte Zahlungen und ein Sandbox-Token für Tests. Produktion: Melden Sie sich in Ihrem PagBank-Konto an, öffnen Sie Venda online > Integrações und klicken Sie auf Gerar token; PagBank sendet den Token per E-Mail. Sandbox: Erstellen Sie im Entwicklerportal von PagBank ein Sandbox-Konto und kopieren Sie dessen Token. Sandbox- und Produktionstoken funktionieren nur in ihrer jeweiligen Umgebung.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert für eine 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. Alternativ können Sie den Ordner wcp_pagseguro_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage, oder klicken Sie auf der Plugins-Seite 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. Geben Sie den Sandbox-Token und, für echte Zahlungen, den Produktionstoken ein.

6. Aktivieren Sie Enable / Disable und speichern Sie. Führen Sie Testzahlungen mit aktiviertem Sandbox Mode durch und schalten Sie ihn danach aus, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > PagSeguro / PagBank. Unter dem Titel zeigt die Seite den aktuellen Modus an: SANDBOX MODE (Zahlungen werden in der PagBank-Sandbox erstellt, ohne echte Abbuchungen) oder LIVE (Zahlungen werden mit dem Produktionstoken erstellt). Sie warnt, wenn der Token des aktuellen Modus fehlt (die Zahlungsart wird dann an der Kasse ausgeblendet), und wenn die Shop-Währung nicht BRL ist. In der Liste der Zahlungsarten ist PagBank als einrichtungsbedürftig markiert, bis der Token des aktuellen Modus eingegeben ist; solange der Sandbox-Modus aktiv ist, wird ein Testmodus-Hinweis angezeigt.

Allgemein

Enable / Disable: Enable PagSeguro/PagBank payments schaltet die Zahlungsart ein oder aus. Standard: aus.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: PagSeguro / PagBank.

Description: der Text unter der Zahlungsart an der Kasse. Standard: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

PagBank-Konto

Dieser Abschnitt erklärt, wo Sie die Token erhalten, und verlinkt auf Ihr PagBank-Konto sowie auf die PagBank-Seite zu Tokens.

Sandbox Mode: Enable sandbox/test mode (no real charges). Neue Zahlungen gehen mit dem Sandbox-Token an die PagBank-Sandbox, und an der Kasse erscheint ein Hinweis SANDBOX MODE. Statusabfragen und Erstattungen einer Bestellung verwenden immer die Umgebung und den Token, mit denen ihre Zahlung erstellt wurde. Standard: an.

Sandbox token: der PagBank-Sandbox-Token. Wird verwendet, solange der Sandbox-Modus aktiv ist.

Production token: der PagBank-Produktionstoken. Wird verwendet, wenn der Sandbox-Modus aus ist. Halten Sie ihn geheim.

Der einzelne Token der Version 1.0 wird automatisch übernommen: War der Sandbox-Modus aktiv, wird er zum Sandbox-Token, andernfalls bleibt er Produktionstoken.

Zahlungsbenachrichtigungen

Jede Zahlung teilt PagBank mit, wohin Statusänderungen gemeldet werden, daher ist in PagBank nichts einzurichten. Der Abschnitt zeigt die Benachrichtigungs-URL. Sie sieht so aus: https://your-site/wc-api/webhook_wc_pagseguro/. Die Adresse muss über HTTPS aus dem Internet erreichbar sein.

Benachrichtigungen mit einem x-authenticity-token-Header werden mit dem Token der Umgebung der Bestellung geprüft; eine ungültige Signatur wird abgelehnt. Dem Inhalt der Benachrichtigung selbst wird nie vertraut: Das Plugin liest Checkout und PagBank-Bestellung immer über die PagBank-API (Status, Betrag, Währung), bevor sich die Bestellung ändert.

Erweitert

Debug log: Log API requests and notifications schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_pagseguro_gateway. Fehler werden immer protokolliert. Protokolle enthalten keine Token und keine Kundendaten. Standard: aus.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig PagSeguro / PagBank) und gibt die Bestellung auf. Das Plugin erstellt einen PagBank-Checkout über den genauen Bestellbetrag in BRL als einen Artikel, Order # mit der Bestellnummer und dem Namen Ihres Shops, und leitet den Kunden auf die Zahlungsseite von PagBank weiter. Name und E-Mail-Adresse des Kunden, CPF oder CNPJ aus den Feldern des Plugins Brazilian Market on WooCommerce sowie eine brasilianische Telefonnummer werden vorausgefüllt, wenn der Shop sie hat; der Kunde kann sie auf der PagBank-Seite ergänzen oder korrigieren. Der Kunde bezahlt mit den in Ihrem PagBank-Konto aktivierten Zahlungsarten, zum Beispiel Kreditkarte, PIX oder Boleto.

Die Zahlungsseite läuft 5 Minuten bevor der Timer Hold stock von WooCommerce eine unbezahlte Bestellung storniert (mindestens 10 Minuten) oder nach 120 Minuten ab, wenn kein Lagerbestand reserviert wird.

Nach der Zahlung kehrt der Kunde in den Shop zurück. Die Rückkehr wird genauso geprüft wie eine Benachrichtigung: Das Plugin liest die Zahlung über die PagBank-API, und eine Rückkehr allein markiert eine Bestellung nie als bezahlt. Eine bezahlte Bestellung oder eine Zahlung, die noch aussteht (Boleto, PIX, Prüfung), führt zur Bestellbestätigungsseite; die Bestellung wird durch die Benachrichtigung bestätigt, falls PagBank sie noch nicht gemeldet hat.

Wurde die Zahlung nicht abgeschlossen, kehrt der Kunde zur Seite Pay for order zurück, mit The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. oder The payment was declined by PagBank. Please try again with another card or payment method. Wurde die Zahlung abgebrochen und damit auch die Bestellung, gelangt der Kunde mit The PagBank payment was cancelled, so the order was cancelled. in den Warenkorb.

Zahlt der Kunde erneut, wird der offene PagBank-Checkout wiederverwendet, wenn Betrag und Umgebung gleich sind und er nicht innerhalb von 10 Minuten abläuft. Andernfalls wird der vorherige Checkout deaktiviert, sodass er nicht mehr bezahlt werden kann. Eine zuvor auf der alten Seite geleistete Zahlung zählt weiterhin für die Bestellung.

Kann PagBank die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. oder Could not connect to PagBank. Please try again in a moment. Der Grund von PagBank wird in den Bestellnotizen ergänzt.

Die Zahlungsart funktioniert in 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 hat kein eigenes Kartenformular, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen, keine Split-Zahlungen und keine Marktplätze. Zahlungsarten und Ratenzahlungen sind die in Ihrem PagBank-Konto konfigurierten.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: der Kunde wurde zu PagBank weitergeleitet und hat noch nicht bezahlt. Eine Notiz zeigt die PagBank-Checkout-ID und die Umgebung. Läuft die Zahlungsseite ohne Zahlung ab, weist eine Notiz darauf hin, und der Status ändert sich nicht.

Processing: die Zahlung wurde bestätigt. Dies ist der Standardstatus von WooCommerce nach der Zahlung; Bestellungen, die nur virtuelle herunterladbare Produkte enthalten, werden auf Abgeschlossen gesetzt. Die Bestellnotiz zeigt den Betrag, die Zahlungsart und die PagBank-Belastungs-ID, die auch die Transaktions-ID der Bestellung ist.

On hold: ein Boleto oder PIX wurde erzeugt und wartet auf Zahlung; die Zahlung wird geprüft; eine Kartenzahlung wurde autorisiert, aber nicht erfasst (erfassen Sie sie in PagBank); der bezahlte Betrag oder die Währung stimmt nicht mit der Bestellung überein; oder eine Zahlung ist eingegangen, nachdem WooCommerce die unbezahlte Bestellung storniert hatte (prüfen Sie den Lagerbestand und schließen Sie dann die Bestellung ab oder erstatten Sie die Zahlung in PagBank). Die Bestellnotiz erklärt es.

Failed: die Zahlung wurde abgelehnt. Der Kunde kann über die Seite Pay for order erneut bezahlen.

Cancelled: die Zahlung wurde storniert, zum Beispiel ein abgelaufenes Boleto oder PIX.

Refunded: die Zahlung wurde im PagBank-Dashboard vollständig erstattet.

Jeder PagBank-Status wird nur einmal angewendet; wiederholte Benachrichtigungen oder Rückkehren erzeugen daher keine weiteren Notizen, E-Mails oder Lagerabbuchungen. Geht eine zweite Zahlung für eine bereits bezahlte Bestellung ein, weist eine Notiz Sie an, sie in PagBank zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via PagSeguro / PagBank (der Button zeigt den Titel Ihrer Zahlungsart). Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird in der Umgebung und mit dem Token gesendet, mit denen die Zahlung erfolgte. Eine Erstattung wird nur verbucht, wenn PagBank sie bestätigt; andernfalls zeigt WooCommerce den Fehler an, zum Beispiel PagBank refund failed: ... oder PagBank did not confirm the refund, und es wird nichts verbucht. Erstattungen von Boleto-Zahlungen und Teilerstattungen von PIX folgen den Regeln von PagBank. Eine erfolgreiche Erstattung wird mit der Belastungs-ID in den Bestellnotizen vermerkt.

Im PagBank-Dashboard vorgenommene Erstattungen werden nicht als WooCommerce-Erstattungspositionen übernommen. Eine vollständige Erstattung setzt die Bestellung auf Erstattet; eine Teilerstattung fügt eine Notiz mit dem erstatteten Betrag hinzu, und Sie können die Erstattung manuell in der Bestellung erfassen.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > PagSeguro / PagBank. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, etwa 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 für eine 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 PagBank 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), sodass Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Ein Hinweis erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: bereits gestartete 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 im Hintergrund automatisch erneut geprüft.

Fehlerbehebung

PagBank erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, der Token des aktuellen Modus gesetzt ist (Sandbox token im Sandbox-Modus, Production token im Live-Modus) und die Shop-Währung BRL ist. Die Einstellungsseite zeigt in jedem dieser Fälle eine Warnung an.

Die Zahlung ist erfolgt, aber die Bestellung bleibt auf „Ausstehende Zahlung“: PagBank hat die Zahlung noch nicht gemeldet, und der Kunde ist nicht in den Shop zurückgekehrt. Die Bestellung wird aktualisiert, sobald die Benachrichtigung eintrifft. Prüfen Sie, ob Ihre Website über HTTPS aus dem Internet erreichbar ist, und sehen Sie in WooCommerce > Status > Logs, Quelle wcp_pagseguro_gateway, nach.

Die Benachrichtigung antwortet Invalid signature: der x-authenticity-token stimmt nicht mit dem Token der Umgebung überein, in der die Bestellung bezahlt wurde. Prüfen Sie, ob der richtige Token in den Einstellungen steht.

Die Benachrichtigung antwortet Verification failed, retry later: die PagBank-API war nicht erreichbar, der Token der Umgebung der Bestellung fehlt, oder die Bestellung wurde im selben Moment von einer anderen Anfrage aktualisiert. PagBank wiederholt die Benachrichtigung.

Die Benachrichtigung antwortet Order not found: die Bestellung existiert in diesem Shop nicht oder wurde mit einer anderen Zahlungsart bezahlt. Es wird nichts geändert.

Der Kunde sieht This order is already being processed: eine Benachrichtigung oder die Rückkehr des Kunden aktualisierte die Bestellung im selben Moment. Der Kunde kann es gleich noch einmal versuchen.

Der Kunde sieht PagBank payments are temporarily unavailable: der Token des aktuellen Modus fehlt oder wurde von PagBank abgelehnt.

Der Kunde sieht PagSeguro/PagBank only accepts payments in Brazilian Real (BRL): die Bestellung ist in einer anderen Währung.

Bestellung steht auf On hold mit der Notiz Amount/currency does not match: PagBank hat eine Zahlung gemeldet, deren Betrag oder Währung vom Bestellbetrag abweicht, zum Beispiel weil die Bestellung nach der Erstellung der Zahlungsseite geändert wurde. Vergleichen Sie die Beträge in PagBank und schließen Sie die Bestellung ab oder erstatten Sie sie manuell.

Erstattung schlägt mit einer Meldung zum Token fehl: die Zahlung erfolgte im Sandbox- oder im Produktionsmodus, und der Token dieser Umgebung fehlt oder wurde abgelehnt. Geben Sie den richtigen Token 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. Kann der Lizenzserver nicht erreicht werden, 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 Einstellungen der Zahlungsart, die übrigen Optionen des Plugins und seine 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 PagBank-Daten.

PagSeguro und PagBank sind Marken ihrer jeweiligen Inhaber. Dieses Plugin ist nicht mit PagSeguro oder PagBank verbunden und wird von ihnen nicht unterstützt.