VibeFox PagSeguro for OpenCart — Hilfe

Anforderungen

OpenCart: 3.0.x (getestet mit 3.0.5.0) oder 4.0.2 und neuer (getestet mit 4.1.0.3).

PHP: 8.0 oder neuer.

Currency: Brasilianischer Real (BRL). Der Shop muss die Währung BRL haben (System > Localisation > Currencies), und die Zahlungsart wird nur angezeigt, wenn der Kunde in BRL zur Kasse geht.

Reachable site: Ihr Shop muss über das Internet erreichbar sein, damit PagBank Zahlungsbenachrichtigungen zustellen kann.

PagBank account: ein Produktions-Token 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 das Token per E-Mail. Sandbox: Kopieren Sie das Token Ihres Sandbox-Kontos im PagBank-Entwicklerportal. Sandbox- und Produktions-Token funktionieren nur in ihrer eigenen Umgebung.

VibeFox license key: erworben auf vibefox.net. Ein Schlüssel funktioniert für eine Domain.

Installation

Der Download ist eine ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das Paket für OpenCart 3 wcp_pagseguro_gateway-oc3-(version).ocmod.zip und das Paket für OpenCart 4 wcp_pagseguro_gateway.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen gleich.

OpenCart 3

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_pagseguro_gateway-oc3-(version).ocmod.zip. Die Erweiterung enthält keine OCMOD-Modifikationen, daher muss Extensions > Modifications nicht aktualisiert werden. Statt des Installers können Sie den Inhalt des Ordners upload dieses Pakets auch in das Stammverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments. Suchen Sie VibeFox PagSeguro Gateway und klicken Sie auf Install (die grüne +-Schaltfläche). Ihr Admin-Benutzer benötigt das Recht, die Liste der Zahlungserweiterungen zu ändern.

3. Klicken Sie auf Edit (die Stift-Schaltfläche), um die Einstellungsseite zu öffnen. Fügen Sie Ihren VibeFox-Lizenzschlüssel in das Feld License key im Lizenzbereich oben auf der Seite ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie das Sandbox-Token und, für echte Zahlungen, das Produktions-Token ein. In PagBank muss nichts eingerichtet werden: Die Benachrichtigungs-URL wird bei jeder Zahlung übermittelt.

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

OpenCart 4

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_pagseguro_gateway.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Code der Erweiterung dem Dateinamen, und ein umbenanntes Paket funktioniert nicht.

2. Das Paket erscheint auf derselben Seite in der Liste der installierten Erweiterungen. Klicken Sie daneben auf Install (die grüne +-Schaltfläche).

3. Gehen Sie zu Extensions > Extensions und wählen Sie den Typ Payments. Suchen Sie VibeFox PagSeguro Gateway, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Stift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel und die Token ein und testen Sie die Zahlungen wie in den Schritten 3 bis 5 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich. Nur die Benachrichtigungs-URL ist anders (siehe Notification URL); sie wird ebenfalls bei jeder Zahlung an PagBank übermittelt.

Eine neue Installation startet mit deaktivierter Zahlungsart und aktiviertem Sandbox-Modus.

Konfiguration

Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Payments > VibeFox PagSeguro Gateway > Edit. Die Abschnitte sind links aufgelistet; die Schaltfläche Save unter der Liste speichert die gesamte Seite. Über den Einstellungen zeigt die Seite den aktuellen Modus an: SANDBOX MODE (Zahlungen werden in der PagBank-Sandbox angelegt, es erfolgen keine echten Abbuchungen) oder LIVE (Zahlungen werden mit dem Produktions-Token angelegt). Sie warnt, wenn das Token des aktuellen Modus fehlt (die Zahlungsart wird dann an der Kasse ausgeblendet), und wenn die Standardwährung des Shops nicht BRL ist. Ohne das Recht, die Erweiterung zu ändern, zeigt die Seite die Einstellungen an, kann sie aber nicht speichern.

