VibeFox Pagar.me 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: brasilianischer Real (BRL). Die Zahlungsart wird ausgeblendet, wenn die Shop-Währung (bzw. auf der Seite „Pay for order“ die Bestellwährung) nicht BRL ist.

Pagar.me-Konto: Sie benötigen die geheimen Schlüssel Ihres Pagar.me-Kontos: den Testschlüssel (sk_test_...) und, für den Livebetrieb, 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-Lizenzschlüssel: gekauft auf vibefox.net. Ein Schlüssel funktioniert auf einer 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. Sie können den Ordner wcp_pagarme_gateway auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Pagar.me > Manage, oder klicken Sie auf der Seite Plugins unter dem Namen des Plugins 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 geheimen Testschlüssel ein und beim Start des Livebetriebs den geheimen Live-Schlüssel.

6. Legen Sie den Webhook im Pagar.me-Dashboard mit der URL an, die in den Einstellungen angezeigt wird (siehe Konfiguration).

7. Aktivieren Sie Enable / Disable und speichern Sie. Machen Sie Testzahlungen mit eingeschaltetem Test mode, danach schalten Sie ihn aus, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Pagar.me. Unter dem Titel zeigt die Seite den aktuellen Modus an: TEST MODE (Zahlungen werden mit dem geheimen Testschlüssel angelegt, keine echten Belastungen) 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 Shop-Währung nicht BRL ist. In der Liste der Zahlungsarten ist Pagar.me als einrichtungsbedürftig markiert, bis der Schlüssel des aktuellen Modus eingegeben ist; solange der Testmodus aktiv ist, wird außerdem ein Test-Hinweis angezeigt.

Allgemein

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. Standard: Pagar.me.

Description: der Text unter der Zahlungsart an der Kasse. Standard: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

API-Schlüssel

Kopieren Sie die geheimen Schlüssel aus dem Pagar.me-Dashboard: Development > Keys. Pagar.me verwendet eine einzige API-Adresse für Test- und Live-Zahlungen; der Schlüssel entscheidet, ob es sich um eine Test- oder echte Zahlung handelt.

Test mode: Use the test secret key (no real charges). Solange der Testmodus eingeschaltet ist, wird an der Kasse ein Hinweis TEST MODE angezeigt. Statusprüfungen und Erstattungen einer Bestellung verwenden immer den Schlüssel des Modus, in dem ihre Zahlung angelegt wurde. Standard: an.

Test secret key: der geheime Testschlüssel von Pagar.me (sk_test_...). Wird verwendet, solange der Testmodus eingeschaltet ist.

Live secret key: der geheime Live-Schlüssel von Pagar.me (sk_...). Wird verwendet, wenn der Testmodus ausgeschaltet ist. Halten Sie ihn geheim.

Der einzelne geheime Schlüssel aus Version 1.0 wird automatisch übernommen: Ein Testschlüssel wird in Test secret key verschoben und der Testmodus eingeschaltet; andernfalls bleibt er der Live-Schlüssel und der Testmodus wird ausgeschaltet.

Zahlungsseite

Payment methods: die Zahlungsarten, die auf der Pagar.me-Zahlungsseite angeboten werden. Wählen Sie nur Zahlungsarten, die in Ihrem Pagar.me-Konto aktiviert sind. Standard: Credit card, PIX und Boleto.

Credit card: sofort autorisiert und eingezogen.

PIX: Sofortzahlung per PIX.

Boleto: Zahlschein; die Bestellung bleibt auf „On hold“, bis sie bezahlt wird.

Debit card: Zahlung mit Debitkarte.

Boleto due in (days): die Anzahl der Tage bis zur Fälligkeit des Boleto, von 1 bis 30. Die Bestellung bleibt auf „On hold“, bis Pagar.me die Zahlung bestätigt. Standard: 3.

Zahlungsbenachrichtigungen (Webhook)

Öffnen Sie im Pagar.me-Dashboard Settings > Webhooks und legen Sie einen Webhook mit der URL an, die in diesem Abschnitt angezeigt wird. Sie sieht so aus: https://your-site/wc-api/webhook_wc_pagarme/. Kopieren Sie sie genau so, wie die Einstellungen sie anzeigen.

Wählen Sie diese Ereignisse aus:

order.paid: die Pagar.me-Bestellung wurde bezahlt.

order.payment_failed: die Zahlung ist fehlgeschlagen.

order.canceled: die Pagar.me-Bestellung wurde storniert oder ist abgelaufen.

charge.paid: eine Belastung wurde bezahlt, zum Beispiel ein PIX oder Boleto, das später bezahlt wurde.

charge.pending: eine Belastung wartet auf Zahlung, zum Beispiel ein ausgestelltes Boleto.

charge.refunded: eine Belastung wurde erstattet.

charge.chargedback: der Karteninhaber hat eine Zahlung beanstandet.

