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

Währung: Brasilianische Real (BRL). Die Zahlungsart wird nur für Warenkörbe in BRL angezeigt.

HTTPS: Ihr Shop 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 schickt das Token per E-Mail. Sandbox: Legen Sie im PagBank-Entwicklerportal ein Sandbox-Konto an und kopieren Sie dessen Token. Sandbox- und Produktionstoken funktionieren nur in ihrer eigenen Umgebung.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel gilt für eine 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 später VibeFox PagSeguro Gateway in der Modulliste und klicken Sie dort auf Configure.

3. Geben 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. Geben Sie das Sandbox-Token und, für echte Zahlungen, das Produktionstoken ein.

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

Bei der Installation legt das Modul zwei Bestellstatus an, Awaiting PagBank payment und PagBank payment on hold. PrestaShop bietet die neue Zahlungsart für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken; die Währung BRL muss für das Modul erlaubt bleiben.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox PagSeguro Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die ganze Seite speichert. Oberhalb der Felder zeigt die Seite den aktuellen Modus an: SANDBOX MODE (Zahlungen werden in der PagBank-Sandbox erstellt, keine echten Abbuchungen) oder LIVE (Zahlungen werden mit dem Produktionstoken erstellt). Sie warnt, wenn das Token des aktuellen Modus fehlt (die Zahlungsart wird dann im Bezahlvorgang ausgeblendet), und wenn die Standardwährung des Shops nicht BRL ist (die Zahlungsart wird dann für Warenkörbe in anderen Währungen nicht angeboten).

PagSeguro / PagBank

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

Title: der Name der Zahlungsart, den Kunden im Bezahlvorgang sehen. Er wird auch als Zahlungsartname in der Bestellung gespeichert. Standard: PagSeguro / PagBank. Pflichtfeld.

Description: der Text unter der Zahlungsart im Bezahlvorgang. 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 Token.

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

Sandbox token: das PagBank-Sandbox-Token. Es wird verwendet, solange der Sandbox-Modus eingeschaltet ist.

Production token: das PagBank-Produktionstoken (Bearer). Es wird verwendet, wenn der Sandbox-Modus ausgeschaltet ist. Halten Sie es geheim.

Gespeicherte Token werden nie erneut 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 tokens: Markieren Sie ein Token und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlungsbenachrichtigungen

Notification URL: Jede Zahlung teilt PagBank mit, wohin Statusänderungen gemeldet werden, daher muss in PagBank nichts eingerichtet werden. Der Abschnitt zeigt die URL. Mit aktivierten URL-Umschreibungen sieht sie so aus: https://your-shop/module/wcp_pagseguro_gateway/webhook. Die Adresse muss über HTTPS aus dem 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. Der Inhalt der Benachrichtigung selbst wird nie als vertrauenswürdig betrachtet: Das Modul liest vor dem Anlegen oder Ändern einer Bestellung immer Checkout und PagBank-Bestellung über die PagBank-API (Status, Betrag, Währung). Ohne Benachrichtigungen wird die Bestellung angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Erweitert

Debug log: Log API requests and notifications schreibt Details in logs/wc_psg_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Logs enthalten weder Token noch Kundendaten. Fehler werden immer protokolliert. Standard: aus.

Log: zeigt die Größe und die neuesten Einträge des Logs. Klicken Sie auf Clear log, um es zu leeren.

Delete Data on Uninstall: Wenn eingeschaltet, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und das Log. Bestellungen, ihre PagBank-Referenzen (für Erstattungen benötigt) und die Bestellstatus bleiben immer erhalten. Standard: aus.