Beim Speichern darf Title nicht leer sein (bis zu 128 Zeichen), Sort Order muss eine ganze Zahl sein (negative Zahlen sind erlaubt), Total muss eine Zahl von 0 oder mehr sein, und die Geo-Zone sowie die Bestellstatus müssen vorhanden sein. Ist ein Wert falsch, nennt eine Fehlermeldung ihn, und es wird nichts gespeichert.

PagSeguro / PagBank

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. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: PagSeguro / PagBank. Pflichtfeld, bis zu 128 Zeichen.

Description: der Text, der Kunden im Schritt Confirm Order über der Bestätigungsschaltfläche angezeigt wird. Standard: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

Sort Order: die Position von PagBank unter den Zahlungsarten an der Kasse. Lassen Sie das Feld leer oder geben Sie eine ganze Zahl ein.

Geo Zone: bietet PagBank nur für Rechnungsadressen in der gewählten Geo-Zone an. Standard: All zones. Geo-Zonen werden unter System > Localisation > Geo Zones eingerichtet. Wenn der Shop keine Rechnungsadresse abfragt, wird auf OpenCart 4 die Lieferadresse verwendet.

Total: der Warenkorbwert in der Standardwährung des Shops, den eine Bestellung erreichen muss, bevor PagBank angeboten wird. Lassen Sie das Feld leer, um PagBank bei jedem Betrag anzubieten.

PagBank-Konto

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

Sandbox Mode: Enable sandbox/test mode (no real charges). Neue Zahlungen gehen mit dem Sandbox-Token an die PagBank-Sandbox, und Kunden sehen im Schritt Confirm Order den Hinweis SANDBOX MODE — Using test environment. No real charges. Statusprüfungen und Erstattungen einer Bestellung verwenden immer die Umgebung und das Token, in denen ihre Zahlung erstellt wurde. Standard: an.

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

Production token: das PagBank-Produktions-Token (Bearer). Wird verwendet, wenn der Sandbox-Modus aus ist. Bewahren Sie es geheim auf.

Gespeicherte Token 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. Um ein gespeichertes Token zu entfernen, setzen Sie unter dem Feld den Haken bei Clear the saved token on save und klicken Sie auf Save.

Zahlungsbenachrichtigungen

Notification URL: Bei jeder Zahlung wird PagBank angewiesen, seine Kauf- und Zahlungsbenachrichtigungen an diese URL zu senden, daher muss in PagBank nichts konfiguriert werden. In OpenCart 3 sieht sie etwa so aus: https://your-store/index.php?route=extension/payment/wcp_pagseguro_gateway/webhook, in OpenCart 4 so: https://your-store/index.php?route=extension/wcp_pagseguro_gateway/payment/wcp_pagseguro_gateway.webhook. Sie wird aus der Shop-Adresse Ihrer OpenCart-Installation gebildet. Die URL muss über das Internet erreichbar sein.

Benachrichtigungen mit einem x-authenticity-token-Header werden mit dem Token der Umgebung geprüft, in der die Zahlung erstellt wurde; eine ungültige Signatur wird abgelehnt. Dem Inhalt der Benachrichtigung selbst wird nie vertraut: Die Erweiterung liest den Kauf und die PagBank-Bestellung (Status, Betrag, Währung) immer über die PagBank-API, bevor sich die Bestellung ändert. Ohne Benachrichtigungen erhält die Bestellung ihren Status, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Bestellungen

OpenCart legt die Bestellung im Schritt Confirm Order ohne Status an (fehlende Bestellung). Die Bestellung erhält erst einen Status, nachdem PagBank die Zahlung per Benachrichtigung oder bei der Rückkehr des Kunden gemeldet hat; die Zahlung wird immer bei PagBank abgefragt. Jedes der folgenden Felder listet Ihre OpenCart-Bestellstatus auf.

Order Status After Payment: der Status nach einer geprüften PagBank-Zahlung. Standard: In Bearbeitung.

