VibeFox Iugu for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

Währung: Brasilianischer Real (BRL). Iugu rechnet nur in BRL ab. Die Zahlungsmethode wird für Warenkörbe in einer anderen Währung und für Summen unter R$ 1,00 (das Iugu-Minimum) ausgeblendet.

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 beides eine einzige API-Adresse: Das Token entscheidet, ob Rechnungen Test- oder echte Rechnungen sind. In Iugu muss kein Webhook eingerichtet werden.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel funktioniert auf einer Domain.

Installation

1. Gehen Sie im Back Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls aus.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure oder suchen Sie später VibeFox Iugu Gateway in der Modulliste und klicken Sie dort auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel im Feld License key des Lizenzblocks oben auf der Konfigurationsseite ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie die Test- und Live-API-Tokens ein (siehe Konfiguration), lassen Sie Test mode aktiviert, schalten Sie Enable / Disable ein und klicken Sie auf Save.

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

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Iugu payment und Iugu payment on hold. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken. Iugu wird in jedem Fall nur für Warenkörbe in BRL angeboten.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Iugu Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Über den Feldern zeigt die Seite TEST MODE (Rechnungen werden mit dem Test-API-Token erstellt, ohne echte Abbuchungen) oder LIVE an. Sie warnt, wenn das Token des aktiven Modus fehlt (die Zahlungsmethode wird dann an der Kasse ausgeblendet), und wenn die Standardwährung des Shops nicht BRL ist (Iugu wird dann für Warenkörbe in anderen Währungen nicht angeboten).

Iugu

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

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Iugu. Pflichtfeld.

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: verwendet das Test-API-Token, sodass keine echten Abbuchungen erfolgen. 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 beeinträchtigt daher ältere Bestellungen nicht.

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

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

Gespeicherte Tokens 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.

Clear saved tokens: Markieren Sie ein Token und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert bei.

Zahlungsbenachrichtigungen

Notification URL: Jede Rechnung weist Iugu an, Statusänderungen an diese URL Ihres Shops zu melden. Mit SEO-URLs sieht sie so aus: https://your-shop/module/wcp_iugu_gateway/webhook. In Iugu ist nichts zu konfigurieren. Ein zusätzlicher kontoweiter Trigger (gatilho), der auf dieselbe URL zeigt, ist unschädlich. Die Benachrichtigungen enthalten keine Zahlungsdaten, denen der Shop vertraut: Die Rechnung wird immer über die Iugu-API erneut abgerufen (Status, Betrag, Währung), bevor eine Bestellung angelegt oder geändert wird.

Das Modul 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 wendet ihren Status an:

paid: Die Bestellung wird als bezahlt angelegt (oder wechselt in den Status „bezahlt“), nachdem Betrag und Währung geprüft wurden.

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

partially_paid: Die Rechnung wurde teilweise bezahlt. Die Bestellung wird auf Wartestellung gesetzt.

expired: Die Rechnung ist ohne Zahlung abgelaufen. Eine wartende Bestellung erhält Payment error.

canceled: Die Rechnung wurde storniert. Eine wartende 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 Wartestellung gesetzt.

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 dann geprüft, wenn der Kunde von der Iugu-Seite in den Shop zurückkehrt.

Erweitert

Debug log: schreibt Iugu-Anfragen und Benachrichtigungen in logs/wc_igu_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Tokens und Kundendaten werden nicht protokolliert. Fehler und Warnungen werden immer geschrieben, auch wenn der Schalter aus ist. Standard: off.

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

Delete Data on Uninstall: Wenn aktiviert, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und das Protokoll. Bestellungen, Iugu-Rechnungsreferenzen, Erstattungen und die Bestellstatus des Moduls bleiben immer erhalten, sodass alte Bestellungen nach einer Neuinstallation weiterhin funktionieren. Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Iugu) und bestätigt. Eine gültige E-Mail-Adresse des Kunden ist erforderlich. Das Modul erstellt eine Iugu-Rechnung über die Warenkorbsumme in BRL mit einer Fälligkeit von 3 Tagen und leitet den Kunden auf die Rechnungsseite von Iugu weiter. Dort bezahlt der Kunde per Kreditkarte, Boleto oder PIX, mit den Methoden, die in Ihrem Iugu-Konto aktiviert sind. Die Rechnung zeigt Order # und die Warenkorbnummer. Name und E-Mail-Adresse des Kunden werden an Iugu übermittelt, außerdem Firma und CPF/CNPJ aus dem Feld Identification number oder VAT number der Adresse, sofern vorhanden. Telefonnummer und Adresse werden nur in dem Format übermittelt, das Iugu akzeptiert (brasilianische Telefonnummern, brasilianische Adressen mit 8-stelliger CEP; die Hausnummer wird als s/n übermittelt). Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Iugu dies bestätigt: Die Rechnung wird über die Iugu-API abgerufen, wenn der Kunde zurückkehrt, und wenn Iugu eine Benachrichtigung sendet. Danach wird die Bestellung angelegt, und der Kunde sieht die Standard-Bestellbestätigungsseite mit Your payment with Iugu has been received.

