VibeFox Iugu for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 8.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer.

Shopwährung: Brasilianischer Real (BRL). Iugu rechnet nur in BRL ab. Die Zahlungsmethode wird ausgeblendet, wenn der Shop oder die Bestellung auf der Seite Pay for order eine andere Währung verwendet, sowie bei Beträgen unter R$ 1,00 (dem Mindestbetrag von Iugu).

Iugu-Konto: Sie benötigen zwei API-Tokens aus dem Iugu-Dashboard, eines vom Typ "Test" und eines vom Typ "Live" (siehe Konfiguration). Iugu verwendet für beide eine API-Adresse: Das Token bestimmt, ob Rechnungen Test- oder echte Rechnungen sind. In Iugu muss kein Webhook eingerichtet werden.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert für eine Domain.

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Sie können auch den Ordner wcp_iugu_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Stellen Sie die Shopwährung unter WooCommerce > Settings > General auf Brasilianischer Real (BRL) ein.

4. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Iugu > Manage, oder klicken Sie auf der Plugins-Seite unter dem Plugin-Namen auf Settings.

5. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

6. Geben Sie die Test- und Live-API-Tokens ein (siehe Konfiguration), lassen Sie Test mode aktiviert, schalten Sie Enable / Disable ein und speichern Sie.

7. Legen Sie eine Testbestellung an und bezahlen Sie sie mit einer Iugu-Testkarte. Wenn alles bereit ist, deaktivieren Sie Test mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Iugu. Unter dem Titel des Gateways zeigt die Seite TEST MODE (Rechnungen werden mit dem Test-API-Token erstellt, es erfolgen keine echten Belastungen) oder LIVE an. Sie warnt, wenn das Token des aktiven Modus fehlt (die Zahlungsmethode wird dann an der Kasse ausgeblendet) und wenn die Shopwährung nicht BRL ist. In der Liste der Zahlungsmethoden ist Iugu als einrichtungsbedürftig markiert, bis das Token des aktiven Modus eingegeben ist, und zeigt ein Testmodus-Abzeichen, solange der Testmodus aktiv ist.

Allgemein

Enable / Disable: Enable Iugu payments schaltet die Zahlungsmethode ein oder aus. Standard: off.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Iugu.

Description: der Text unter der Zahlungsmethode an der Kasse. Standard: Pay securely via Iugu. You will be redirected to complete your payment.

API-Zugangsdaten

Erstellen Sie die API-Tokens in Iugu Alia (alia.iugu.com): Settings > API integration > New. Erstellen Sie ein Token vom Typ "Test" und eines vom Typ "Live".

Test mode: Use the test API token (no real charges). Standard: on. Solange der Testmodus aktiv ist, zeigt die Kasse SANDBOX — Test mode enabled. No real charges. über der Beschreibung an. Statusabfragen und Erstattungen einer Bestellung verwenden immer das Token des Modus, in dem ihre Rechnung erstellt wurde. Ein Moduswechsel bricht daher ältere Bestellungen nicht.

Test API token: das API-Token von Iugu vom Typ "Test". Es wird verwendet, solange der Testmodus aktiv ist.

Live API token: das API-Token von Iugu vom Typ "Live" (Produktion). Es wird verwendet, wenn der Testmodus deaktiviert ist. Halten Sie es geheim.

Zahlungsbenachrichtigungen

Jede Rechnung weist Iugu an, Statusänderungen an die Benachrichtigungs-URL Ihres Shops zu melden, die in diesem Bereich der Einstellungen angezeigt wird. Sie sieht so aus: https://your-site/wc-api/webhook_wc_iugu/. In Iugu ist nichts zu konfigurieren. Ein zusätzlicher kontoweiter Auslöser (gatilho), der auf dieselbe URL zeigt, ist unbedenklich. Die Benachrichtigungen enthalten keine Zahlungsdaten, denen der Shop vertraut: Die Rechnung wird vor jeder Bestellungsänderung immer über die Iugu-API gelesen (Status, Betrag, Währung).

Das Plugin reagiert auf die Iugu-Ereignisse, die einen Rechnungsstatus ändern können: invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action und invoices. Für jedes davon liest es die Rechnung und übernimmt ihren Status:

paid: die Bestellung wird nach der Prüfung von Betrag und Währung als bezahlt markiert.

authorized or in_analysis: die Kartenzahlung wartet auf die Erfassung oder wird geprüft. Die Bestellung wird auf „In Wartestellung“ gesetzt.

partially_paid: die Rechnung wurde teilweise bezahlt. Die Bestellung wird auf „In Wartestellung“ gesetzt.

expired: die Rechnung ist ohne Zahlung abgelaufen. Die Bestellung wird auf „Fehlgeschlagen“ gesetzt, und der Kunde kann erneut bezahlen.

canceled: die Rechnung wurde storniert. Die Bestellung wird storniert.