Awaiting PagBank Payment Status: ein Boleto oder PIX wurde ausgestellt oder die Zahlung wird geprüft (WAITING / IN_ANALYSIS); PagBank bestätigt das Geld später. Standard: Ausstehend.

PagBank Payment On Hold Status: die Zahlung benötigt Ihre Prüfung (siehe Bestellstatus). Standard: Ausstehend, weil OpenCart keinen Status „On hold“ hat. Sie können unter System > Localisation > Order Statuses einen eigenen Status anlegen und hier auswählen.

Payment Declined Status: die Zahlung einer wartenden Bestellung wurde abgelehnt. Meldet PagBank sie später als bezahlt, erhält die Bestellung den Status nach der Zahlung. Standard: Fehlgeschlagen.

Payment Cancelled Status: die Zahlung einer wartenden Bestellung wurde in PagBank storniert. Eine Zahlung, die für eine Bestellung in diesem Status eingeht, setzt sie in den Prüfstatus. Standard: Storniert.

Refunded Status: wird gesetzt, nachdem die Zahlung auf der Bestellseite oder im PagBank-Dashboard vollständig erstattet wurde. Standard: Erstattet.

Erweitert

Debug log: schreibt API-Anfragen und Benachrichtigungen in wc_psg_debug.log.php im Logs-Ordner von OpenCart (storage/logs). Die Datei kann nicht über den Webbrowser geöffnet werden. Protokolle enthalten keine Token und keine Kundendaten. Fehler und Warnungen werden immer 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 eingeschaltet, entfernt das Deinstallieren der Erweiterung die Einstellungen des Gateways und das Protokoll. Bestellungen und deren PagBank-Referenzen (für Erstattungen erforderlich) bleiben immer erhalten. Standard: aus.

Import / Export

Export: Download JSON speichert die Einstellungen als JSON-Datei. Token werden nicht exportiert.

Import: Fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen. Gespeicherte Token bleiben erhalten.

Kasse

Im Schritt Payment Method wählt der Kunde die Zahlungsart (standardmäßig PagSeguro / PagBank). Im Schritt Confirm Order sieht der Kunde Ihre Beschreibung und den Hinweis You will be redirected to the PagBank payment page (credit card, PIX, boleto) and returned to the store. OpenCart legt die Bestellung in diesem Schritt an, noch ohne Status. Auf OpenCart 4 wählt der Kunde die Zahlungsart mit der Schaltfläche Choose des Blocks Zahlungsart im Fenster Payment method options und klickt unten auf der Kassenseite auf Confirm Order. Wenn der Kunde auf Confirm Order klickt, erstellt die Erweiterung eine PagBank-Zahlung über den Bestellbetrag in BRL als einen Artikel, Order # mit der Bestellnummer und dem Namen Ihres Shops (Gutscheine, Versand und Steuern sind im Betrag enthalten), und leitet den Kunden zur PagBank-Zahlungsseite weiter. Name und E-Mail-Adresse des Kunden werden übergeben, außerdem die CPF oder CNPJ (11 oder 14 Ziffern) aus einem benutzerdefinierten Feld des Kunden oder der Zahlungsadresse, dessen Name CPF oder CNPJ enthält, sowie eine brasilianische Telefonnummer. OpenCart hat standardmäßig kein CPF-Feld; Sie können eines unter Customers > Custom Fields hinzufügen. Auf OpenCart 4 werden, wenn der Shop keine Zahlungsadresse abfragt, die Lieferadresse und ihre benutzerdefinierten Felder verwendet. Der Kunde kann diese Angaben auf der PagBank-Seite ergänzen oder korrigieren und bezahlt mit den in Ihrem PagBank-Konto aktivierten Methoden. Die Zahlungsseite läuft nach 120 Minuten ab.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn PagBank die Zahlung bestätigt: Die Erweiterung liest die Zahlung über die PagBank-API, sobald die Benachrichtigung eintrifft oder der Kunde zurückkehrt, und der belastete Betrag (ohne Ratenzinsen von PagBank) sowie die Währung müssen mit der Bestellung übereinstimmen. Die Bestellung erhält dann ihren Status auf die übliche OpenCart-Weise, mit den üblichen Bestell-E-Mails und der Bestandsaktualisierung, und der Kunde sieht die Erfolgsseite der OpenCart-Bestellung. Bei einem erstellten Boleto oder PIX oder bei einer Zahlung in Prüfung zeigt die Seite außerdem Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. Bei einer Bestellung im Prüfstatus wird We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. angezeigt. Hat PagBank die Zahlung bei der Rückkehr des Kunden noch nicht bestätigt, zeigt eine Seite Payment confirmation denselben Text mit den Schaltflächen Check again und Back to checkout.

