VibeFox Iugu for OpenCart — Hilfe

Voraussetzungen

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.

Währung: Brasilianischer Real (BRL). Iugu rechnet nur in BRL ab, daher muss der Shop die Währung BRL unter System > Localisation > Currencies haben. Die Zahlungsart wird ausgeblendet, wenn die Checkout-Währung des Kunden eine andere ist, und bei Summen unter R$ 1,00 (dem Mindestbetrag von Iugu).

Iugu-Konto: Sie benötigen zwei API-Token aus dem Iugu-Dashboard, einen vom Typ „Test“ und einen vom Typ „Live“ (siehe Configuration). Iugu verwendet für beide eine einzige API-Adresse: Das Token entscheidet, ob Rechnungen Test- oder echte Rechnungen sind. In Iugu muss kein Webhook eingerichtet werden.

CPF/CNPJ (optional): OpenCart hat kein eigenes CPF-Feld. Wenn Sie ein benutzerdefiniertes Feld für Kunden oder Adressen hinzufügen, dessen Name CPF oder CNPJ enthält (Customers > Custom Fields), wird sein Wert an Iugu übergeben.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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 OpenCart-3-Paket wcp_iugu_gateway-oc3-(version).ocmod.zip und das OpenCart-4-Paket wcp_iugu_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_iugu_gateway-oc3-(version).ocmod.zip. Die Erweiterung enthält keine OCMOD-Änderungen, daher muss Extensions > Modifications nicht aktualisiert werden. Statt des Installers können Sie auch den Inhalt des Ordners upload aus diesem Paket in das Stammverzeichnis Ihres Shops kopieren.

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

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

4. Geben Sie die Test- und Live-API-Token ein (siehe Configuration), lassen Sie Test mode eingeschaltet, aktivieren Sie Enable / Disable und klicken Sie auf Save.

5. Legen Sie eine Testbestellung in BRL an und bezahlen Sie sie auf der Iugu-Seite mit einer Iugu-Testzahlung. Wenn alles bereit ist, schalten Sie Test mode aus.

OpenCart 4

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_iugu_gateway.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Erweiterungscode 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 Iugu 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 API-Token ein 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 Zahlungsbenachrichtigungen).

Bei einer neuen Installation ist die Zahlungsart zunächst ausgeschaltet und der Testmodus eingeschaltet.

Konfiguration

Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Payments > VibeFox Iugu Gateway > Edit. Die Abschnitte stehen links; die Schaltfläche Save unter der Liste speichert die gesamte Seite. Oberhalb der Einstellungen zeigt die Seite TEST MODE (Rechnungen werden mit dem Test-API-Token erstellt, es werden keine echten Abbuchungen vorgenommen) oder LIVE an. Sie wird gewarnt, wenn das Token des aktiven Modus fehlt (die Zahlungsart wird dann im Checkout ausgeblendet) und wenn die Standardwährung des Shops nicht BRL ist (Iugu wird dann für andere Währungen nicht angeboten). Ohne das Recht, die Erweiterung zu bearbeiten, zeigt die Seite die Einstellungen an, kann sie aber nicht speichern.

Beim Speichern darf Title nicht leer sein und nicht länger als 128 Zeichen, Sort Order muss eine ganze Zahl sein, Total muss eine Zahl von 0 oder mehr sein, und die ausgewählte Geo Zone und die Bestellstatus müssen vorhanden sein. Andernfalls wird nichts gespeichert, und die Fehlermeldung nennt das Feld.

Iugu

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

Title: der Name der Zahlungsart, den Kunden im Checkout sehen. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Iugu. Pflichtfeld, bis zu 128 Zeichen.

Description: der Text, der Kunden im Schritt Confirm Order oberhalb der Bestätigungsschaltfläche angezeigt wird. Standard: Sicher bezahlen über Iugu. Sie werden weitergeleitet, um Ihre Zahlung abzuschließen.

Sort Order: die Position von Iugu unter den Zahlungsarten im Checkout. Lassen Sie das Feld leer oder geben Sie eine ganze Zahl ein.

Geo Zone: Iugu wird nur für Zahlungsadressen in der ausgewählten Geo Zone angeboten. Standard: All zones. Geo Zones werden unter System > Localisation > Geo Zones eingerichtet.

