VibeFox Niubiz for WooCommerce — Hilfe

Voraussetzungen

WordPress: 5.8 oder neuer.

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

PHP: 8.0 oder neuer.

Shopwährung: peruanische Sol (PEN) oder US-Dollar (USD). Bei anderen Währungen wird die Zahlungsart an der Kasse ausgeblendet.

Niubiz-Konto: Niubiz stellt für jede Umgebung eine merchant ID (código de comercio), einen API user und ein API password aus. Sandbox-Zugangsdaten erhalten Sie vom Integrationsteam von Niubiz, Produktionszugangsdaten nach der Zertifizierung Ihrer Integration durch Niubiz. Ein Webhook muss nicht eingerichtet werden: Niubiz beantwortet die Autorisierung sofort.

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. Alternativ können Sie den Ordner wcp_niubiz_payment per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

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

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

5. Lassen Sie Sandbox mode eingeschaltet und geben Sie merchant ID, API user und API password der Sandbox ein (siehe Konfiguration).

6. Schalten Sie Enable/Disable ein und führen Sie einige Testzahlungen mit den Niubiz-Testkarten durch.

7. Nachdem Niubiz Ihre Integration zertifiziert hat, geben Sie die Produktionszugangsdaten ein und deaktivieren Sie Sandbox mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Niubiz. Oberhalb der Felder warnt die Seite, wenn die Shopwährung weder PEN noch USD ist oder wenn die Zugangsdaten des aktuellen Modus unvollständig sind (in beiden Fällen wird die Zahlungsart an der Kasse ausgeblendet). Solange der Sandbox-Modus eingeschaltet ist, zeigt sie außerdem Der Sandbox-Modus ist aktiv: Zahlungen gehen an die Niubiz-Sandbox, und es werden keine echten Belastungen vorgenommen. In der Liste der Zahlungsarten wird Niubiz als einrichtungsbedürftig markiert, bis der aktuelle Modus vollständige Zugangsdaten hat.

Allgemein

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

Title: der Name der Zahlungsart, den der Kunde an der Kasse sieht. Standard: Credit or debit card (Niubiz).

Description: der Text, der an der Kasse unter der Zahlungsart angezeigt wird. Standard: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

Niubiz-Zugangsdaten

Niubiz stellt Ihnen eine merchant ID, einen API user und ein API password für die Sandbox und nach der Zertifizierung für die Produktion bereit. Die Entwicklerdokumentation finden Sie unter desarrolladores.niubiz.com.pe.

Sandbox mode: Use the Niubiz sandbox (QA) environment — no real charges. Schaltet sowohl die API-Endpunkte als auch die unten stehenden Zugangsdaten um. Standard: ein. Zum Akzeptieren echter Zahlungen deaktivieren.

Sandbox merchant ID: der Händlercode Ihres Sandbox-Kontos, nur Ziffern. Leerzeichen werden entfernt. Enthält der Wert andere Zeichen, zeigt die Einstellungsseite einen Fehler und behält den bisherigen Wert.

Sandbox API user: der API user der Sandbox.

Sandbox API password: das API password der Sandbox.

Production merchant ID: der Händlercode Ihres Produktionskontos (angeschlossen), nur Ziffern.

Production API user: der API user der Produktion.

Production API password: das API password der Produktion.

Zahlungsformular

Logo URL: optionale HTTPS-Adresse Ihres Logos, das im Niubiz-Zahlungsformular angezeigt wird, etwa 187 × 40 px. Ohne diese Angabe wird der Shopname angezeigt. Eine Adresse, die nicht mit https:// beginnt, wird abgelehnt und der bisherige Wert bleibt erhalten.

Erweitert

Debug log: Log API calls schreibt die Niubiz-Anfragen unter WooCommerce > Status > Logs, Quelle wcp_niubiz_payment. Fehler werden immer protokolliert. Zugangsdaten, Token sowie Karten- und Kundendaten werden nie protokolliert. Standard: aus.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted. Das Deaktivieren löscht nie etwas. Zahlungsdaten, die in Bestellungen gespeichert sind, bleiben erhalten. Standard: aus.

Einstellungen aus Version 1.0, die nur einen Satz Zugangsdaten hatten, werden automatisch übernommen: in die Sandbox-Felder, wenn der Testmodus eingeschaltet war, andernfalls in die Produktionsfelder.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Credit or debit card (Niubiz)) und gibt die Bestellung auf. Das Plugin fordert bei Niubiz ein Zugriffstoken und eine Zahlungssitzung für die Bestellsumme an und leitet den Kunden auf die Zahlungsseite der Bestellung Ihres Shops weiter. Im Sandbox-Modus zeigen Kasse und Zahlungsseite SANDBOX-MODUS: Verwenden Sie Niubiz-Testkarten, es werden keine echten Belastungen vorgenommen.