Bezahlvorgang

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig PagSeguro / PagBank) und bestätigt. Das Modul erstellt einen PagBank-Checkout über die Warenkorbsumme in BRL als einen einzigen Artikel, Order # mit der Warenkorbnummer und Ihrem Shopnamen, und leitet den Kunden auf die Zahlungsseite von PagBank weiter. Name und E-Mail-Adresse des Kunden, die CPF oder CNPJ aus dem Feld Identification number oder VAT number der Adresse und eine brasilianische Telefonnummer werden eingetragen, 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 nach 120 Minuten ab. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn PagBank die Zahlung bestätigt: Das Modul liest die Zahlung über die PagBank-API, sobald die Benachrichtigung eintrifft oder der Kunde zurückkehrt; eine bloße Rückkehr markiert eine Bestellung nie als bezahlt. Danach wird die Bestellung angelegt, und der Kunde sieht die Bestellbestätigung mit Your payment with PagBank has been received. Bei einem erzeugten Boleto oder PIX oder einer Zahlung in Prüfung zeigt die Seite Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. Wird eine solche Zahlung später abgelehnt oder storniert, zeigt die Seite Your PagBank payment was not completed. Please contact us about this order. Hat PagBank die Zahlung noch nicht bestätigt, wenn der Kunde zurückkehrt, erscheint die Seite Payment confirmation mit We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. und einer Schaltfläche Check again.

Wurde die Zahlung nicht abgeschlossen, kehrt der Kunde zum Bezahlvorgang 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. Der Warenkorb bleibt erhalten. Wurde eine Bestellung, die auf ein Boleto oder PIX wartete, storniert, sieht der Kunde The PagBank payment was cancelled, so the order was cancelled.

Zahlt der Kunde erneut, wird der offene PagBank-Checkout wiederverwendet, wenn Betrag und Umgebung gleich sind und er nicht innerhalb der nächsten 10 Minuten abläuft. Andernfalls wird der vorherige Checkout deaktiviert, sodass er nicht mehr bezahlt werden kann. Eine Zahlung, die zuvor auf der vorherigen Seite erfolgt ist, zählt weiterhin für den Warenkorb, und die Bestellung wird angelegt, statt eine neue Zahlung zu erzeugen.

Kann PagBank die Zahlung nicht starten, bleibt der Kunde im Bezahlvorgang 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 Log festgehalten.

Benachrichtigungen funktionieren auch, wenn der Shop im Wartungsmodus ist, und werden nicht durch die Ländereinschränkung Ihres Shops blockiert.

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

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Der Kunde wurde zu PagBank weitergeleitet und hat nicht bezahlt, die Karte wurde abgelehnt oder die Zahlungsseite ist abgelaufen. Es existiert nur der Warenkorb, und der Kunde kann erneut bezahlen.

Payment accepted: Die Zahlung wurde mit dem erwarteten Betrag und der erwarteten Währung bestätigt. Sie wird mit der PagBank-Charge-ID als Transaktions-ID verbucht, und eine Notiz zeigt Betrag, Zahlungsart und Charge-ID.

Awaiting PagBank payment: Ein Boleto oder PIX wurde erzeugt und wartet auf Zahlung, oder die Zahlung wird geprüft. Die Bestellung wechselt zu Payment accepted, sobald PagBank die Zahlung als bezahlt meldet.