Total: die Checkout-Summe in der Standardwährung des Shops, die eine Bestellung erreichen muss, bevor Iugu angeboten wird. Leer lassen, um Iugu bei jeder Summe anzubieten. Iugu selbst benötigt mindestens R$ 1,00.

API-Zugangsdaten

Erstellen Sie die API-Token in Iugu Alia (der Abschnitt verlinkt dorthin): Settings > API integration > New. Erstellen Sie ein Token vom Typ „Test“ und eines vom Typ „Live“.

Test mode: verwendet das Test-API-Token, daher werden keine echten Abbuchungen vorgenommen. Standard: an. Solange der Testmodus eingeschaltet ist, sehen Kunden im Schritt Confirm Order oberhalb der Beschreibung SANDBOX — Test mode enabled. No real charges. Statusprüfungen und Erstattungen einer Bestellung verwenden immer das Token des Modus, in dem ihre Rechnung erstellt wurde. Ein Moduswechsel beschädigt daher keine älteren Bestellungen.

Test API token: das Iugu-API-Token vom Typ „Test“. Es wird verwendet, solange der Testmodus eingeschaltet ist.

Live API token: das Iugu-API-Token vom Typ „Live“ (Produktion). Es wird verwendet, wenn der Testmodus ausgeschaltet ist. Bewahren Sie es sicher 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: Jede Rechnung weist Iugu an, Statusänderungen an diese URL Ihres Shops zu melden. Auf OpenCart 3 sieht sie etwa so aus: https://your-store/index.php?route=extension/payment/wcp_iugu_gateway/webhook, auf OpenCart 4 so: https://your-store/index.php?route=extension/wcp_iugu_gateway/payment/wcp_iugu_gateway.webhook. Sie muss aus dem Internet erreichbar sein. In Iugu ist nichts einzurichten. Ein zusätzlicher kontoweiter Trigger, der auf dieselbe URL zeigt, schadet nicht. Die Benachrichtigungen enthalten keine Zahlungsdaten, denen der Shop vertraut: Die Rechnung wird immer über die Iugu-API (Status, Betrag, Währung) gelesen, bevor sich die Bestellung ändert.

Die Erweiterung reagiert auf die in diesem Abschnitt aufgeführten Iugu-Ereignisse: invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action und invoices. Bei jedem davon liest sie die Rechnung und wendet ihren Status an:

Eine abgelaufene oder stornierte Rechnung einer Bestellung ohne Status lässt die Bestellung ohne Status, damit der Kunde erneut bezahlen kann. Andere Ereignisse und Rechnungen, die nicht von Ihrem Shop erstellt wurden, werden mit HTTP 200 beantwortet und ignoriert, ohne eine Anfrage an Iugu zu senden. Ohne Benachrichtigungen wird eine Rechnung nur geprüft, wenn der Kunde von der Iugu-Seite in den Shop zurückkehrt.

Bestellungen

OpenCart legt die Bestellung im Schritt Confirm Order ohne Status an (eine fehlende Bestellung). Sie erhält erst dann einen Status, wenn Iugu die Rechnung gemeldet hat, per Benachrichtigung oder bei der Rückkehr des Kunden; die Rechnung wird immer über Iugu gelesen. Jedes Feld unten listet Ihre OpenCart-Bestellstatus auf.

Order Status After Payment: wird nach einer überprüften Iugu-Zahlung gesetzt. Standard: In Bearbeitung.

Awaiting Iugu Payment Status: Der Kunde kam mit einem ausgestellten Boleto oder PIX von der Iugu-Seite zurück; Iugu bestätigt den Zahlungseingang später. Standard: Ausstehend.

Iugu Payment On Hold Status: Kartenzahlung autorisiert, aber nicht erfasst, Zahlung in Prüfung, teilweise bezahlt, Chargeback, Betrag oder Währung weicht von der Bestellung ab oder Zahlung nach der Stornierung der Bestellung. Eine Notiz erklärt den Grund; prüfen Sie ihn manuell. Standard: Ausstehend, da OpenCart keinen Status „On hold“ hat. Sie können unter System > Localisation > Order Statuses einen eigenen Status anlegen und hier auswählen.