Auf der Zahlungsseite öffnet sich das Niubiz-Zahlungsformular automatisch. Die Seite enthält außerdem eine Schaltfläche Pay mit der Bestellsumme, um das Formular erneut zu öffnen, eine Schaltfläche Cancel order und einen Link Choose another payment method. JavaScript ist erforderlich. Lässt sich das Niubiz-Formular nicht laden, zeigt die Seite Das Niubiz-Zahlungsformular konnte nicht geladen werden. Bitte laden Sie die Seite neu oder versuchen Sie es später noch einmal.

Der Kunde gibt die Karte im Niubiz-Formular ein. Niubiz gibt ein Einmal-Token an Ihren Shop zurück, und das Plugin autorisiert es serverseitig mit dem eigenen Betrag, der Währung und der Kaufnummer der Bestellung. Die Zahlung wird sofort belastet. Die Bestellung wird nur dann als bezahlt markiert, wenn Niubiz die Zahlung genehmigt und die Antwort zur Bestellung passt. Danach sieht der Kunde die Bestellbestätigungsseite.

Abgelehnte Karte: Der Kunde kehrt mit Ihre Zahlung wurde abgelehnt: und dem Grund von Niubiz zur Zahlungsseite zurück und kann es mit derselben oder einer anderen Karte erneut versuchen. Das Formular öffnet sich nicht erneut über der Meldung; der Kunde klickt auf Pay.

Keine Antwort von Niubiz: Gibt Niubiz keine eindeutige Antwort (Zeitüberschreitung, Serverfehler, unlesbare Antwort), sieht der Kunde die Bestellbestätigungsseite mit Wir konnten Ihre Zahlung bei Niubiz nicht bestätigen. Bitte zahlen Sie nicht erneut – der Shop prüft die Zahlung und meldet sich bei Ihnen.

Sitzung abgelaufen: Die Zahlungssitzung ist bis zu 20 Minuten gültig. Wird sie verwendet oder läuft sie bald ab, oder ändern sich Bestellsumme oder Modus, erstellt die Zahlungsseite eine neue Sitzung.

Jeder Zahlungsversuch erhält eine neue Kaufnummer: die Bestell-ID gefolgt von einer dreistelligen Versuchsnummer (bis zu 12 Zeichen), da Niubiz für jede Autorisierung eine eindeutige Kaufnummer verlangt. Ein Kunde kann eine unbezahlte oder fehlgeschlagene Bestellung über die Seite Pay for order erneut bezahlen.

Die Zahlungsart 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 nimmt nur einmalige Kartenzahlungen an. Es gibt keine Erstattungen oder Stornierungen aus WooCommerce, keine gespeicherten Karten, Abonnements oder wiederkehrenden Zahlungen, keine Auswahl von Ratenzahlungen (cuotas) und kein PagoEfectivo, Yape oder andere Wallets und QR-Zahlungen. Bestellungen, die wegen einer verlorenen Antwort auf Wartend gesetzt wurden, werden nicht automatisch erneut geprüft.

Bestellungen

Bestellstatus

Zahlung ausstehend: Der Kunde wurde zur Zahlungsseite geschickt und hat noch nicht gezahlt.

In Bearbeitung: Niubiz hat die Zahlung genehmigt und die Antwort stimmte mit der Bestellung überein. Bestellungen mit ausschließlich virtuellen, herunterladbaren Produkten werden wie üblich in WooCommerce auf Abgeschlossen gesetzt. Die Bestellnotiz zeigt die Umgebung, die Transaktions-ID, den Autorisierungscode, die Kaufnummer und die Kartenmarke mit maskierter Kartennummer. Die Transaktions-ID der Bestellung ist die Niubiz-Transaktions-ID.

Fehlgeschlagen: Die Karte wurde abgelehnt. Die Bestellnotiz zeigt den Grund von Niubiz, den Aktionscode und die Kaufnummer. Der Kunde kann erneut zahlen.

Wartend, genehmigt aber nicht passend: Niubiz hat eine Zahlung genehmigt, deren Kaufnummer, Betrag oder Währung von der Bestellung abweicht, oder deren Antwort keinen Betrag oder keine Währung enthält. Die Bestellung wird nicht als bezahlt markiert; die Notiz listet die Abweichungen auf. Prüfen Sie die Transaktion in der Niubiz-Konsole. Der Kunde sieht Ihre Zahlung wurde empfangen und wird vom Shop geprüft.

Wartend, ohne eindeutige Antwort: Niubiz hat nicht eindeutig geantwortet, die Karte könnte daher belastet worden sein. Die Notiz nennt die Kaufnummer. Suchen Sie sie in der Niubiz-Konsole: Ist die Transaktion genehmigt und korrekt, setzen Sie die Bestellung auf In Bearbeitung; andernfalls stornieren Sie sie.

Storniert: Der Kunde hat auf der Zahlungsseite auf Cancel order geklickt, oder die Bestellung wurde von Ihnen oder durch das Zeitlimit der WooCommerce-Bestandsreservierung storniert.