Wurde die Zahlung nicht abgeschlossen, kehrt der Kunde zur Kasse zurück mit The PagBank payment was not completed. You can try again or choose another payment method., The PagBank payment page has expired. You can try again or choose another payment method. oder The payment was declined by PagBank. Please try again with another card or payment method. Der Warenkorb bleibt erhalten. Auf OpenCart 4 werden diese Meldungen oberhalb der Kassenseite angezeigt. Wurde eine Bestellung, die auf ein Boleto oder PIX wartete, storniert, sieht der Kunde The PagBank payment was cancelled, so the order was cancelled. Ist der Warenkorb bereits leer (zum Beispiel, weil die Bestellung die Erfolgsseite erreicht hatte, bevor das Boleto oder PIX abgelaufen ist), gibt es an der Kasse nichts zu bezahlen: Stattdessen zeigt eine Seite Payment confirmation die Meldung; bei einer unbezahlten Bestellung lautet sie The PagBank payment of order #N was not completed (declined, canceled or expired), so the order will not be shipped. To buy these items, please place a new order., mit einer Schaltfläche Continue.

OpenCart 3 legt jedes Mal eine neue Bestellung an, wenn der Schritt Confirm Order angezeigt wird. OpenCart 4 behält eine Bestellung für die Kasse bei und aktualisiert sie, daher bezahlt der Kunde nach einer abgelehnten Karte, einer nicht abgeschlossenen Zahlung oder einer abgelaufenen Seite dieselbe Bestellung mit einer neuen PagBank-Zahlung. Vor einer neuen Zahlung prüft die Erweiterung die früheren PagBank-Zahlungen derselben Bestellung und desselben Warenkorbs: Wurde auf einer früheren Seite bezahlt, wird diese Zahlung übernommen, statt eine neue zu erstellen; ist eine andere Bestellung des Warenkorbs bezahlt oder wartet sie, gelangt der Kunde zur Erfolgsseite. Die offene Zahlung der Bestellung wird wiederverwendet, wenn Betrag und Umgebung gleich sind und sie nicht innerhalb von 10 Minuten abläuft; andernfalls wird sie deaktiviert, sodass sie nicht mehr bezahlt werden kann. Trifft trotzdem eine zweite Zahlung ein, erscheint ein Hinweis, dass Sie sie erstatten sollten.

Wurde die Bestellung bezahlt und danach von Ihnen geschlossen (zum Beispiel storniert oder erstattet), wird dem Kunden, der von PagBank zurückkommt, nicht die Erfolgsseite angezeigt: Der Kunde landet wieder an der Kasse mit Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order. oder sieht diese Meldung auf einer Seite Payment confirmation, wenn der Warenkorb bereits leer ist.

OpenCart 4 behält die Bestellung in der Kasse, bis die Erfolgsseite angezeigt wird. Wurde diese Bestellung inzwischen geschlossen, schickt Confirm Order den Kunden mit der passenden Meldung zurück zur Kasse: die Meldungen zu einem stornierten Boleto oder PIX und zu einer abgelehnten Zahlung von oben, Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. oder, bei einer bezahlten und danach von Ihnen geschlossenen Bestellung, die Meldung über die vom Shop geschlossene Bestellung. Das nächste Confirm Order bezahlt eine neue Bestellung. Ist diese Bestellung bereits bezahlt oder wartet sie und enthält der Warenkorb jetzt andere Produkte oder Mengen, lautet die Meldung Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it.