Hat der Kunde einen Boleto- oder PIX-Code erzeugt und ist vor der Zahlung zurückgekehrt, wird die Bestellung in Awaiting Iugu payment angelegt, und die Bestätigungsseite zeigt Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. Die Bestellung wechselt zu Payment accepted, sobald Iugu den Zahlungseingang meldet, per Benachrichtigung oder wenn der Kunde den Rücksprunglink erneut öffnet. Konnte Iugu bei der Rückkehr des Kunden noch nicht erreicht werden, zeigt eine Seite Payment confirmation an: We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. mit einer Schaltfläche Check again und einer Schaltfläche Back to checkout. Eine Bestellung, deren Rechnung storniert wurde oder ohne Zahlung abgelaufen ist, zeigt auf der Bestätigungsseite Your Iugu payment was not completed. Please contact us about this order.

Wurde die Rechnung storniert oder ist sie abgelaufen, bevor eine Bestellung existiert, kehrt der Kunde zur Kasse zurück und sieht The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. Der Warenkorb bleibt erhalten. Wenn der Kunde erneut bezahlt, leitet das Modul ihn zur selben offenen Rechnung weiter, sofern Betrag und Modus unverändert sind. Andernfalls storniert es die alte Rechnung in Iugu und erstellt eine neue, sodass ein Warenkorb nicht über zwei offene Rechnungen doppelt bezahlt werden kann. Wird eine ältere Rechnung trotzdem bezahlt, wird die Zahlung weiterhin dem Warenkorb zugeordnet.

Kann Iugu die Rechnung nicht erstellen, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel Iugu could not create the invoice: mit dem Grund und einer Aufforderung, die Rechnungsdaten zu prüfen, oder Could not connect to Iugu. Please try again in a moment. Der technische Grund wird im Protokoll festgehalten.

Die Benachrichtigungs-URL funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

Das Modul 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 Ratenzahlungseinstellungen. Für Raten verwenden Sie die Einstellungen der Iugu-Seite. Die Zahlungsmethoden auf der Iugu-Seite können in den Moduleinstellungen nicht ausgewählt werden: Es werden alle Methoden angeboten, die in Ihrem Iugu-Konto aktiviert sind. Eine Bestellung mit Payment error oder Canceled kann nicht aus dem Shop heraus erneut bezahlt werden; der Kunde gibt eine neue Bestellung auf.

Bestellungen und Erstattungen

Bestellstatus

No order yet: Der Kunde wurde zu Iugu weitergeleitet und hat noch nicht bezahlt, oder Iugu hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted: Iugu hat die Zahlung bestätigt. Die Zahlung wird mit der Iugu-Rechnungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Rechnungs-ID und die Zahlungsmethode (Kreditkarte, Boleto oder PIX).

Awaiting Iugu payment: Der Kunde ist mit einem ausgestellten Boleto oder PIX zurückgekehrt. Die Bestellung wechselt zu Payment accepted, sobald Iugu die Zahlung meldet.

Iugu payment on hold: 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 im Warenkorb gemeldet (zum Beispiel weil der Warenkorb nach der Erstellung der Rechnung geändert wurde) oder die Zahlung ist eingegangen, nachdem die Bestellung storniert worden war. Die Notizen erklären den Grund. Prüfen Sie die Bestellung und erfüllen Sie sie oder erstatten Sie die Zahlung.

Payment error: Die Rechnung einer wartenden Bestellung ist ohne Zahlung abgelaufen. Meldet Iugu die Rechnung später doch als bezahlt, wechselt die Bestellung zu Payment accepted.

Canceled: Die Rechnung einer wartenden Bestellung wurde in Iugu storniert.

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

Wird eine weitere Rechnung desselben Warenkorbs ebenfalls bezahlt, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, die doppelte Zahlung in Iugu zu erstatten.

Iugu-Zahlungsblock

