VibeFox Niubiz 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: Peruanische Sol (PEN) oder US-Dollar (USD). Die Zahlungsart wird nur für Warenkörbe in einer dieser Währungen angeboten. Für andere Währungen wird sie an der Kasse ausgeblendet.

Niubiz-Konto: Niubiz stellt für jede Umgebung eine Händler-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. Es muss kein Webhook eingerichtet werden: Niubiz beantwortet die Autorisierung sofort.

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.

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

3. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Configure-Seite ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Lassen Sie Sandbox mode eingeschaltet und geben Sie die Sandbox-Werte für merchant ID, API user und API password ein (siehe Konfiguration).

5. Schalten Sie Enable/Disable ein, klicken Sie auf Save und führen Sie einige Testzahlungen mit den Niubiz-Testkarten durch.

6. Nachdem Niubiz Ihre Integration zertifiziert hat, geben Sie die Produktionszugangsdaten ein und schalten Sie Sandbox mode aus.

Bei der Installation legt das Modul den Bestellstatus Niubiz payment on hold an. PrestaShop verknüpft ein neues Zahlungsmodul mit allen Währungen, Kundengruppen und den zu diesem Zeitpunkt aktiven Ländern. Sie können das unter Payment > Preferences ändern. Prüfen Sie dort, ob PEN oder USD für das Modul erlaubt ist.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Niubiz Payment > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn im Shop keine aktive Währung PEN oder USD vorhanden ist oder wenn die Zugangsdaten des aktuellen Modus unvollständig sind (in beiden Fällen wird die Zahlungsart an der Kasse ausgeblendet). Ist die Standardwährung des Shops weder PEN noch USD, teilt die Seite mit, dass Niubiz nur für Warenkörbe in PEN oder USD angeboten wird. Solange der Sandbox-Modus eingeschaltet ist, zeigt die Seite Der Sandbox-Modus ist aktiv: Zahlungen gehen an die Niubiz-Sandbox, und es werden keine echten Belastungen vorgenommen.

Niubiz

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

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Credit or debit card (Niubiz). Pflichtfeld: Ein leerer Titel wird nicht gespeichert, der bisherige bleibt erhalten.

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 Händler-ID, einen API user und ein API password für die Sandbox sowie nach der Zertifizierung für die Produktion bereit. Die Entwicklerdokumentation finden Sie unter desarrolladores.niubiz.com.pe.

Sandbox mode: nutzt die Sandbox-(QA-)Umgebung von Niubiz ohne echte Belastungen. Er schaltet sowohl die API-Endpunkte als auch den unten stehenden Satz an Zugangsdaten um. Standard: ein. Für Live-Zahlungen ausschalten. Solange er eingeschaltet ist, sehen Kunden unter der Zahlungsart und auf der Zahlungsseite SANDBOX-MODUS: Verwenden Sie Niubiz-Testkarten — es werden keine echten Belastungen vorgenommen.

Sandbox merchant ID: die Händler-ID Ihres Sandbox-Kontos, nur Ziffern. Leerzeichen werden entfernt. Enthält der Wert andere Zeichen, zeigt die Seite einen Fehler an und behält den bisherigen Wert. Die anderen Felder werden gespeichert.

Sandbox API user: der API user der Sandbox.

Sandbox API password: das API password der Sandbox.

Production merchant ID: die Händler-ID Ihres Produktionskontos (angeschlossen), nur Ziffern, mit derselben Prüfung.

Production API user: der API user der Produktion.

Production API password: das API password der Produktion.

Gespeicherte Passwörter werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Gespeichert — zum Beibehalten leer lassen. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Clear saved passwords: Setzen Sie den Haken bei einem Passwort und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlungsformular

Logo URL: optionale HTTPS-Adresse Ihres Logos, das im Niubiz-Zahlungsformular angezeigt wird, etwa 187 × 40 px. Ohne sie wird der Shopname angezeigt. Eine Adresse, die keine gültige https://-Adresse ist, wird mit einem Fehler abgelehnt und der bisherige Wert bleibt erhalten.

Erweitert

Debug log: protokolliert die Niubiz-API-Aufrufe in logs/niubiz_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Fehler und Warnungen werden immer protokolliert, auch wenn dieser Schalter aus ist. Zugangsdaten, Token sowie Karten- und Kundendaten werden nie protokolliert. Standard: aus.

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

Delete data on uninstall: Wenn eingeschaltet, entfernt die Deinstallation des Moduls seine Einstellungen und das Protokoll. Zahlungsdaten, die für Bestellungen gespeichert wurden (Niubiz-Versuche, Bestellnotizen), und der Bestellstatus bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Credit or debit card (Niubiz)) und gibt die Bestellung auf. Das Modul fordert bei Niubiz ein Zugriffstoken und eine Zahlungssitzung für den Warenkorbbetrag in der Warenkorbwährung an und öffnet die Zahlungsseite Niubiz payment Ihres Shops. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Auf der Zahlungsseite öffnet sich das Niubiz-Zahlungsformular automatisch. Die Seite zeigt Schließen Sie die Zahlung im sicheren Niubiz-Zahlungsformular ab — Ihre Kartendaten werden bei Niubiz eingegeben, nicht auf dieser Website. Außerdem gibt es eine Schaltfläche Pay mit dem Warenkorbbetrag, um das Formular erneut zu öffnen, und einen Link Choose another payment method. JavaScript ist erforderlich. Kann das Niubiz-Formular nicht geladen werden, zeigt die Seite Das Niubiz-Zahlungsformular konnte nicht geladen werden. Bitte laden Sie die Seite neu oder versuchen Sie es später erneut.