Invoice Expired Status: Die Rechnung einer wartenden Bestellung ist ohne Zahlung abgelaufen. Wenn Iugu sie später trotzdem als bezahlt meldet, erhält die Bestellung den Status nach der Zahlung. Standard: Fehlgeschlagen.

Invoice Canceled Status: Die Rechnung einer wartenden Bestellung wurde in Iugu storniert. Standard: Storniert.

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

Erweitert

Debug log: schreibt API-Anfragen und Benachrichtigungen in wc_igu_debug.log.php im Log-Ordner von OpenCart (storage/logs). Die Datei kann nicht über den Browser geöffnet werden. Token und Kundendaten (E-Mail, Telefon, CPF) werden nie protokolliert. Fehler und Warnungen werden immer geschrieben, auch wenn der Schalter aus ist. 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 der Erweiterung die Einstellungen der Zahlungsart und das Log. Bestellungen, Iugu-Rechnungsreferenzen und Erstattungen bleiben immer erhalten, sodass alte Bestellungen nach einer erneuten Installation weiter funktionieren. Standard: aus.

Import / Export

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

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

Checkout

Im Schritt Payment Method wählt der Kunde die Zahlungsart (standardmäßig Iugu). Im Schritt Confirm Order sieht der Kunde Ihre Beschreibung und den Hinweis You will be redirected to the Iugu invoice page to pay by credit card, boleto or PIX. OpenCart legt die Bestellung in diesem Schritt an, noch ohne Status. Wenn der Kunde auf Confirm Order klickt, erstellt die Erweiterung eine Iugu-Rechnung über die Bestellsumme in BRL mit 3 Tagen Fälligkeit und leitet den Kunden zur Iugu-Rechnungsseite weiter. Eine gültige E-Mail-Adresse ist erforderlich. Die Rechnung zeigt Order # und die Bestellnummer. Dort bezahlt 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 die CPF/CNPJ aus einem benutzerdefinierten Feld namens CPF oder CNPJ, wenn sie 11 oder 14 Ziffern hat. Telefon und Adresse werden nur in dem Format gesendet, das Iugu akzeptiert (brasilianische Telefonnummern, brasilianische Adressen mit einer 8-stelligen CEP; die Hausnummer wird als s/n übertragen).

Auf 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 Kasse auf Confirm Order. Standardmäßig fragt OpenCart 4 nicht nach einer Zahlungsadresse; die Erweiterung übernimmt dann die Adresse und das benutzerdefinierte Feld CPF/CNPJ der Lieferadresse.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Iugu die Zahlung bestätigt: Die Rechnung wird über die Iugu-API gelesen, wenn der Kunde zurückkehrt und wenn Iugu eine Benachrichtigung sendet. 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.

Hat der Kunde einen Boleto- oder PIX-Code erzeugt und ist vor der Zahlung zurückgekommen, erhält die Bestellung den Awaiting Iugu Payment Status, und die Erfolgsseite zeigt Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. Die Bestellung wechselt in den bezahlten Status, sobald Iugu den Zahlungseingang meldet, per Benachrichtigung oder wenn der Kunde den Rücklink erneut öffnet. Bei einer Bestellung in Prüfung zeigt die Erfolgsseite We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. Konnte Iugu nicht erreicht werden oder hat die Zahlung bei der Rückkehr des Kunden noch nicht gemeldet, zeigt eine Seite Payment confirmation denselben Text mit den Schaltflächen Check again und Back to checkout.

