VibeFox Pagar.me 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 bezahlt und die Bestellsumme größer als null ist.
Pagar.me account: Sie benötigen die geheimen Schlüssel Ihres Pagar.me-Kontos: den Testschlüssel (sk_test_...) und für den Live-Betrieb den Live-Schlüssel (sk_...). Sie finden sie im Pagar.me-Dashboard unter Development > Keys. Verwendet werden nur die geheimen Schlüssel; der öffentliche Schlüssel (pk_...) wird nicht benötigt. Angeboten werden nur die Zahlungsarten, die in Ihrem Pagar.me-Konto aktiviert sind.
VibeFox license key: erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer Domain.
Installation
Der Download ist eine einzige ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das OpenCart-3-Paket wcp_pagarme_gateway-oc3-(version).ocmod.zip und das OpenCart-4-Paket wcp_pagarme_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 Administrationsbereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_pagarme_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 auch den Inhalt des Ordners upload dieses Pakets in das Stammverzeichnis Ihres Shops kopieren.
2. Gehen Sie zu Extensions > Extensions und wählen Sie den Typ Payments. Suchen Sie VibeFox Pagar.me Gateway und klicken Sie auf Install (die grüne +-Schaltfläche). Ihr Administrator 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 den Lizenzbereich oben auf der Seite unter License key ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Geben Sie den geheimen Testschlüssel ein und, wenn Sie live gehen, den geheimen Live-Schlüssel.
5. Legen Sie im Pagar.me-Dashboard den Webhook mit der URL an, die in den Einstellungen angezeigt wird (siehe Konfiguration).
6. Aktivieren Sie Enable / Disable und klicken Sie auf Save. Führen Sie Testzahlungen bei eingeschaltetem Test mode durch und schalten Sie ihn danach aus, um echte Zahlungen anzunehmen.
OpenCart 4
1. Gehen Sie im Administrationsbereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_pagarme_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 Pagar.me Gateway, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Stift-Schaltfläche).
4. Geben Sie den Lizenzschlüssel, die geheimen Schlüssel und den Webhook ein, wie in den Schritten 3 bis 6 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich. Nur die Webhook-URL ist anders (siehe Zahlungsbenachrichtigungen (Webhook)).
Eine neue Installation startet mit deaktivierter Zahlungsart und eingeschaltetem Testmodus.
Konfiguration
Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Payments > VibeFox Pagar.me Gateway > Edit. Die Abschnitte sind links aufgelistet; die Schaltfläche Save unter der Liste speichert die gesamte Seite. Oberhalb der Einstellungen zeigt die Seite den aktuellen Modus an: TEST MODE (Zahlungen werden mit dem geheimen Testschlüssel angelegt, es erfolgen keine echten Abbuchungen) oder LIVE. Sie warnt, wenn der geheime Schlüssel des aktuellen Modus fehlt (die Zahlungsart wird dann an der Kasse ausgeblendet), wenn der Testschlüssel nicht mit sk_test_ beginnt, wenn der Live-Schlüssel nicht mit sk_ beginnt oder ein Testschlüssel ist, 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), Boleto due in (days) muss eine ganze Zahl von 1 bis 30 sein, Sort Order muss eine ganze Zahl sein (negative Zahlen sind erlaubt), Total muss eine Zahl von 0 oder mehr sein, und die Geo-Zone und die Bestellstatus müssen existieren. Ist ein Wert falsch, nennt eine Fehlermeldung ihn, und nichts wird gespeichert.
Pagar.me
Enable / Disable: Enable Pagar.me payments schaltet die Zahlungsart ein oder aus. Standard: aus.
Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Pagar.me. Pflichtfeld, bis zu 128 Zeichen.
Description: der Text, den der Kunde im Schritt Confirm Order über der Bestätigungsschaltfläche sieht. Standard: Sicher bezahlen über Pagar.me (Kreditkarte, PIX oder Boleto). Sie werden weitergeleitet, um Ihre Zahlung abzuschließen.
Sort Order: die Position von Pagar.me unter den Zahlungsarten an der Kasse. Lassen Sie das Feld leer oder geben Sie eine ganze Zahl ein.
Geo Zone: bietet Pagar.me nur für Rechnungsadressen in der ausgewählten Geo-Zone an. Standard: All zones. Geo-Zonen richten Sie unter System > Localisation > Geo Zones ein. In OpenCart 4 wird die Lieferadresse verwendet, wenn der Shop keine Rechnungsadresse abfragt.
Total: der Kassenbetrag in der Standardwährung des Shops, den eine Bestellung erreichen muss, bevor Pagar.me angeboten wird. Lassen Sie das Feld leer, um Pagar.me bei jedem Betrag anzubieten.
API-Schlüssel
Kopieren Sie die geheimen Schlüssel aus dem Pagar.me-Dashboard (der Abschnitt enthält einen Link dorthin): Development > Keys. Pagar.me verwendet eine API-Adresse für Test- und Live-Zahlungen; der Schlüssel entscheidet, ob es sich um eine Test- oder echte Zahlung handelt.
Test mode: verwendet den geheimen Testschlüssel, es erfolgen keine echten Abbuchungen. Ist er eingeschaltet, sehen Kunden im Schritt Confirm Order den Hinweis TEST MODE — Use test credentials. No real charges.. Statusabfragen und Erstattungen einer Bestellung verwenden immer den Schlüssel des Modus, in dem ihre Zahlung angelegt wurde. Standard: eingeschaltet.
Test secret key: der geheime Testschlüssel von Pagar.me (sk_test_...). Er wird verwendet, solange der Testmodus eingeschaltet ist.
Live secret key: der geheime Live-Schlüssel von Pagar.me (sk_...). Er wird verwendet, wenn der Testmodus ausgeschaltet ist. Bewahren Sie ihn sicher auf.
Gespeicherte Schlüssel 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 einen gespeicherten Schlüssel zu entfernen, aktivieren Sie unter dem Feld Clear the saved key on save und klicken Sie auf Save.
Zahlungsseite
Die Zahlungsarten, die auf der Zahlungsseite von Pagar.me angeboten werden, jeweils mit eigenem Schalter. Wählen Sie nur Zahlungsarten, die in Ihrem Pagar.me-Konto aktiviert sind. Ist keine ausgewählt, werden Kreditkarte, PIX und Boleto angeboten. Standard: Kreditkarte, PIX und Boleto.
Boleto due in (days): die Anzahl der Tage bis zur Fälligkeit des Boleto, von 1 bis 30. Standard: 3. Ein anderer Wert wird beim Speichern mit Boleto due in (days): enter a number from 1 to 30. abgelehnt.
Zahlungsbenachrichtigungen (Webhook)
Öffnen Sie im Pagar.me-Dashboard Settings > Webhooks und legen Sie einen Webhook mit der URL an, die unter Webhook URL in diesem Abschnitt angezeigt wird. Unter OpenCart 3 hat sie die Form https://your-store/index.php?route=extension/payment/wcp_pagarme_gateway/webhook, unter OpenCart 4 die Form https://your-store/index.php?route=extension/wcp_pagarme_gateway/payment/wcp_pagarme_gateway.webhook. Sie wird aus der Shop-Adresse Ihrer OpenCart-Installation gebildet. Kopieren Sie sie genau so, wie sie in den Einstellungen angezeigt wird. Die URL muss aus dem Internet erreichbar sein.
Wählen Sie diese Ereignisse aus (sie sind ebenfalls in diesem Abschnitt aufgeführt):
Der Webhook benötigt weder Passwort noch Signatur. Sein Inhalt wird nie als vertrauenswürdig behandelt: Der Shop übernimmt daraus nur die Pagar.me-Bestell-ID und liest diese Bestellung mit dem Schlüssel des Modus, in dem sie angelegt wurde, über die Pagar.me-API aus. Benachrichtigungen zu Pagar.me-Bestellungen, die nicht von diesem Shop angelegt wurden, werden ignoriert. Ohne den Webhook werden später erfolgte PIX- und Boleto-Zahlungen erst bestätigt, wenn der Kunde zum Shop zurückkehrt.
Bestellungen
OpenCart legt die Bestellung im Schritt Confirm Order ohne Status an (eine fehlende Bestellung, missing order). Die Bestellung erhält einen Status erst, nachdem Pagar.me die Zahlung per Webhook oder bei der Rückkehr des Kunden gemeldet hat; die Pagar.me-Bestellung wird immer erneut über die API abgefragt. Jedes der folgenden Felder listet Ihre OpenCart-Bestellstatus auf.
Order Status After Payment: der Status nach einer geprüften Pagar.me-Zahlung. Standard: In Bearbeitung.
Awaiting Pagar.me Payment Status: ein PIX-Code oder Boleto wurde ausgestellt oder eine Kartenzahlung wird geprüft; Pagar.me bestätigt den Geldeingang später. Standard: Ausstehend.
Pagar.me Payment On Hold Status: die Zahlung muss von Ihnen geprüft werden (siehe Bestellstatus). Standard: Ausstehend, da OpenCart keinen Status „Zurückgehalten“ hat. Sie können unter System > Localisation > Order Statuses einen eigenen Status anlegen und hier auswählen.
Payment Failed Status: die Zahlung einer wartenden Bestellung ist fehlgeschlagen, wurde storniert oder ist abgelaufen. Meldet Pagar.me sie später doch als bezahlt, erhält die Bestellung den Status nach der Zahlung. Standard: Fehlgeschlagen.
Cancelled Order Status: der Status, den Ihr Shop für stornierte Bestellungen verwendet. Die Erweiterung setzt ihn nicht: Eine Pagar.me-Zahlung, die danach eingeht, versetzt die Bestellung in den Prüfstatus. Standard: Storniert.
Refunded Status: wird gesetzt, nachdem die Zahlung von der Bestellseite oder im Pagar.me-Dashboard vollständig erstattet wurde. Standard: Erstattet.
Erweitert
Debug log: schreibt API-Anfragen und Benachrichtigungen in wc_pgm_debug.log.php im Logs-Ordner von OpenCart (storage/logs). Die Datei lässt sich nicht über den Webbrowser öffnen. Fehler und Warnungen werden immer protokolliert. Schlüssel und Kundendaten (E-Mail, Telefon, CPF) werden nicht protokolliert. Standard: aus.
Log: zeigt die Größe und die neuesten Einträge des Protokolls an. Klicken Sie auf Clear log, um es zu leeren.
Delete data on uninstall: Ist die Option eingeschaltet, werden beim Deinstallieren der Erweiterung die Gateway-Einstellungen und das Protokoll entfernt. Bestellungen und ihre Pagar.me-Zahlungsdaten (für Erstattungen benötigt) bleiben immer erhalten. Standard: aus.
Import / Export
Export: Download JSON speichert die Einstellungen als JSON-Datei. Geheime Schlüssel werden nicht exportiert.
Import: fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen. Gespeicherte geheime Schlüssel bleiben erhalten.
Kasse
Im Schritt Payment Method wählt der Kunde die Zahlungsart (standardmäßig Pagar.me). Im Schritt Confirm Order sieht der Kunde Ihre Beschreibung und den Hinweis You will be redirected to the Pagar.me payment page to pay by credit card, PIX, boleto or debit card. OpenCart legt die Bestellung in diesem Schritt an, noch ohne Status. In OpenCart 4 wählt der Kunde die Zahlungsart mit der Schaltfläche Choose im Block der Zahlungsart, im Fenster Payment method options, und klickt unten auf der Kassenseite auf Confirm Order. Klickt der Kunde auf Confirm Order, legt die Erweiterung eine Pagar.me-Bestellung über den Bestellbetrag in BRL an und leitet den Kunden auf die Zahlungsseite von Pagar.me weiter. Die Bestellpositionen mit Steuern, Versand und anderen Aufschlägen werden als Artikel übermittelt; hat die Bestellung einen Rabatt (Coupon, Gutschein, Bonuspunkte) oder ergeben die Positionen nicht die Gesamtsumme, wird eine Position Order # mit der Bestellnummer über den Gesamtbetrag übermittelt. Eine gültige E-Mail-Adresse ist erforderlich.
Name und E-Mail-Adresse des Kunden werden an Pagar.me übergeben. CPF oder CNPJ (11 oder 14 Ziffern) wird aus einem benutzerdefinierten Feld des Kunden oder der Rechnungsadresse übernommen, dessen Name CPF oder CNPJ enthält; OpenCart hat standardmäßig kein solches Feld, daher fügen Sie es unter Customers > Custom Fields hinzu, wenn Sie es übergeben möchten. In OpenCart 4 werden, wenn der Shop keine Rechnungsadresse abfragt, die Lieferadresse und ihre benutzerdefinierten Felder verwendet. Eine brasilianische Mobilnummer wird ebenfalls übergeben. Die Rechnungsadresse wird nur für eine brasilianische Adresse mit achtstelliger CEP und einem Bundesstaat übergeben. Ohne CPF oder CNPJ gibt der Kunde diese auf der Pagar.me-Seite ein.
Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Pagar.me die Zahlung bestätigt: Der Shop liest die Pagar.me-Bestellung über die API, und der gezahlte Betrag und die Währung müssen mit der Bestellung übereinstimmen. Danach erhält die Bestellung ihren Status auf die übliche OpenCart-Weise, mit den üblichen Bestell-E-Mails und der Bestandsaktualisierung, und der Kunde sieht die OpenCart-Erfolgsseite der Bestellung. Ein ausgestelltes PIX oder Boleto, das noch nicht bezahlt wurde, versetzt die Bestellung in den Status „Ausstehend“; die Seite zeigt außerdem Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Bei einer Bestellung im Prüfstatus erscheint We are confirming your payment with Pagar.me. The order will be updated automatically — please do not pay again. Bei jeder späteren Rückkehr wird die Pagar.me-Bestellung erneut gelesen, sodass ein in der Zwischenzeit bezahltes PIX oder Boleto auch dann übernommen wird, wenn der Webhook nicht angekommen ist.
Kehrt der Kunde ohne Zahlung zurück, landet er wieder an der Kasse mit The Pagar.me payment was not completed. You can try again or choose another payment method. Wurde die Zahlung abgelehnt oder storniert, lautet die Meldung The Pagar.me payment was declined or canceled. You can try again or choose another payment method. Der Warenkorb bleibt erhalten. In OpenCart 4 werden diese Meldungen oberhalb der Kassenseite angezeigt. Hat die Bestellung bereits einen Status und ist ihre Zahlung fehlgeschlagen oder abgelaufen, lautet die Meldung The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. Ist der Warenkorb bereits leer (zum Beispiel weil die Bestellung die Erfolgsseite erreicht hatte, bevor ihr PIX oder Boleto abgelaufen ist), gibt es an der Kasse nichts mehr zu bezahlen: Eine Seite Payment confirmation sagt The Pagar.me 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. Konnte Pagar.me nicht erreicht werden, bittet eine Seite Payment confirmation den Kunden, nicht erneut zu bezahlen, und bietet Check again und Back to checkout an.
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, sodass der Kunde nach einer nicht abgeschlossenen oder abgelehnten Zahlung dieselbe Bestellung erneut bezahlt. Vor einer neuen Zahlung prüft die Erweiterung die früheren Versuche desselben Warenkorbs: Ist einer davon bezahlt oder wartet sein PIX oder Boleto noch, gelangt der Kunde ohne neue Zahlung zur Erfolgsseite. Eine offene Pagar.me-Zahlungsseite derselben Bestellung wird wiederverwendet, wenn Betrag und Modus gleich sind; andere offene Seiten werden zuvor bei Pagar.me geschlossen. Wird eine zweite Pagar.me-Bestellung desselben Warenkorbs dennoch bezahlt, wird sie nicht übernommen, und ein Hinweis an der bezahlten Bestellung bittet Sie, das Duplikat zu erstatten.
In OpenCart 4 bleibt die Bestellung der Kasse bis zur Anzeige der Erfolgsseite erhalten. Wurde diese Bestellung inzwischen geschlossen (zum Beispiel ist ihr PIX oder Boleto abgelaufen, ihre Zahlung fehlgeschlagen oder Sie haben sie storniert oder erstattet), schickt Confirm Order den Kunden mit Your previous order was cancelled or its payment failed. Please confirm the order again. zurück zur Kasse, oder, wenn die Bestellung vor dem Schließen bezahlt war, mit This order was closed by the store, so it will not be shipped. Your cart is kept: confirm the order again to pay. Das nächste Confirm Order bezahlt eine neue Bestellung. Kehrt der Kunde von Pagar.me zu einer Bestellung zurück, die bezahlt und danach von Ihnen geschlossen wurde, sieht er an der Kasse dieselbe Meldung oder, wenn der Warenkorb bereits leer ist, eine Seite mit Order #(Nummer) was closed by the store, so it will not be shipped. To buy these items, please place a new order. Hat die Bestellung der Kasse bereits einen Status und enthält der Warenkorb nun andere Produkte oder Mengen, wird der Kunde zurück zur Kasse geschickt, und der neue Warenkorb erhält eine neue Bestellung.
Kann Pagar.me die Zahlung nicht starten, bleibt der Kunde im Schritt Confirm Order mit einer kurzen Meldung, zum Beispiel Could not connect to Pagar.me. Please try again in a moment., oder der Pagar.me-Meldung zu ungültigen Rechnungsdaten. Der technische Grund wird im Protokoll festgehalten.
Der Webhook funktioniert auch, wenn sich der Shop im Wartungsmodus befindet: OpenCart 3 lässt Anfragen von Zahlungserweiterungen durch, und in OpenCart 4 fügt die Erweiterung eine Startup-Aktion hinzu, die den Webhook und die Rückkehr des Kunden von Pagar.me durchlässt.
Die Erweiterung hat kein Kartenformular in Ihrer Kasse, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen, keine Ratenregeln, keine Split-Zahlungen (Marktplatz) und keine reinen Autorisierungszahlungen per Karte.
Bestellungen und Erstattungen
Bestellstatus
No status (missing order): Der Kunde wurde zu Pagar.me weitergeleitet und hat noch nicht bezahlt oder kein PIX oder Boleto ausgestellt, oder die Zahlung wurde abgelehnt. Unter Sales > Orders werden solche Bestellungen nur mit dem Filter Order Status auf Missing Orders angezeigt.
In 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 bestätigt. Eine Notiz zeigt die Pagar.me-Bestell-ID (or_...) und die Zahlungsart.
Awaiting Pagar.me Payment Status (default Pending): ein PIX oder Boleto wurde ausgestellt (oder eine Kartenzahlung wird geprüft) und wartet auf Zahlung. Die Bestellung wechselt zu Order Status After Payment, sobald Pagar.me die Zahlung bestätigt.
Pagar.me Payment On Hold Status (default Pending): das Boleto wurde nur teilweise bezahlt; oder der gezahlte Betrag oder die Währung weicht von der Bestellung ab; oder die Zahlung kam an, nachdem die Bestellung storniert oder erstattet worden war; oder für eine bezahlte Bestellung wurde ein Chargeback eröffnet. Die Notiz erklärt es. Prüfen Sie die Bestellung und erfüllen Sie sie oder erstatten Sie die Zahlung.
Payment Failed Status (default Failed): die Zahlung einer wartenden oder zurückgehaltenen Bestellung ist fehlgeschlagen, oder ihre Pagar.me-Bestellung wurde storniert oder ist abgelaufen (zum Beispiel ein unbezahltes Boleto). Meldet Pagar.me später eine Zahlung, wechselt die Bestellung trotzdem zu Order Status After Payment.
Refunded Status (default Refunded): die Zahlung wurde über die Erweiterung vollständig erstattet oder in Pagar.me erstattet oder storniert.
Jeder Pagar.me-Status wird genau einmal angewendet, sodass wiederholte Webhooks oder Rückkehrer keine Notizen oder Zahlungen hinzufügen. Notizen sind Einträge im History der Bestellung, die der Kunde nicht sieht.
Registerkarte VibeFox Pagar.me Gateway
Öffnen Sie unter Sales > Orders eine mit Pagar.me bezahlte Bestellung. Am unteren Rand der Bestellseite, neben History und Additional, zeigt die Registerkarte VibeFox Pagar.me Gateway die Pagar.me order-ID mit einem Hinweis Test mode für Testzahlungen, die Payment method, den Status, die Beträge Paid / refunded, das Erstattungsformular, den Erstattungsverlauf und die Pagar.me notes der Bestellung an. Die Registerkarte wird Benutzern angezeigt, die Zugriff auf die Erweiterung haben.
Erstattungen
Geben Sie auf der Registerkarte VibeFox Pagar.me Gateway den Amount ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Reason (optional), und klicken Sie auf Refund via Pagar.me. Bestätigen Sie die Abfrage Refund this amount through Pagar.me? This cannot be undone. Vollständige und teilweise Erstattungen von Karten- und PIX-Zahlungen werden unterstützt. Sie benötigen das Recht, die Erweiterung zu ändern (festgelegt unter System > Users > User Groups). Sie können bis zu dem Betrag erstatten, den Pagar.me tatsächlich eingezogen hat; nach einer Betragsabweichung ist die Grenze also der Betrag, den der Kunde bezahlt hat, nicht die Bestellsumme. Die Erstattung wird mit dem Schlüssel des Modus gesendet, in dem die Zahlung erfolgte, daher muss dessen geheimer Schlüssel eingerichtet sein. Eine Erstattung wird nur verbucht, wenn Pagar.me sie bestätigt; andernfalls zeigt die Registerkarte den Fehler an, zum Beispiel Pagar.me refused the refund: ... oder Pagar.me did not confirm the refund, und es wird keine Erstattung verbucht. Eine erfolgreiche Erstattung wird mit der Belastungs-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 Artikel an den Bestand zurückzugeben, wie eine manuelle Statusänderung. Eine teilweise Erstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Pagar.me die Zahlung gemeldet hat.
Boleto-Zahlungen können nur auf das Bankkonto des Kunden erstattet werden. Erstatten Sie sie im Pagar.me-Dashboard und erfassen Sie die Erstattung anschließend manuell in OpenCart. Produktrücksendungen unter Sales > Returns zahlen über Pagar.me kein Geld zurück.
Eine vollständige Erstattung oder Stornierung, die im Pagar.me-Dashboard vorgenommen wird, kommt per Webhook an, setzt die Bestellung auf Refunded Status und fügt eine Notiz hinzu. Ein Chargeback fügt eine Notiz hinzu und versetzt eine bezahlte Bestellung in den Prüfstatus.
Lizenzschlüssel
Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich License — VibeFox Pagar.me Gateway ist der erste Block auf Extensions > Extensions > Payments > VibeFox Pagar.me Gateway > Edit, oberhalb der Einstellungen. Fügen Sie den Schlüssel unter 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 zur erneuten Statusprüfung, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-payment-pagarme und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Administratoren mit dem Recht zum Ändern der Erweiterung können den Schlüssel ändern. Die Texte des Bereichs folgen der Sprache des Administrationsbereichs (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. Nachdem sich die Shop-Adresse geändert hat oder Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet die Erweiterung mit dem zuletzt bekannten Status weiter.
Ein Schlüssel funktioniert auf einer Domain: der 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 Pagar.me Kunden an der Kasse nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Ein Administrator, der im Administrationsbereich im selben Browser angemeldet ist, sieht die Zahlungsart im Shop weiterhin, mit dem Hinweis (unlicensed — visible to admins only), damit Sie die Erweiterung vor dem Kauf eines Schlüssels einrichten und testen können. In OpenCart 4 gibt es diese Vorschau nicht: Der Shop sieht die Anmeldung im Administrationsbereich nicht, daher ist ohne aktiven Schlüssel die Zahlungsart für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint auf dem Dashboard des Administrationsbereichs eine Erinnerung. Schließen Sie sie mit ×, um sie für 7 Tage 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, Updates und Support erfordern jedoch eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard oder die Seite Edit im Administrationsbereich öffnen: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal wöchentlich. Ein Cron-Job ist nicht nötig. Beim Deinstallieren der Erweiterung werden der Lizenzschlüssel und der Lizenzstatus immer entfernt.
Fehlerbehebung
Pagar.me does not appear at checkout: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, der geheime Schlüssel des aktuellen Modus gesetzt ist (Test secret key im Testmodus, Live secret key im Live-Modus) und der Kunde in BRL bezahlt. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt. Prüfen Sie außerdem, ob die Zahlungsadresse in der ausgewä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 or in the awaiting status: Der Webhook funktioniert nicht. Prüfen Sie im Pagar.me-Dashboard, ob der Webhook für das von Ihnen verwendete Konto und den Modus existiert, ob seine URL genau der unter Webhook URL angezeigten entspricht und ob die oben genannten Ereignisse ausgewählt sind. Die Bestellung wird außerdem jedes Mal geprüft, wenn der Kunde zum Shop zurückkehrt.
The webhook answers verification failed, retry later: Der Shop konnte die Pagar.me-Bestellung nicht über die API lesen, zum Beispiel weil der Schlüssel dieses Modus fehlt oder die API nicht antwortete. Pagar.me wiederholt den Webhook.
The webhook answers busy: Der Warenkorb wurde im selben Moment von einer anderen Anfrage verarbeitet, oder der Bestellstatus konnte nicht gesetzt werden. Pagar.me wiederholt den Webhook. Aktivieren Sie Debug log, um den Grund zu sehen.
The webhook answers unknown order: Die Pagar.me-Bestellung wurde nicht von diesem Shop angelegt, zum Beispiel eine Bestellung eines anderen Shops auf demselben Konto. Es wird nichts geändert.
The webhook answers invalid payload or invalid order id: Die Anfrage ist keine Pagar.me-Benachrichtigung. Es wird nichts geändert.
The customer sees Pagar.me payments are not available right now: Der geheime Schlüssel ist falsch oder fehlt. Prüfen Sie den Schlüssel des aktuellen Modus.
The customer sees Pagar.me could not start the payment: Pagar.me hat die Rechnungsdaten abgelehnt, zum Beispiel die CPF im benutzerdefinierten Feld. Die Meldung nennt das Problem; der vollständige Grund steht im Protokoll.
The customer sees A valid billing email is required for Pagar.me.: Die E-Mail-Adresse der Bestellung ist ungültig.
The customer sees Pagar.me only supports payments in Brazilian Real (BRL).: Die Kasse läuft in einer anderen Währung.
The customer sees This order already has a Pagar.me payment that the store has to review: Eine frühere Zahlung des Warenkorbs muss von Ihnen geprüft werden. Prüfen Sie das Pagar.me-Dashboard und das Protokoll.
Order is in the review status after payment: Lesen Sie die Notizen auf der Registerkarte VibeFox Pagar.me Gateway (siehe Bestellstatus) und erfüllen Sie danach die Bestellung oder erstatten Sie die Zahlung.
No refund form in the tab: Die Registerkarte nennt den Grund: Die Zahlung ist noch nicht gemeldet, sie ist vollständig erstattet, Ihre Benutzergruppe hat kein Recht zum Ändern der Erweiterung oder der geheime Schlüssel des Modus der Zahlung ist nicht gesetzt.
Refund fails for a boleto: Boleto-Zahlungen können nicht über die API erstattet werden. Erstatten Sie im Pagar.me-Dashboard und erfassen Sie die Erstattung manuell.
Für Entwickler: Bevor die Pagar.me-Bestellung gesendet wird, löst die Erweiterung das OpenCart-Ereignis wc_pgm_order_data mit dem Anfragetext und der Bestellung aus. Der Zahlungsbetrag muss gleich der Bestellsumme bleiben.
Deinstallation
Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments und klicken Sie neben VibeFox Pagar.me Gateway auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart entfernt stets die eigenen Einstellungen der Erweiterung: Enable / Disable, Sort Order, Geo Zone, Total und die Bestellstatus aus dem Abschnitt Orders, die bei einer Neuinstallation auf ihre Standardwerte zurückgesetzt werden. Das OpenCart-Ereignis der Erweiterung wird ebenfalls entfernt (in OpenCart 4 seine Ereignisse und seine Startup-Aktion, die den Webhook und die Rückkehr des Kunden im Wartungsmodus durchlässt). Ist Delete data on uninstall eingeschaltet, werden die übrigen Gateway-Einstellungen (Titel, Beschreibung, Testmodus, geheime Schlüssel, Zahlungsarten, Boleto-Tage, Protokollierung) und das Protokoll entfernt. Ist die Option ausgeschaltet, bleiben sie für eine spätere Neuinstallation erhalten. Die Zahlungs- und Erstattungsdaten von Pagar.me bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen.
In OpenCart 4 entfernen Sie auch die Dateien der Erweiterung, indem Sie nach der Deinstallation zu Extensions > Installer gehen, in der Liste der installierten Erweiterungen neben VibeFox Pagar.me Gateway auf Uninstall (die orangefarbene −-Schaltfläche) und danach auf Delete (die rote Papierkorb-Schaltfläche) klicken, um das hochgeladene Paket zu entfernen.
Pagar.me ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit Pagar.me verbunden und wird von Pagar.me nicht unterstützt.