Der Kunde gibt die Karte im Niubiz-Formular ein. Niubiz sendet ein einmalig gültiges Token an Ihren Shop, und das Modul autorisiert es serverseitig mit Betrag, Währung und Kaufnummer der Sitzung, in der Umgebung, in der die Sitzung erstellt wurde. Die Zahlung wird sofort belastet. Die Bestellung wird nur dann als bezahlt markiert, wenn Niubiz die Zahlung genehmigt und die Antwort mit dem Warenkorb übereinstimmt. Danach wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite.

Abgelehnte Karte: Es wird keine Bestellung angelegt. 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 über der Meldung nicht erneut; der Kunde klickt auf Pay.

Keine Antwort von Niubiz: Gibt Niubiz keine endgültige Antwort (Timeout, Serverfehler, unlesbare Antwort), wird die Bestellung auf Niubiz payment on hold angelegt, und die Bestätigungsseite zeigt 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. Hat Niubiz eine Zahlung genehmigt, die nicht zum Warenkorb passt, zeigt die Seite Ihre Zahlung ist eingegangen und wird vom Shop geprüft. Wir melden uns, falls noch etwas benötigt wird.

Anfrage abgelehnt: Lehnt Niubiz die Anfrage selbst ab (zum Beispiel bei ungültigen Zugangsdaten oder einer doppelten Kaufnummer), wird keine Bestellung angelegt, und der Kunde sieht Niubiz konnte die Zahlung nicht verarbeiten, und Ihre Karte wurde nicht belastet. Der Grund wird im Protokoll festgehalten.

Warenkorb geändert: Ändert sich der Warenkorbbetrag, nachdem das Formular geöffnet wurde (zum Beispiel in einem anderen Browser-Tab), wird die Zahlung nicht autorisiert und der Kunde sieht Ihr Warenkorb wurde geändert, seit das Zahlungsformular geöffnet wurde. Ihre Karte wurde daher nicht belastet. Bitte prüfen Sie den Betrag und zahlen Sie erneut.

Sitzung abgelaufen: Eine Niubiz-Zahlungssitzung ist bis zu 20 Minuten gültig. Ist sie bereits verwendet, hat sie weniger als 5 Minuten Restlaufzeit, gehört zu einem anderen Modus oder einer anderen Händler-ID oder hat sich der Warenkorbbetrag geändert, erstellt die Zahlungsseite eine neue Sitzung.

Jeder Zahlungsversuch erhält eine neue Kaufnummer: die Warenkorb-ID, gefolgt von einer dreistelligen Versuchsnummer (bis zu 12 Zeichen), weil Niubiz für jede Autorisierung eine eindeutige Kaufnummer verlangt.

Das Modul nimmt nur einmalige Kartenzahlungen an. Es gibt keine Erstattungen oder Stornierungen aus PrestaShop, keine gespeicherten Karten, Abonnements oder wiederkehrenden Zahlungen, keine Auswahl von Ratenzahlungen (cuotas) und keine Zahlungen über PagoEfectivo, Yape oder andere Wallets und QR-Zahlungen. Bestellungen, die wegen einer ausgebliebenen Antwort auf Niubiz payment on hold gesetzt wurden, werden nicht automatisch erneut geprüft.

Bestellungen

Bestellstatus

No order yet: Der Kunde befindet sich auf der Zahlungsseite und hat noch nicht bezahlt, oder die Karte wurde abgelehnt oder die Anfrage verweigert. Es existiert nur der Warenkorb. Ablehnungen und Verweigerungen werden im Modulprotokoll festgehalten.

Payment accepted: Niubiz hat die Zahlung genehmigt und die Antwort stimmte mit dem Warenkorb überein. Die Zahlung wird mit der Transaktions-ID von Niubiz erfasst, und eine Notiz zeigt Umgebung, Transaktions-ID, Autorisierungscode, Kaufnummer sowie Kartenmarke und maskierte Kartennummer.

Niubiz payment on hold, approved but not matching: Niubiz hat eine Zahlung genehmigt, deren Kaufnummer, Betrag oder Währung vom Warenkorb abweicht oder deren Antwort keinen Betrag oder keine Währung enthält. Die Bestellung wird nicht als bezahlt markiert. Entspricht die genehmigte Währung der Warenkorbwährung, wird der genehmigte Betrag als Zahlung mit seiner Transaktions-ID erfasst. Die Notiz listet die Abweichungen auf. Prüfen Sie die Transaktion in der Niubiz-Konsole.