PagBank payment on hold: PagBank hat einen anderen Betrag oder eine andere Währung gemeldet als der Warenkorb (zum Beispiel wurde der Warenkorb geändert, nachdem die Zahlungsseite erstellt wurde), eine Zahlung ist eingegangen, nachdem die Bestellung storniert worden war (Lagerbestand 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. Der tatsächlich eingegangene Betrag wird in der Bestellung verbucht.

Payment error: Eine Zahlung, die auf Bestätigung wartete oder in Prüfung war, wurde abgelehnt.

Canceled: Eine wartende Zahlung, zum Beispiel ein abgelaufenes Boleto oder PIX, wurde storniert.

Refunded: Die Zahlung wurde vollständig erstattet, über das Modul oder im PagBank-Dashboard.

Jeder PagBank-Status wird nur einmal angewendet, sodass wiederholte Benachrichtigungen oder Rückkehrer keine Notizen oder Statusänderungen hinzufügen. 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.

Block „PagBank payment“

Die Bestellseite zeigt einen Block PagBank payment mit dem PagBank-Checkout, den PagBank-Bestell- und Charge-IDs, der Zahlungsart, dem Status, dem bezahlten und erstatteten Betrag, einem Sandbox-Badge für Sandbox-Zahlungen, dem Erstattungsverlauf und den PagBank notes der Bestellung.

Erstattungen

Geben Sie im Block PagBank payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via PagBank. Bestätigen Sie die Frage Refund this amount through PagBank? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig. Die Obergrenze ist der Betrag, den PagBank belastet hat; nach einer Betragsabweichung können Sie also bis zu dem erstatten, was 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 verbucht, wenn PagBank sie bestätigt; andernfalls zeigt der Block den Fehler, zum Beispiel PagBank refund failed: ... oder PagBank did not confirm the refund, und nichts wird verbucht. Erstattungen von Boleto-Zahlungen und Teilerstattungen von PIX-Zahlungen folgen den Regeln von PagBank. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der Charge-ID hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine Teilerstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald PagBank die Zahlung als bezahlt gemeldet hat.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden über PagBank kein Geld zurück.

Im PagBank-Dashboard vorgenommene Erstattungen werden mit der nächsten Benachrichtigung erkannt: Eine vollständige Erstattung setzt die Bestellung auf Refunded, 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 Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox PagSeguro Gateway ist der erste Block auf Modules > Module Manager > VibeFox PagSeguro Gateway > Configure, oberhalb der Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zur erneuten Prüfung des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-pagseguro 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 Domainplatz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul weiter mit dem zuletzt bekannten Status.

Ein Schlüssel gilt für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt den Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird PagBank Kunden im Bezahlvorgang nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Die PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind; daher ist die Zahlungsart auch für Sie ausgeblendet. Sie können das Modul also einrichten, bevor Sie einen Schlüssel kaufen, aber im Bezahlvorgang nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support benötigen eine Verlängerung. Der Status wird während Ihrer Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach 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

PagBank erscheint nicht im Bezahlvorgang: 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 die Warenkorbwährung BRL ist. Die Einstellungsseite zeigt eine Warnung, wenn das Token fehlt oder die Shopwährung nicht BRL ist. Prüfen Sie unter Payment > Preferences, ob das Modul für BRL, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ist erfolgt, aber es wurde keine Bestellung angelegt: PagBank hat die Zahlung noch nicht gemeldet, und der Kunde ist nicht in den Shop zurückgekehrt. Die Bestellung wird angelegt, sobald die Benachrichtigung eintrifft. Prüfen Sie, ob Ihr Shop unter der Notification URL über HTTPS aus dem Internet erreichbar ist, und schalten Sie das Debug log ein, um die Benachrichtigungen zu sehen.

Die Benachrichtigung meldet 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.

Die Benachrichtigung meldet 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.

Die Benachrichtigung meldet Order not found: Die Benachrichtigung gehört zu einem Warenkorb, der in diesem Shop nicht mit diesem Modul bezahlt wurde. Es wird nichts geändert.

Der Kunde sieht PagBank payments are temporarily unavailable. Please choose another payment method.: Das Token des aktuellen Modus fehlt oder wurde von PagBank abgelehnt.

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

Bestellung ist PagBank payment on hold: Lesen Sie die Notizen im Block PagBank payment (siehe Bestellstatus), vergleichen Sie die Beträge in PagBank und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Erstattung schlägt mit einer Meldung zum Token fehl: Die Zahlung wurde in der Sandbox oder in der Produktion getätigt, und das Token dieser Umgebung fehlt oder wurde abgelehnt. Geben Sie das richtige Token ein und versuchen Sie es erneut.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox PagSeguro Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete Data on Uninstall eingeschaltet, werden die Gateway-Einstellungen und das Log entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die PagBank-Zahlungen und Erstattungen der Bestellungen sowie die Bestellstatus Awaiting PagBank payment und PagBank payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation noch erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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