Kann PagBank die Zahlung nicht starten, bleibt der Kunde im Schritt Confirm Order mit einer kurzen 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 technische Grund wird im Protokoll festgehalten.

Benachrichtigungen funktionieren auch, wenn der Shop im Wartungsmodus ist: OpenCart 3 lässt Anfragen von Zahlungserweiterungen durch, und auf OpenCart 4 fügt die Erweiterung eine Startup-Aktion hinzu, die die Benachrichtigungen und die Rückkehr des Kunden von PagBank durchlässt.

Die Erweiterung hat kein Kartenformular im Shop, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen und keine Split-Zahlungen oder Marktplätze. Zahlungsarten und Ratenzahlungen sind die, die in Ihrem PagBank-Konto eingerichtet sind.

Bestellungen und Erstattungen

Bestellstatus

No status (missing order): Der Kunde wurde zu PagBank weitergeleitet und hat nicht bezahlt, die Karte wurde abgelehnt oder die Zahlungsseite ist abgelaufen; der Kunde kann erneut bezahlen. Unter Sales > Orders werden solche Bestellungen nur mit dem Filter Order Status auf Missing Orders angezeigt.

Auf OpenCart 4 kann eine unbezahlte Bestellung der Kasse den Status Voided erhalten, den OpenCart 4 setzt, wenn der Kunde zum Schritt Confirm Order zurückkehrt. Die Erweiterung behandelt eine solche Bestellung wie eine Bestellung ohne Status, und eine spätere Zahlung bestätigt sie trotzdem.

Order Status After Payment (default Processing): Die Zahlung wurde mit dem erwarteten Betrag und der erwarteten Währung bestätigt. Eine Notiz zeigt den Betrag, die Zahlungsart und die PagBank-Charge-ID.

Awaiting PagBank Payment Status (default Pending): Ein Boleto oder PIX wurde erstellt und wartet auf Zahlung, oder die Zahlung wird geprüft. Die Bestellung wechselt zu Order Status After Payment, sobald PagBank die Zahlung als bezahlt meldet.

PagBank Payment On Hold Status (default Pending): PagBank hat einen anderen Betrag oder eine andere Währung als bei der Bestellung gemeldet; eine Zahlung ist eingegangen, nachdem die Bestellung storniert worden war (Bestand prüfen, dann die Bestellung abschließen oder die Zahlung in PagBank erstatten); oder eine Kartenzahlung wurde autorisiert, aber nicht erfasst (in PagBank erfassen). Die Notiz erklärt es. Das tatsächlich erhaltene Geld wird für Erstattungen festgehalten.

Payment Declined Status (default Failed): Eine Zahlung, die wartete oder geprüft wurde, wurde abgelehnt.

Payment Cancelled Status (default Canceled): Eine Zahlung, die wartete, zum Beispiel ein abgelaufenes Boleto oder PIX, wurde storniert.

Refunded Status (default Refunded): Die Zahlung wurde vollständig erstattet, entweder über die Erweiterung oder im PagBank-Dashboard.

Jeder PagBank-Status wird nur einmal angewendet, sodass wiederholte Benachrichtigungen oder Rückkehrer keine Notizen oder Statusänderungen hinzufügen. Eine bezahlte Bestellung wird nie zurückgesetzt. Trifft eine zweite Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert, und eine Notiz bittet Sie, das Duplikat in PagBank zu erstatten. Notizen sind Einträge im History der Bestellung, die der Kunde nicht sieht.

Reiter VibeFox PagSeguro Gateway

Öffnen Sie unter Sales > Orders eine mit PagBank bezahlte Bestellung. Unten auf der Bestellseite, neben History und Additional, zeigt der Reiter VibeFox PagSeguro Gateway den PagBank checkout mit der Kennzeichnung Sandbox bei Sandbox-Zahlungen, die IDs PagBank order und Charge, die Payment method, den Status, die Beträge Paid / refunded, das Erstattungsformular, den Erstattungsverlauf und die PagBank notes der Bestellung. Der Reiter wird Benutzern angezeigt, die Zugriff auf die Erweiterung haben.