Niubiz payment on hold, no definitive answer: Niubiz hat nicht eindeutig geantwortet, daher könnte die Karte belastet worden sein. Es wird keine Zahlung erfasst. Die Notiz nennt die Kaufnummer. Suchen Sie sie in der Niubiz-Konsole: Ist die Transaktion genehmigt und korrekt, setzen Sie die Bestellung auf Payment accepted; wenn nicht, stornieren Sie sie.

Wird für einen Warenkorb, der bereits eine Bestellung hat, eine zweite Zahlung beantwortet, wird keine zweite Bestellung angelegt. Eine Notiz an der Bestellung nennt Kaufnummer, Transaktions-ID und Betrag, damit Sie es in der Niubiz-Konsole prüfen und bei Bedarf erstatten oder stornieren können.

Niubiz-Zahlungsblock

Die Bestellseite zeigt einen Block Niubiz payment mit Kaufnummer, Umgebung (Sandbox oder Produktion), Transaktions-ID, Autorisierungscode, Karte und den Notizen der Bestellung. Bei einer Bestellung im Status Niubiz payment on hold erinnert der Block Sie daran, die Kaufnummer in der Niubiz-Konsole zu prüfen. Der Block ist nur lesbar.

Erstattungen

Erstattungen und Stornierungen sind aus PrestaShop nicht möglich. Erstatten oder stornieren Sie die Transaktion in der Niubiz-Konsole und aktualisieren Sie die Bestellung manuell. Die standardmäßigen PrestaShop-Erstattungsschaltflächen der Bestellseite senden kein Geld über Niubiz zurück.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Niubiz Payment ist der erste Block auf Modules > Module Manager > VibeFox Niubiz Payment > Configure, 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 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-niubiz 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. Nachdem sich die Adresse des Shops geändert hat oder Sie in Ihrem vibefox.net-Konto einen Domain-Platz 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-Einrichtung. Das Entfernen des Schlüssels aus dem Shop gibt seinen 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. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind; daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt.

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 der Eingabe des Schlüssels, danach einmal pro Woche. Es ist kein Cron-Job nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Niubiz erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, die merchant ID, der API user und das API password des aktuellen Modus ausgefüllt sind (Sandbox-Felder im Sandbox-Modus, sonst Produktionsfelder) und die Warenkorbwährung PEN oder USD ist. Die Einstellungsseite zeigt eine Warnung, wenn die Zugangsdaten oder Währungen falsch sind. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: Niubiz hat für dieses Zahlungsformular keinen Webhook, daher wird die Bestellung nur durch die Antwort auf die Autorisierung angelegt. Hat der Kunde das Formular nicht abgeschlossen, gibt es keine Bestellung. Andernfalls sehen Sie im Feld Log auf der Modulseite nach und suchen Sie die Kaufnummer in der Niubiz-Konsole. Hat Niubiz geantwortet, die Bestellung aber nicht angelegt werden konnte (zum Beispiel weil das Modul deaktiviert war), sieht der Kunde Ihre Zahlung ist eingegangen, die Bestellung konnte aber nicht automatisch abgeschlossen werden. Bitte kontaktieren Sie uns — zahlen Sie nicht erneut., und das Modul versucht, die Bestellung erneut anzulegen, wenn der Kunde die Zahlungsseite erneut öffnet.

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

Der Kunde sieht „Die Niubiz-Zahlung konnte nicht gestartet werden“: 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 abgesendet. Der Kunde startet die Zahlung auf der Zahlungsseite erneut; die Karte wird nicht zweimal belastet.

Der Kunde sieht „Diese Bestellung wird bereits bezahlt“: Eine andere Anfrage autorisiert im Moment denselben Warenkorb. Der Kunde wartet einen Moment und prüft die E-Mails, bevor er es erneut versucht.

Das Protokoll zeigt „Niubiz hat eine doppelte Autorisierung gemeldet“: Niubiz kennt diese Kaufnummer bereits. Prüfen Sie sie in der Niubiz-Konsole; der Kunde kann es mit einer neuen Kaufnummer erneut versuchen.

Bestellung ist auf Niubiz payment on hold: Lesen Sie die Notizen im Block Niubiz payment. Niubiz hat keine endgültige Antwort gegeben oder eine Zahlung genehmigt, die nicht zum Warenkorb passt. Suchen Sie die Kaufnummer in der Niubiz-Konsole und setzen Sie die Bestellung auf Payment accepted 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.

Für Entwickler: Verlangt Niubiz händlerspezifische Betrugsschutz-Felder (MDD), kann ein anderes Modul sie mit dem Hook actionNiubizPMerchantDefineData hinzufügen. Die mit der Zahlungssitzung gesendeten Karteninhaberdaten lassen sich mit dem Hook actionNiubizPCardholderData ändern.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Niubiz Payment und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall eingeschaltet, werden die Modul-Einstellungen und das Protokoll entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Niubiz-Zahlungsversuche (Kaufnummern, Umgebung, Transaktions-IDs) und der Bestellstatus Niubiz payment on hold bleiben immer als Zahlungshistorie erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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