Der Webhook benötigt weder Passwort noch Signatur. Sein Inhalt wird nie als vertrauenswürdig behandelt: Der Shop übernimmt daraus nur die Pagar.me-Bestellnummer und liest diese Bestellung über die Pagar.me-API mit dem Schlüssel des Modus, in dem sie angelegt wurde. Benachrichtigungen zu Bestellungen anderer Shops auf demselben Pagar.me-Konto werden ignoriert. Ohne den Webhook werden später bezahlte PIX- und Boleto-Zahlungen erst bestätigt, wenn der Kunde zum Shop zurückkehrt.

Erweitert

Debug log: Log API requests and notifications schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_pagarme_gateway. Fehler werden immer protokolliert. Protokolle enthalten keine Schlüssel 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 Pagar.me) und gibt die Bestellung auf. Eine gültige Rechnungs-E-Mail-Adresse ist erforderlich. Das Plugin legt eine Pagar.me-Bestellung über die Bestellsumme in BRL an, mit den Bestellpositionen, dem Versand und den Gebühren (oder einer einzelnen Position Order # mit der Bestellnummer, wenn sich die Positionen nicht exakt addieren lassen), und sendet den Kunden zur Zahlungsseite von Pagar.me. Name, E-Mail-Adresse und für Brasilien Telefonnummer und Rechnungsadresse des Kunden werden an Pagar.me übergeben. CPF oder CNPJ werden aus den Feldern des Plugins Brazilian Market on WooCommerce übernommen, sofern vorhanden; andernfalls gibt der Kunde sie auf der Pagar.me-Seite ein.

Nach der Zahlung kehrt der Kunde zu Ihrem 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 bezahlte Betrag und die Währung müssen mit der Bestellung übereinstimmen. Eine bezahlte Kartenzahlung, ein bezahltes PIX oder Boleto markiert die Bestellung als bezahlt. Ein ausgestelltes PIX oder Boleto, das noch nicht bezahlt wurde, setzt die Bestellung auf „On hold“, bis Pagar.me die Zahlung per Webhook bestätigt.

Kehrt der Kunde ohne Zahlung zurück oder wurde die Zahlung abgelehnt oder abgebrochen, gelangt er zur Seite Pay for order mit The Pagar.me payment was not completed. You can pay the order below. oder The Pagar.me payment was declined or canceled. You can try again below.

Zahlt der Kunde erneut, wird die offene Pagar.me-Zahlungsseite wiederverwendet, wenn Betrag und Modus gleich sind; andernfalls wird sie bei Pagar.me geschlossen, bevor eine neue angelegt wird. Wurde der frühere Versuch inzwischen bezahlt oder wartet sein PIX oder Boleto noch, wird die Bestellung ohne neue Zahlung aktualisiert. Lässt sich die frühere Seite nicht schließen, bleibt sie der Bestellung zugeordnet, sodass eine dort vorgenommene Zahlung trotzdem erfasst wird.

Kann Pagar.me die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel Could not connect to Pagar.me. Please try again in a moment., oder die Pagar.me-Meldung zu ungültigen Rechnungsdaten. Der technische Grund wird den Bestellnotizen hinzugefügt.

Die Zahlungsart funktioniert an 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 Kartenformular in Ihrer Kasse, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen, keine Ratenzahlungsregeln, keine Split-Zahlungen (Marktplatz), keine Autorisierungs-Zahlungen per Karte und keine Integration von Pagar.me Hub.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Der Kunde wurde zu Pagar.me weitergeleitet und hat noch nicht bezahlt oder noch kein PIX oder Boleto erstellt. Eine Notiz zeigt die Pagar.me-Bestellnummer und den Modus.

Processing: Die Zahlung wurde bestätigt. Dies ist der übliche WooCommerce-Status nach der Zahlung; Bestellungen mit nur virtuellen, herunterladbaren Produkten werden auf Completed gesetzt. Die Bestellnotiz zeigt die Pagar.me-Bestellnummer und die Zahlungsart. Die Transaktions-ID ist die Pagar.me-Bestellnummer (or_...).

On hold: Ein PIX oder Boleto wurde ausgestellt (oder eine Kartenzahlung wird geprüft) und wartet auf Zahlung; oder das Boleto wurde nur teilweise bezahlt; oder der bezahlte Betrag oder die Währung weicht von der Bestellung ab; oder eine Zahlung ist nach der Stornierung der Bestellung eingegangen; oder die Bestellung wurde bei Pagar.me bezahlt, nachdem der Kunde auf eine andere Zahlungsart gewechselt war; oder ein Chargeback wurde für eine bezahlte Bestellung eröffnet. Die Bestellnotiz erklärt den Grund. Prüfen Sie die Bestellung und setzen Sie sie auf Processing oder erstatten Sie die Zahlung bei Pagar.me.

Failed: Die Zahlung ist fehlgeschlagen, oder die Pagar.me-Bestellung wurde storniert oder ist abgelaufen (zum Beispiel ein unbezahltes Boleto). Nur der letzte Versuch einer unbezahlten Bestellung kann sie auf Failed setzen. Der Kunde kann erneut bezahlen.

Refunded: Die Zahlung wurde bei Pagar.me erstattet oder storniert.

Jeder Pagar.me-Status wird genau einmal angewendet, sodass wiederholte Webhooks oder Rückkehren keine Notizen, E-Mails oder Bestandsreduzierungen hinzufügen. Eine bezahlte Bestellung wird nie wieder auf Pending payment oder Failed zurückgesetzt, und eine stornierte oder erstattete Bestellung wird nie wieder geöffnet. Wird eine zweite Pagar.me-Bestellung derselben WooCommerce-Bestellung bezahlt, weist eine Notiz Sie an, das Duplikat im Pagar.me-Dashboard zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Pagar.me (die Schaltfläche zeigt den Titel Ihrer Zahlungsart). Vollständige und teilweise Erstattungen von Karten- und PIX-Zahlungen werden unterstützt, bis zu dem Betrag, der bei Pagar.me noch erstattet werden kann. Die Erstattung wird mit dem Schlüssel des Modus gesendet, in dem die Zahlung erfolgt ist. Eine Erstattung wird nur erfasst, wenn Pagar.me sie bestätigt; andernfalls zeigt WooCommerce den Fehler an, zum Beispiel Pagar.me refused the refund: ... oder Pagar.me did not confirm the refund, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird den Bestellnotizen mit der Belastungs-ID hinzugefügt.

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 WooCommerce, ohne Refund via Pagar.me.

Eine vollständige Erstattung oder Stornierung im Pagar.me-Dashboard wird per Webhook übermittelt und setzt die Bestellung auf Refunded. Ein Chargeback fügt eine Notiz hinzu und setzt eine Bestellung im Status Processing oder Completed auf „On hold“.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Pagar.me. Fügen Sie den Schlüssel bei License key ein und klicken Sie auf Activate. Der Block zeigt den Status, etwa das Datum, bis zu dem die Lizenz gültig 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 auf einer 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 Pagar.me 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), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Eine Erinnerung erscheint auf der Seite Plugins und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren weiter.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, für Updates und Support ist aber eine Verlängerung nötig. Der Status wird im Hintergrund automatisch erneut geprüft.