Erstattungen

Geben Sie im Reiter VibeFox PagSeguro Gateway den Amount ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Reason (optional), und klicken Sie auf Refund via PagBank. Bestätigen Sie die Abfrage Refund this amount through PagBank? This cannot be undone. Vollständige und Teilerstattungen werden unterstützt. Sie benötigen das Recht, die Erweiterung zu ändern (festgelegt unter System > Users > User Groups). Die Obergrenze ist der Betrag, den PagBank berechnet hat; nach einer Betragsabweichung können Sie daher bis zu dem Betrag erstatten, den der Kunde tatsächlich bezahlt hat, nicht bis zur Bestellsumme. Die Erstattung wird in der Umgebung und mit dem Token gesendet, mit denen die Zahlung erfolgte. Eine Erstattung wird nur erfasst, wenn PagBank sie bestätigt; andernfalls zeigt der Reiter den Fehler, zum Beispiel PagBank refund failed: ... oder PagBank did not confirm the refund, und nichts wird erfasst. Erstattungen von Boleto-Zahlungen und Teilerstattungen von PIX folgen den Regeln von PagBank. Eine erfolgreiche Erstattung wird mit der Charge-ID dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded Status, ohne den Kunden zu benachrichtigen und ohne Produkte in den Bestand zurückzubuchen, wie eine manuelle Statusänderung. Eine Teilerstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald PagBank die Zahlung als bezahlt gemeldet hat.

Produktrücksendungen unter Sales > Returns erstatten kein Geld über PagBank.