Wenn die Rechnung storniert wurde oder abgelaufen ist, kehrt der Kunde zum Checkout zurück, mit der Meldung The Iugu invoice was not paid (it was canceled or has expired). Your cart is kept: confirm the order again to pay. Wurde die Bestellung storniert, weil ihre Iugu-Rechnung storniert wurde, lautet die Meldung Your order was cancelled because its Iugu invoice was canceled. Ist der Warenkorb bereits leer (eine Boleto- oder PIX-Bestellung hatte die Erfolgsseite erreicht, bevor ihre Rechnung abgelaufen ist), sieht der Kunde stattdessen eine Seite Payment confirmation mit The Iugu invoice of order #... was not paid (it was canceled or has expired), so the order will not be shipped. To buy these items, please place a new order. (oder die Meldung zur Stornierung) und einer Schaltfläche Continue. Auf OpenCart 4 werden die Meldungen des Checkouts über der Kasse angezeigt. OpenCart 3 legt jedes Mal eine neue Bestellung an, wenn der Schritt Confirm Order angezeigt wird; OpenCart 4 aktualisiert die Bestellung der Kasse, sodass der Kunde nach einer abgelaufenen oder stornierten Rechnung dieselbe Bestellung mit einer neuen Rechnung bezahlt. Ein Warenkorb wird nur einmal bezahlt. Vor einer neuen Rechnung prüft die Erweiterung die früheren Rechnungen des Warenkorbs: Ist eine bezahlt, wird diese Zahlung übernommen und der Kunde gelangt zur Erfolgsseite; hat dieselbe Bestellung noch eine offene Rechnung mit demselben Betrag und Modus, wird der Kunde dorthin zurückgeschickt; andere offene Rechnungen werden in Iugu storniert. Wird eine ältere Rechnung trotzdem bezahlt, wird die Zahlung dennoch zugeordnet, und eine doppelte Zahlung für einen bereits bezahlten Warenkorb wird mit einer Notiz markiert. Eine Änderung des Warenkorbs, auch eine neue Menge, gilt als neuer Warenkorb, der eine eigene Zahlung braucht.

OpenCart 4 behält die Bestellung in der Kasse, bis die Erfolgsseite angezeigt wird. Wurde diese Bestellung inzwischen geschlossen (zum Beispiel ist ihr Boleto abgelaufen oder Sie haben sie storniert), wird der Kunde mit The Iugu invoice was not paid (it was canceled or has expired). Your cart is kept: confirm the order again to pay. zurück zur Kasse geschickt, oder, falls sie 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. Ist die Bestellung bereits aufgegeben und der Warenkorb enthält inzwischen einen neuen Kauf, lädt Confirm Order die Kassenseite neu. In jedem Fall bezahlt das nächste Confirm Order eine neue Bestellung des Warenkorbs.

Kann Iugu die Rechnung nicht erstellen, bleibt der Kunde im Schritt Confirm Order mit einer kurzen 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 im Log festgehalten.

Die Benachrichtigungs-URL funktioniert auch, während 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 Benachrichtigung und die Rückkehr des Kunden durchlässt.

Die Erweiterung unterstützt nur Einmalzahlungen. Sie hat kein Kartenformular im Shop, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Abrechnungen, keine Zahlungsheftchen (carnê), keine geteilten Zahlungen und keine Ratenzahlungseinstellungen — nutzen Sie für Raten die Einstellungen der Iugu-Seite. Die Zahlungsarten, die auf der Iugu-Seite angeboten werden, lassen sich in den Einstellungen der Erweiterung nicht auswählen: Angeboten werden alle Zahlungsarten, die in Ihrem Iugu-Konto aktiviert sind.

Bestellungen und Erstattungen

Bestellstatus

Kein Status (fehlende Bestellung): Der Kunde wurde zu Iugu weitergeleitet und hat nicht bezahlt, die Rechnung ist abgelaufen oder wurde storniert, oder Iugu hat die Zahlung noch nicht bestätigt. Unter Sales > Orders werden solche Bestellungen nur mit dem Filter Order Status auf Missing Orders angezeigt.

Order Status After Payment (Standard In Bearbeitung): Iugu hat die Zahlung bestätigt. Eine Notiz zeigt die Rechnungs-ID und die Zahlungsart (Kreditkarte, Boleto oder PIX).

Awaiting Iugu Payment Status (Standard Ausstehend): Der Kunde kam mit einem ausgestellten Boleto oder PIX zurück. Die Bestellung wechselt in den bezahlten Status, sobald Iugu die Zahlung meldet.