Die Bestellseite zeigt einen Block Iugu payment mit der Iugu-Rechnungs-ID (verlinkt mit der Rechnung in Iugu), der Zahlungsmethode, dem Status, dem von Iugu eingezogenen Betrag und dem erstatteten Betrag, einem Kennzeichen Test mode für Testrechnungen, dem Erstattungsverlauf und den Iugu notes der Bestellung.

Erstattungen

Geben Sie im Block Iugu payment den Betrag ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Grund, 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, Bestellungen zu bearbeiten. Die Erstattung wird mit dem Token des Modus gesendet, in dem die Rechnung erstellt wurde, daher muss dieses Token eingerichtet sein.

Kreditkarte: vollständige oder teilweise Erstattungen.

PIX: nur vollständige Erstattungen.

Boleto: kann nicht über Iugu erstattet werden. Erstatten Sie dem Kunden den Betrag per Banküberweisung.

Erstattungen beziehen sich auf den Betrag, den Iugu tatsächlich für die Rechnung eingezogen hat. Nach einer Betragsabweichung können Sie daher bis zum tatsächlich gezahlten Betrag des Kunden erstatten, nicht bis zur Bestellsumme. Nur bezahlte Rechnungen können erstattet werden, 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 der Block den Fehler an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der Rechnungs-ID und dem Grund hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine Teilerstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Iugu die Rechnung als bezahlt gemeldet hat.

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

Eine vollständige Erstattung, die im Iugu-Dashboard vorgenommen wird, setzt die Bestellung auf Refunded mit einer Notiz. Teilerstattungen aus dem Dashboard werden nicht importiert.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Iugu Gateway ist der erste Block unter Modules > Module Manager > VibeFox Iugu Gateway > Configure, oberhalb der Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-iugu und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, nennt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nach einer Änderung der Shopadresse oder nachdem Sie einen Domainplatz in Ihrem Konto freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Iugu Kunden an der Kasse nicht angezeigt. Versucht ein Kunde dennoch eine Zahlung, sieht er This payment method is not available. Please choose another one. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher wird die Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber nicht an der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird während der Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cronjob ist nicht nötig. Beim Deinstallieren oder Zurücksetzen des Moduls werden Lizenzschlüssel und Lizenzstatus immer entfernt.

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 Live-Modus. Die Warenkorbwährung muss BRL sein und die Summe mindestens R$ 1,00 betragen. Prüfen Sie unter Payment > Preferences, ob das Modul für die Währung BRL, das Land des Kunden und die Kundengruppe erlaubt ist. Die Einstellungsseite zeigt eine Warnung, wenn das Token oder die Währung falsch ist.

Die Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: Die Benachrichtigung von Iugu hat Ihren Shop nicht erreicht oder konnte nicht geprüft werden. Aktivieren Sie Debug log und sehen Sie sich das Feld Log auf der Modulseite 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.

Notification answers 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.

Notification answers busy: Der Warenkorb wurde im selben Moment von einer anderen Anfrage verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). Iugu wiederholt die Benachrichtigung. Das Protokoll zeigt den Grund.

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

Bestellung im Status Iugu payment on hold: Lesen Sie die Iugu notes im Bestellblock. Eine Kartenzahlung wartet auf Erfassung, die Zahlung wird geprüft, ist teilweise bezahlt oder angefochten, der bezahlte Betrag stimmt nicht mit dem Warenkorb überein oder die Zahlung kam, nachdem die Bestellung storniert wurde.

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 „This order already has an Iugu payment that the store has to review“: Eine frühere Rechnung des Warenkorbs ist autorisiert, in Prüfung oder teilweise bezahlt, aber es konnte keine Bestellung angelegt werden. Prüfen Sie die Rechnung in Iugu und das Protokoll.

Erstattung schlägt fehl: Lesen Sie die Meldung im Block. Boleto-Zahlungen können nicht über Iugu erstattet werden, PIX-Zahlungen nur vollständig, und nur bezahlte Rechnungen können erstattet werden. Wenn die Meldung besagt, dass die Zahlung im Test- oder Live-Modus erfolgte und kein Token eingerichtet ist, geben Sie das Token dieses Modus ein. Wenn Iugu die Erstattung nicht bestätigt hat, prüfen Sie die Rechnung in Iugu, bevor Sie es erneut versuchen.

Entwickler können die Rechnungsanfrage ändern, zum Beispiel die Zahlungsmethoden mit payable_with einschränken, im Hook actionWcpIuguInvoiceData.

Deinstallation

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

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