Erstattungen, die im PagBank-Dashboard vorgenommen werden, werden mit der nächsten Benachrichtigung oder Prüfung erkannt: Eine vollständige Erstattung setzt die Bestellung auf Refunded Status, eine Teilerstattung fügt eine Notiz mit dem erstatteten Betrag hinzu.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich License — VibeFox PagSeguro Gateway ist der erste Block unter Extensions > Extensions > Payments > VibeFox PagSeguro Gateway > Edit, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Bereich 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: opencart-payment-pagseguro und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit dem Recht „Modify“ für die Erweiterung können den Schlüssel ändern. Die Texte des Bereichs folgen der Admin-Sprache (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, nennt der Bereich 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 die Erweiterung mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert für eine Domain: die Shop-Adresse aus der OpenCart-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 PagBank Kunden an der Kasse nicht angezeigt. Wird eine Zahlung dennoch gestartet, sieht der Kunde This payment method is not available. Please choose another one. Ein Admin-Benutzer, der sich im selben Browser im Admin-Bereich angemeldet hat, sieht die Zahlungsart im Shop weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie die Erweiterung einrichten und testen können, bevor Sie einen Schlüssel kaufen. Auf OpenCart 4 steht diese Vorschau nicht zur Verfügung: Der Shop sieht die Anmeldung im Admin-Bereich nicht, daher ist die Zahlungsart ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint im Admin-Dashboard eine Erinnerung. Schließen Sie sie mit ×, um sie 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen: bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Admin-Dashboard oder die Seite Edit öffnen: 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 der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

PagBank does not appear at checkout: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, das Token des aktuellen Modus gesetzt ist (Sandbox token im Sandbox-Modus, Production token im Live-Modus) und der Kunde in BRL bezahlt. Die Einstellungsseite zeigt eine Warnung, wenn das Token fehlt oder die Shop-Währung nicht BRL ist. Prüfen Sie außerdem, ob die Zahlungsadresse in der gewählten Geo Zone liegt und ob die Bestellung den in den Einstellungen festgelegten Total erreicht.

The payment went through, but the order stays without a status: PagBank hat die Zahlung noch nicht gemeldet und der Kunde ist nicht in den Shop zurückgekehrt. Die Bestellung erhält ihren Status, sobald die Benachrichtigung eintrifft. Prüfen Sie, ob Ihr Shop unter der Notification URL über das Internet erreichbar ist, und aktivieren Sie das Debug log, um die Benachrichtigungen zu sehen.

The notification answers Invalid signature: Der x-authenticity-token stimmt nicht mit dem Token der Umgebung überein, in der die Zahlung erfolgte, oder dieses Token ist nicht gespeichert. Prüfen Sie, ob in den Einstellungen das richtige Token steht.

The notification answers Verification failed, retry later: Die PagBank-API war nicht erreichbar, das Token der Umgebung der Zahlung fehlt oder der Warenkorb wurde gleichzeitig von einer anderen Anfrage verarbeitet. PagBank wiederholt die Benachrichtigung.

The notification answers Order not found: Die Benachrichtigung betrifft eine Bestellung, die in diesem Shop nicht mit dieser Erweiterung bezahlt wurde. Es wird nichts geändert.

The customer sees PagBank payments are temporarily unavailable. Please choose another payment method.: Das Token des aktuellen Modus fehlt oder PagBank hat es abgelehnt.

The customer sees PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: Die Kasse läuft in einer anderen Währung.

The customer sees This order has no amount to pay.: Der Bestellbetrag ist null.

Order is in the review status after payment: Lesen Sie die Notizen im Reiter VibeFox PagSeguro Gateway (siehe Bestellstatus), vergleichen Sie die Beträge in PagBank und erfüllen Sie dann die Bestellung oder erstatten Sie die Zahlung.

No refund form in the tab: Der Reiter nennt den Grund: Die Zahlung ist noch nicht als bezahlt gemeldet, sie ist vollständig erstattet, Ihre Benutzergruppe hat kein Recht, die Erweiterung zu ändern, oder das Token der Umgebung der Zahlung ist nicht gesetzt.

Refund fails with a message about the token: Die Zahlung erfolgte in der Sandbox oder in der Produktion, und das Token dieser Umgebung fehlt oder wurde abgelehnt. Geben Sie das richtige Token ein und versuchen Sie es erneut.

Für Entwickler: Bevor die PagBank-Zahlung erstellt wird, löst die Erweiterung das OpenCart-Ereignis wc_psg_checkout_data mit dem Anfragekörper, der Bestellung und der Umgebung aus. Der Artikel muss dem Bestellbetrag entsprechen.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments und klicken Sie neben VibeFox PagSeguro Gateway auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart entfernt immer die eigenen Einstellungen der Erweiterung: Enable / Disable, Sort Order, Geo Zone, Total und die Bestellstatus im Bereich Orders, die bei einer Neuinstallation auf ihre Standardwerte zurückgesetzt werden. Auch das OpenCart-Ereignis der Erweiterung wird entfernt (auf OpenCart 4 auch dessen Ereignisse und die Startup-Aktion, die im Wartungsmodus die Benachrichtigungen und die Rückkehr des Kunden durchlässt). Ist Delete Data on Uninstall eingeschaltet, werden die übrigen Gateway-Einstellungen (Titel, Beschreibung, Sandbox-Modus, Token, Protokollierung) und das Protokoll entfernt. Ist es aus, bleiben sie für eine spätere Neuinstallation erhalten. Die PagBank-Datensätze zu Zahlungen und Erstattungen bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen.

Um auf OpenCart 4 auch die Dateien der Erweiterung zu entfernen, gehen Sie nach der Deinstallation zu Extensions > Installer und klicken Sie in der Liste der installierten Erweiterungen neben VibeFox PagSeguro Gateway auf Uninstall (die orangefarbene −-Schaltfläche) und dann auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

PagSeguro und PagBank sind Marken ihrer jeweiligen Eigentümer. Diese Erweiterung ist weder mit PagSeguro oder PagBank verbunden noch wird sie von ihnen unterstützt.