Fehlerbehebung

Pagar.me erscheint nicht an der Kasse: 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 Livebetrieb) und die Shop-Währung BRL ist. Die Einstellungsseite zeigt in jedem dieser Fälle eine Warnung.

Die Zahlung ist erfolgt, die Bestellung bleibt aber auf Pending payment oder On hold: 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 in den Einstellungen angezeigten entspricht und ob die oben genannten Ereignisse ausgewählt sind. Die Bestellung wird außerdem geprüft, wenn der Kunde zum Shop zurückkehrt.

Der Webhook antwortet 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.

Der Webhook antwortet busy, retry later: Die Bestellung wurde im selben Moment durch eine andere Anfrage aktualisiert. Pagar.me wiederholt den Webhook.

Der Webhook antwortet unknown order: Die Pagar.me-Bestellung wurde nicht von diesem Shop angelegt, zum Beispiel eine Bestellung eines anderen Shops im selben Konto. Es wird nichts verändert.

Der Kunde sieht This order is already being processed: Ein Webhook oder die Rückkehr des Kunden aktualisierte die Bestellung im selben Moment. Der Kunde kann es nach einem Moment erneut versuchen.

Der Kunde sieht 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.

Der Kunde sieht Pagar.me could not start the payment: Pagar.me hat die Rechnungsdaten abgelehnt. Die Meldung nennt das Problem; der vollständige Grund steht in den Bestellnotizen.

Der Kunde sieht Pagar.me only supports payments in Brazilian Real (BRL): Die Bestellung ist in einer anderen Währung, zum Beispiel wegen eines Plugins zur Währungsauswahl.

Bestellung ist nach der Zahlung On hold: Lesen Sie die Bestellnotiz. Ein PIX oder Boleto wartet auf Zahlung, der bezahlte Betrag oder die Währung wich ab, oder die Zahlung kam nach der Stornierung der Bestellung.

Erstattung für ein Boleto schlägt fehl: Boleto-Zahlungen können nicht über die API erstattet werden. Erstatten Sie im Pagar.me-Dashboard und erfassen Sie die Erstattung manuell.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel etwa 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. Ist der Lizenzserver nicht erreichbar, 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. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen und die Protokolle des Plugins 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 Pagar.me-Daten.

Pagar.me ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Pagar.me verbunden noch von Pagar.me unterstützt.