Lehnt Niubiz die Anfrage selbst ab (zum Beispiel eine doppelte Kaufnummer, HTTP 406 oder ungültige Zugangsdaten), ändert sich der Bestellstatus nicht. Eine Notiz besagt, dass die Karte nicht belastet wurde, und der Kunde kann mit einer neuen Kaufnummer erneut versuchen.

Erstattungen

Erstattungen und Stornierungen sind über WooCommerce nicht verfügbar. Erstatten oder stornieren Sie die Transaktion in der Niubiz-Konsole und aktualisieren Sie die Bestellung manuell, zum Beispiel mit einer manuellen Erstattung in WooCommerce.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Niubiz. 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 Niubiz Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde Diese Zahlungsart ist nicht verfügbar. Bitte wählen Sie eine andere. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert als (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Ein Hinweis erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Im Niubiz-Formular bereits gestartete Zahlungen werden weiterhin autorisiert.

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

Fehlerbehebung

Niubiz erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, merchant ID, API user und API password des aktuellen Modus ausgefüllt sind (Sandbox-Felder im Sandbox-Modus, sonst Produktionsfelder) und die Währung PEN oder USD ist. Auf der Seite Pay for order zählt die Bestellwährung. Die Einstellungsseite zeigt eine Warnung, wenn Zugangsdaten oder Währung falsch sind.

Die Zahlung ist durchgegangen, aber die Bestellung bleibt auf Zahlung ausstehend: Niubiz hat für dieses Zahlungsformular keinen Webhook, daher wird die Bestellung nur durch die Antwort auf die Autorisierung aktualisiert. Ist die Bestellung mit einer Notiz auf Wartend, suchen Sie die Kaufnummer in der Niubiz-Konsole. Bleibt sie auf Zahlung ausstehend, hat der Kunde das Formular nicht abgeschlossen; prüfen Sie WooCommerce > Status > Logs, Quelle wcp_niubiz_payment.

Der Kunde sieht Wir konnten keine Verbindung zu Niubiz herstellen: Das Zugriffstoken konnte nicht abgerufen werden. Prüfen Sie API user und API password des aktuellen Modus und ob Ihr Server die Niubiz-API erreichen kann. Aktivieren Sie den Debug log für Details.

Der Kunde sieht Wir konnten die Niubiz-Zahlung nicht starten: Niubiz hat die Zahlungssitzung nicht erstellt. Prüfen Sie die merchant ID des aktuellen Modus und das Protokoll.

Der Kunde sieht Dieser Zahlungsversuch wurde bereits verarbeitet: Dasselbe Formular wurde zweimal abgeschickt. Der Kunde startet die Zahlung auf der Zahlungsseite erneut; die Karte wird nicht zweimal belastet.

Der Kunde sieht Ihre Zahlungssitzung ist abgelaufen, und Ihre Karte wurde nicht belastet: Die Zahlungsseite war zu lange geöffnet. Der Kunde versucht es auf derselben Seite erneut.

Bestellnotiz Niubiz meldete eine doppelte Autorisierung: Niubiz kennt diese Kaufnummer bereits. Prüfen Sie sie in der Niubiz-Konsole; der Kunde kann mit einer neuen Kaufnummer erneut versuchen.

Bestellung ist auf Wartend mit einer Niubiz-Notiz: Lesen Sie die Notiz. Niubiz hat keine eindeutige Antwort gegeben oder eine Zahlung genehmigt, die nicht zur Bestellung passt. Suchen Sie die Kaufnummer in der Niubiz-Konsole und setzen Sie die Bestellung auf In Bearbeitung oder stornieren Sie sie.

Fehler beim Speichern der Einstellungen: Eine merchant ID darf nur Ziffern enthalten, und die Logo-URL muss eine gültige https://-Adresse sein. Der bisherige Wert bleibt erhalten.

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 Website-Adresse 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.

Für Entwickler: Wenn Niubiz verlangt, händlerspezifische Betrugsschutzfelder (MDD) zu senden, fügen Sie sie mit dem Filter niubiz_p_merchant_define_data hinzu. Die Schlüssel lauten MDD plus eine Zahl, die Werte dürfen bis zu 100 Zeichen lang sein. Weitere Filter: niubiz_p_cardholder_data (Karteninhaberdaten, die mit der Zahlungssitzung gesendet werden), niubiz_p_purchase_number (Kaufnummer eines Versuchs, 1 bis 12 Buchstaben oder Ziffern, pro Versuch eindeutig) und niubiz_p_icon (Symbol der Zahlungsart).

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 werden nur entfernt, wenn Delete data on uninstall aktiviert war. Niubiz-Daten, die in Bestellungen gespeichert sind (Transaktions-ID, Kaufnummer, maskierte Karte), sind Zahlungshistorie und bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Niubiz ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist nicht mit Niubiz verbunden und wird von Niubiz nicht unterstützt.