refunded: die Rechnung wurde in Iugu erstattet. Die Bestellung wird auf „Erstattet“ gesetzt.

chargeback: der Karteninhaber hat die Zahlung beanstandet. Eine bezahlte Bestellung wird auf „In Wartestellung“ gesetzt.

Andere Ereignisse und Rechnungen, die nicht zu einer Bestellung dieses Shops gehören, werden mit OK beantwortet und ignoriert. Ohne Benachrichtigungen wird eine Bestellung nur geprüft, wenn der Kunde von der Iugu-Seite in den Shop zurückkehrt.

Erweitert

Debug log: Log API requests and notifications unter WooCommerce > Status > Logs, Quelle wcp_iugu_gateway, ohne Tokens oder Kundendaten. Fehler werden immer protokolliert. Standard: off.

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

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Iugu) und gibt die Bestellung auf. Eine gültige E-Mail-Adresse für die Rechnung ist erforderlich. Das Plugin erstellt für den Bestellbetrag in BRL eine Iugu-Rechnung mit 3 Tagen Zahlungsfrist und leitet den Kunden auf die Iugu-Rechnungsseite weiter. Dort zahlt der Kunde per Kreditkarte, Boleto oder PIX, mit den Methoden, die in Ihrem Iugu-Konto aktiviert sind. Name und E-Mail-Adresse des Kunden werden an Iugu übergeben, außerdem CPF/CNPJ, Hausnummer und Ortsteil aus den Kassenfeldern von „Brazilian Market on WooCommerce“, sofern vorhanden. Telefonnummer und Adresse werden nur in dem Format übermittelt, das Iugu akzeptiert (brasilianische Telefonnummern, brasilianische Adressen mit 8-stelliger CEP).

Nach der Zahlung kehrt der Kunde auf die Seite „Bestellung eingegangen“ Ihres Shops zurück. Die Bestellung wird erst als bezahlt markiert, wenn Iugu bestätigt: Die Rechnung wird über die Iugu-API abgerufen, wenn der Kunde zurückkehrt und wenn Iugu eine Benachrichtigung sendet. Hat der Kunde einen Boleto- oder PIX-Code erzeugt und ist vor der Zahlung zurückgekehrt, wird die Bestellung auf „In Wartestellung“ gesetzt, bis Iugu die Zahlung bestätigt. Der Timer für unbezahlte Bestellungen in WooCommerce storniert keine Bestellungen, deren Iugu-Rechnung noch offen ist.

Wenn die Rechnung storniert wurde oder abgelaufen ist und die Bestellung noch bezahlt werden kann, landet der Kunde auf der Seite Pay for order mit dem Hinweis The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. Zahlt der Kunde erneut, schickt das Plugin ihn zur selben offenen Rechnung zurück, sofern sich der Betrag nicht geändert hat. Andernfalls storniert es die alte Rechnung in Iugu und erstellt eine neue, sodass eine Bestellung nicht über zwei offene Rechnungen doppelt bezahlt werden kann. Wird eine ältere Rechnung trotzdem bezahlt, bleibt die Zahlung der Bestellung zugeordnet.

Kann Iugu die Rechnung nicht erstellen, sieht der Kunde eine kurze Meldung, zum Beispiel Iugu could not create the invoice: mit dem Grund und der Bitte, die Rechnungsdaten zu prüfen, oder Could not connect to Iugu. Please try again in a moment. Der technische Grund wird den Bestellnotizen und dem Protokoll hinzugefügt.

Die Zahlungsmethode funktioniert in der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin verarbeitet nur Einmalzahlungen. Es bietet kein Kartenformular im Shop, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Abrechnungen, keine Carnês (Zahlungshefte), keine geteilten Zahlungen und keine Einstellungen für Ratenzahlungen. Dafür verwenden Sie die Einstellungen auf der Iugu-Seite. Die Zahlungsmethoden, die auf der Iugu-Seite angeboten werden, können in den Plugin-Einstellungen nicht ausgewählt werden: Angeboten werden alle Methoden, die in Ihrem Iugu-Konto aktiviert sind.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Die Rechnung wurde erstellt, und der Kunde hat noch nicht bezahlt.

Processing or Completed: Iugu hat die Zahlung bestätigt. WooCommerce setzt den üblichen Status für eine bezahlte Bestellung. Die Bestellnotiz zeigt die Rechnungs-ID von Iugu und die Zahlungsmethode (Kreditkarte, Boleto oder PIX). Die Transaktions-ID ist die Rechnungs-ID von Iugu, und in der Bestellansicht verlinkt sie auf die Rechnung in Iugu.