Iugu Payment On Hold Status (Standard 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, Iugu hat einen anderen Betrag oder eine andere Währung als die Bestellung gemeldet, oder die Zahlung ist nach der Stornierung der Bestellung eingegangen. Die Notizen erklären es. Prüfen Sie die Bestellung und erfüllen Sie sie oder erstatten Sie die Zahlung.

Invoice Expired Status (Standard Fehlgeschlagen): Die Rechnung einer wartenden Bestellung ist ohne Zahlung abgelaufen. Meldet Iugu die Rechnung später trotzdem als bezahlt, wechselt die Bestellung in den bezahlten Status.

Invoice Canceled Status (Standard Storniert): Die Rechnung einer wartenden Bestellung wurde in Iugu storniert.

Refunded Status (Standard Erstattet): Die Zahlung wurde über die Erweiterung oder im Iugu-Dashboard vollständig erstattet.

Ist eine weitere Rechnung derselben Bestellung oder desselben Warenkorbs ebenfalls bezahlt, wird die Bestellung nicht verändert. Eine Notiz fordert Sie auf, die doppelte Zahlung in Iugu zu erstatten. Notizen sind Einträge im History der Bestellung, die der Kunde nicht sieht. Wird eine wartende Bestellung später bezahlt, läuft ab oder wird storniert, benachrichtigt OpenCart den Kunden über den neuen Status.

Registerkarte VibeFox Iugu Gateway

Öffnen Sie unter Sales > Orders eine mit Iugu bezahlte Bestellung. Unten auf der Bestellseite, neben History und Additional, zeigt die Registerkarte VibeFox Iugu Gateway die Iugu invoice-ID (mit Link zur Rechnung in Iugu) mit einem Hinweis Test mode bei Testrechnungen, die Payment method, den Status, die Beträge Paid / refunded, das Erstattungsformular, den Erstattungsverlauf und die Iugu notes der Bestellung. Die Registerkarte wird Benutzern angezeigt, die Zugriff auf die Erweiterung haben.

Erstattungen

Geben Sie auf der Registerkarte VibeFox Iugu Gateway den Amount ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Reason (optional), und klicken Sie auf Refund via Iugu. Bestätigen Sie die Frage Refund this amount through Iugu? This cannot be undone. Sie benötigen das Recht, die Erweiterung zu bearbeiten (festgelegt unter System > Users > User Groups). Die Erstattung wird mit dem Token des Modus gesendet, in dem die Rechnung erstellt wurde; dieses Token muss daher eingetragen sein.

Erstattungen beziehen sich auf den Betrag, den Iugu für die Rechnung tatsächlich eingezogen hat. Nach einer Betragsabweichung können Sie daher bis zu dem Betrag erstatten, den der Kunde bezahlt hat, nicht die Bestellsumme. Erstattet werden können nur bezahlte Rechnungen, und nicht mehr als der in Iugu noch erstattbare Betrag. Eine Erstattung gilt erst als erledigt, wenn Iugu sie bestätigt. Lehnt Iugu die Erstattung ab oder bestätigt sie nicht, zeigt die Registerkarte den Fehler, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit Rechnungs-ID und Grund in den Erstattungsverlauf und die Notizen aufgenommen. Eine vollständige Erstattung setzt die Bestellung auf Refunded Status, ohne den Kunden zu benachrichtigen und ohne Produkte wieder in den Bestand zu buchen, wie eine manuelle Statusänderung. Eine Teilerstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Iugu die Rechnung als bezahlt gemeldet hat.

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

Eine im Iugu-Dashboard vorgenommene vollständige Erstattung setzt die Bestellung mit einer Notiz auf Refunded Status. Teilerstattungen aus dem Dashboard werden nicht übernommen.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Iugu Gateway ist der erste Block unter Extensions > Extensions > Payments > VibeFox Iugu Gateway > Edit, oberhalb der Einstellungen. Fügen 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 zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-payment-iugu 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 Blocks folgen der Sprache des Admin-Bereichs (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 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 auf einer Domain: der Shop-Adresse aus der OpenCart-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Iugu Kunden im Checkout nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Ein Admin-Benutzer, der im Admin-Bereich im selben Browser angemeldet ist, 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 gibt es diese Vorschau nicht: Der Shop sieht die Admin-Anmeldung nicht, daher ist die Zahlungsart ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint auf dem Dashboard des Admin-Bereichs 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, Updates und Support benötigen jedoch eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard oder die Seite Edit des Admin-Bereichs öffnen: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Die Deinstallation der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Iugu erscheint nicht im Checkout: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und das Token des aktiven Modus eingetragen ist: Test API token im Testmodus, Live API token im Live-Modus. Die Checkout-Währung des Kunden muss BRL sein und die Summe mindestens R$ 1,00 betragen. 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. Die Einstellungsseite zeigt eine Warnung, wenn das Token oder die Währung falsch ist.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt ohne Status: Die Benachrichtigung von Iugu hat Ihren Shop nicht erreicht oder konnte nicht geprüft werden. Schalten Sie den Debug log ein und sehen Sie sich das Feld Log auf der Erweiterungsseite an. Prüfen Sie, ob Ihr Shop unter der Notification URL aus dem Internet erreichbar ist und ob das Token des Modus, in dem die Rechnung erstellt wurde, noch eingetragen ist. Die Rechnung wird auch geprüft, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Die Benachrichtigung meldet verification failed: Die Rechnung konnte in diesem Moment nicht über die Iugu-API gelesen werden, zum Beispiel wegen eines Netzwerkfehlers, eines falschen Tokens oder eines fehlenden Tokens für den Modus der Rechnung. Iugu wiederholt die Benachrichtigung.

Die Benachrichtigung meldet busy: Der Warenkorb wurde gleichzeitig von einer anderen Anfrage verarbeitet, oder der Bestellstatus konnte nicht gesetzt werden. Iugu wiederholt die Benachrichtigung. Das Log zeigt den Grund.

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

Die Bestellung ist im Iugu Payment On Hold Status: Lesen Sie die Iugu notes in der Registerkarte der Bestellung. Eine Kartenzahlung wartet auf die Erfassung, die Zahlung wird geprüft, ist teilweise bezahlt oder angefochten, der bezahlte Betrag stimmte nicht mit der Bestellung überein, oder die Zahlung kam nach der Stornierung der Bestellung.

Der Kunde sieht „Iugu payments are not available right now“: Das API-Token fehlt oder ist falsch. Prüfen Sie das Token des aktiven Modus.

Der Kunde sieht „A valid billing email is required for Iugu“: Die Bestellung hat keine gültige E-Mail-Adresse.

Der Kunde sieht „This order already has an Iugu payment that the store has to review“: Eine frühere Rechnung der Bestellung ist autorisiert, in Prüfung oder teilweise bezahlt. Prüfen Sie die Rechnung in Iugu und das Log.

Der Kunde sieht This payment method is not available.: Die Checkout-Sitzung passt nicht mehr zur Bestellung, oder die Zahlungsart wurde inzwischen deaktiviert. Der Kunde lädt den Checkout neu.

Erstattung schlägt fehl: Lesen Sie die Meldung in der Registerkarte. Boleto-Zahlungen können nicht über Iugu erstattet werden, PIX-Zahlungen nur vollständig, und nur bezahlte Rechnungen können erstattet werden. Sagt die Meldung, die Zahlung wurde im Test- oder Live-Modus gemacht und es ist kein Token eingerichtet, tragen Sie das Token dieses Modus ein. Hat Iugu die Erstattung nicht bestätigt, prüfen Sie die Rechnung in Iugu, bevor Sie es erneut versuchen.

Für Entwickler: Vor der Erstellung der Rechnung löst die Erweiterung das OpenCart-Ereignis wc_igu_invoice_data mit der Rechnungsanfrage und der Bestellung aus, zum Beispiel um die Zahlungsarten mit payable_with einzuschränken.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments und klicken Sie neben VibeFox Iugu 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 erneuten Installation auf ihre Standardwerte zurückgesetzt werden. Das OpenCart-Ereignis der Erweiterung wird ebenfalls entfernt (auf OpenCart 4 zusätzlich deren Ereignisse und Startup-Aktion, die Benachrichtigung und Kundenrückkehr im Wartungsmodus durchlässt). Ist Delete data on uninstall eingeschaltet, werden die übrigen Einstellungen der Zahlungsart (Titel, Beschreibung, Testmodus, API-Token, Schalter für das Debug-Log) und das Log entfernt. Ist es aus, bleiben sie für eine spätere Neuinstallation erhalten. Die Iugu-Rechnungsreferenzen und Erstattungen bleiben immer erhalten, sodass früher bezahlte Bestellungen weiterhin erstattet werden können und späte Benachrichtigungen nach einer Neuinstallation weiter zugeordnet werden. 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 neben VibeFox Iugu Gateway in der Liste der installierten Erweiterungen auf Uninstall (die orangefarbene −-Schaltfläche). Klicken Sie dann auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

Iugu ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit Iugu verbunden und wird von Iugu nicht unterstützt.