On hold: Der Kunde hat einen Boleto oder PIX erzeugt und ist in den Shop zurückgekehrt (Zahlung ausstehend), die Kartenzahlung ist autorisiert, aber noch nicht erfasst (erfassen Sie sie in Iugu; die Bestellung wird abgeschlossen, sobald Iugu die Rechnung als bezahlt meldet), die Zahlung wird geprüft, die Rechnung wurde nur teilweise bezahlt, ein Chargeback wurde eröffnet, oder der bezahlte Betrag bzw. die Währung stimmte nicht mit der Bestellung überein. Eine Zahlung, die nach der Stornierung der Bestellung eingeht, setzt sie ebenfalls auf „In Wartestellung“, statt sie stillschweigend wieder zu öffnen. Die Bestellnotizen zeigen, welcher Fall vorliegt.

Failed: Die Rechnung ist ohne Zahlung abgelaufen. Der Kunde kann die Bestellung erneut bezahlen.

Cancelled: Die Rechnung wurde in Iugu storniert.

Refunded: Die Rechnung, mit der die Bestellung bezahlt wurde, wurde in Iugu erstattet.

Wird eine weitere Rechnung derselben Bestellung ebenfalls bezahlt, wird die Bestellung nicht erneut geändert. Eine Notiz fordert Sie auf, die doppelte Zahlung in Iugu zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Iugu. Die Erstattung wird mit dem Token des Modus gesendet, in dem die Rechnung erstellt wurde.

Credit card: vollständige oder teilweise Erstattungen.

PIX: nur vollständige Erstattungen.

Boleto: kann nicht über Iugu erstattet werden. Zahlen Sie dem Kunden den Betrag per Banküberweisung zurück und erfassen Sie die Erstattung anschließend manuell, ohne Refund via Iugu zu verwenden.

Nur bezahlte Rechnungen können erstattet werden, und zwar höchstens den Betrag, der in Iugu noch erstattbar ist. Eine Erstattung gilt erst als erfolgt, wenn Iugu sie bestätigt. Lehnt Iugu die Erstattung ab oder bestätigt sie nicht, zeigt WooCommerce den Fehler an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit Rechnungs-ID und Grund in den Bestellnotizen vermerkt.

Eine vollständige Erstattung, die im Iugu-Dashboard vorgenommen wird, setzt die Bestellung auf „Erstattet“. Teilweise Erstattungen aus dem Dashboard werden nicht übernommen.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Iugu. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.

Ein Schlüssel funktioniert für eine Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Iugu 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 Zahlungsmethode weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Auf der Plugins-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

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

Fehlerbehebung

Iugu erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und das Token des aktiven Modus gesetzt ist: Test API token im Testmodus, Live API token im Livemodus. Die Shopwährung muss BRL sein, und der Bestellbetrag muss mindestens R$ 1,00 betragen. Die Einstellungsseite zeigt eine Warnung, wenn Token oder Währung falsch sind.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt Pending payment: Die Benachrichtigung von Iugu hat Ihren Shop nicht erreicht oder konnte nicht geprüft werden. Aktivieren Sie das Debug log und prüfen Sie WooCommerce > Status > Logs, Quelle wcp_iugu_gateway. Stellen Sie sicher, dass Ihre Website unter der in den Einstellungen angezeigten Benachrichtigungs-URL aus dem Internet erreichbar ist und das Token des Modus, in dem die Rechnung erstellt wurde, noch eingetragen ist. Die Bestellung wird auch geprüft, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Notification answers verification failed: Die Rechnung konnte in diesem Moment nicht über die Iugu-API gelesen werden, zum Beispiel wegen eines Netzwerkfehlers oder eines falschen Tokens. Iugu wiederholt die Benachrichtigung.

Notification answers invalid invoice id: Die Benachrichtigung enthielt keine gültige Rechnungs-ID. Es wird nichts geändert.

Bestellung ist On hold: Lesen Sie die Bestellnotizen. Ein Boleto oder PIX ist noch unbezahlt, eine Kartenzahlung wartet auf die Erfassung, die Zahlung wird geprüft, sie ist nur teilweise bezahlt oder angefochten, der bezahlte Betrag stimmte nicht mit der Bestellung überein, oder die Zahlung kam nach der Stornierung der Bestellung.

The customer sees "Iugu payments are not available right now": Das API-Token fehlt oder ist falsch. Prüfen Sie das Token des aktiven Modus.

Erstattung schlägt fehl: Lesen Sie die Meldung. Boleto-Zahlungen können nicht über Iugu erstattet werden, PIX-Zahlungen nur vollständig, und nur bezahlte Rechnungen können erstattet werden. Hat Iugu die Erstattung nicht bestätigt, prüfen Sie die Rechnung in Iugu, bevor Sie es erneut versuchen.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.

Entwickler können die Rechnungsanfrage anpassen, zum Beispiel die Zahlungsmethoden mit payable_with einschränken, über den Filter wc_igu_invoice_data.

Deinstallation

Die Deaktivierung des Plugins behält alle Daten. Zum vollständigen Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen und die Protokolle werden nur entfernt, wenn Delete Data on Uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Iugu ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Iugu verbunden noch wird es von Iugu unterstützt.