nexi_payment
Ein Flutter-Plugin für die Zahlungs-Gateways von Nexi: die Bezahlseite von Nexi auf Android und iOS und ein Ergebnis, auf das sich die App verlassen kann.
- Rolle
- Autor und Maintainer: die Dart-API, der Code für Android (Java) und iOS (Swift), Tests, CI und Releases
- Art
- Open-Source-Flutter-Plugin, MIT-Lizenz, auf pub.dev
- Zeitraum
- 2020 – heute (2.3.0, Juli 2026)
- Plattformen
- Android und iOS
Das Produkt
Mit nexi_payment kann eine Flutter-App Zahlungen über Nexi abwickeln. Die App übergibt die Bestellung, die Bezahlseite von Nexi erfasst die Karte (die App bekommt sie nie zu sehen), und die App erfährt, was passiert ist: bezahlt, abgebrochen oder fehlgeschlagen, und warum.
Ich habe das Plugin im Juni 2020 geschrieben, als ich Nexi in die App von Criluma Viaggi einbaute, und es auf pub.dev veröffentlicht. Im Juli 2026 habe ich es als 2.0 neu geschrieben: das neuere NPG-Gateway von Nexi neben dem klassischen XPay, ein einheitliches Fehlerschema auf beiden Plattformen, Tests, die die echten SDKs steuern, und Korrekturen für die Momente, in denen die nativen SDKs von Nexi verstummen oder das Falsche melden.
- 7
- stabile Releases auf pub.dev, von 1.0.0 im Juni 2020 bis 2.3.0 im Juli 2026
- 53
- der 58 Commits stammen von mir; die übrigen kamen als Pull Requests von Mitwirkenden
- 2
- Nexi-Gateways hinter einer Dart-API: das klassische XPay und NPG
- 49
- automatisierte Tests: 35 Unit-Tests und 14 Integrationstests, die auf einem Gerät laufen
Rundgang
Die App in Aktion
Wählen Sie eine Aufnahme oder springen Sie direkt zu einem Kapitel.
Aufgezeichnet auf einem Android-Emulator mit einem Release-Build der Beispiel-App, bezahlt in der öffentlichen Sandbox von Nexi. Die Felder der Bezahlseite werden über DevTools gefunden und wie mit einem Finger berührt; auf dieselbe Weise bekommt die Sandbox-Seite zwei kleine Korrekturen, ohne die sie nicht funktioniert.
Funktionen
Von der Schaltfläche in der App zum verlässlichen Ergebnis
01
Ein Aufruf öffnet die Bezahlseite von Nexi
Die App übergibt die Bestellung (ID, Betrag, Währung, Sprache), und das Plugin öffnet über das native SDK die Hosted Payment Page von Nexi: eine Karte oder eine der anderen Zahlungsarten, die Nexi anbietet. Die Karte wird auf der Seite von Nexi eingegeben, nie in der App.
02
Zusammenfassung und 3-D Secure
Nexi zeigt die Zusammenfassung mit der maskierten Karte und übergibt dann für 3-D Secure an die Bank des Karteninhabers: in der Sandbox an die DemoBank, die sich auf Erfolg oder Fehlschlag einstellen lässt.
03
Ein Ergebnis, auf das sich die App verlassen kann
Die nativen SDKs rufen ihren „completed“-Callback für jede abgeschlossene Zahlung auf, abgelehnte eingeschlossen. Das Plugin meldet nur bei einer abschließenden Operation EXECUTED oder AUTHORIZED einen Erfolg; eine fehlgeschlagene Authentifizierung kommt als Fehler mit dem Code von Nexi zurück. Vor 2.0 meldete iOS eine abgelehnte Zahlung sogar als bloßen String; inzwischen werfen beide Plattformen dieselben Fehler mit Code.
04
Jeder Ausweg beendet den Aufruf
Die Zurück-Taste, der eigene Abbrechen-Link von Nexi, ein unter iOS weggewischtes Sheet: Jeder dieser Wege schließt die Zahlung als abgebrochen ab, und die nächste Zahlung öffnet sich normal. Zwei dieser Ausstiege ließen die App früher auf eine Antwort warten, die nie kam.
Unter der Haube
So wurde es entwickelt
Das Schweigen der SDKs füllen
XPaySDK schließt seine Bezahlseite bei der Zurück-Taste von Android, ohne zurückzurufen, und NPGSDK unter iOS kann sein Sheet kommentarlos verschwinden lassen. Das Plugin beobachtet den Lebenszyklus der Bezahlseite und meldet einen Abbruch, wenn sie verschwindet, ohne etwas gesagt zu haben (ein echtes Ergebnis hat immer Vorrang), und eine Sperre lehnt eine zweite Zahlung ab, solange eine offen ist, statt zwei Aufrufe in der Schwebe zu lassen.
Wenn das SDK seine eigene Antwort nicht lesen kann
NPGSDK 1.1.0 deklariert die additionalData einer Operation als Map von Strings, doch das Backend verschachtelt darin ein Objekt, sodass das SDK unter Android beim Parsen des Ergebnisses einer erfolgreichen Zahlung scheitern kann. Das Plugin liest die Bestellung dann über die Orders-API von NPG nach und meldet, was wirklich passiert ist: Es erfindet nie einen Erfolg und meldet „outcome unknown“, wenn es das nicht feststellen kann.
Paketierung, Tests und Releases
Nexi veröffentlicht keine Maven-Artefakte, und sein iOS-Pod enthält keinen Slice für den Simulator: Die Android-SDKs werden im Plugin mitgeliefert, die iOS-Frameworks beim pod install aus den Release-Repositories von Nexi geladen und gegen festgelegte SHA-256-Prüfsummen geprüft. Unit-Tests sichern den Vertrag des Platform Channels ab, Patrol-Tests steuern die echten SDKs gegen die Sandbox von Nexi, die CI analysiert, testet und baut bei jedem Push und Pull Request, und ein Versions-Tag veröffentlicht auf pub.dev.
Ein Zahlungs-Plugin aufzeichnen
Eine echte Bezahlseite, in der Sandbox von Nexi.
Ein Plugin hat keine eigenen Bildschirme, deshalb zeigen die Aufnahmen seine Beispiel-App (einen Release-Build auf einem Android-Emulator), die in der öffentlichen Sandbox von Nexi tatsächlich bezahlt.
- 1
Der veröffentlichte Code, als Release gebaut
Das Repository beim Tag 2.3.0, die Beispiel-App im Release-Modus gebaut, mit den Sandbox-Zugangsdaten, die Nexi veröffentlicht, und auf einem Emulator installiert. Keine privaten Schlüssel: Die klassischen XPay-Schaltflächen brauchen ein eigenes Testterminal eines Händlers und werden nicht gezeigt.
- 2
Über DevTools in die Seite von Nexi
Die Bezahlseite ist eine Webseite in der WebView des SDK. Das Aufnahmeskript findet ihre Felder über die Chrome DevTools, die auch verraten, wo die WebView auf dem Bildschirm liegt, berührt sie auf dem Touchscreen des Emulators wie ein Finger und tippt die Testkarte von Nexi ein.
- 3
Zwei Eigenheiten der Sandbox
Die Sandbox-Seite lässt ihre Karten-Schaltfläche manchmal ohne Beschriftung und aktiviert die Bezahl-Schaltfläche bei einer eingetippten Karte nie. Das Skript behebt beides über DevTools, das Zweite genau so, wie es das Runbook des Plugins für Gerätetests vorsieht.
- 4
Drei Ausgänge
Eine Zahlung, die durchgeht, eine, bei der 3-D Secure fehlschlägt, und zwei Arten, einfach abzubrechen. Jede Aufnahme beginnt mit einer zurückgesetzten App und einer neuen Bestellung.
Die Zahlungsseiten, der Sandbox-Händler (WWW.CHARTA.IT) und die DemoBank gehören zur öffentlichen Sandbox von Nexi. Die Karte ist die veröffentlichte Testkarte von Nexi; der Karteninhaber ist erfunden.
Hier gibt es nichts auszuprobieren: Das Plugin läuft innerhalb von Android- und iOS-Apps. Es ist auf pub.dev und GitHub verfügbar.
Alle Bildschirme
Alle Screenshots im Überblick
Die Beispiel-AppBeide Gateways, Kartenspeicherung und eine wiederkehrende Belastung, je eine Schaltfläche. Hosted Payment PageDie Seite von Nexi, geöffnet vom nativen SDK: Karte oder eine andere Zahlungsart. Die KarteDie veröffentlichte Testkarte von Nexi; die App bekommt die Nummer nie zu sehen. ZusammenfassungHändler, Betrag, Bestellung und die maskierte Karte. 3-D SecureDie DemoBank der Sandbox bittet den Karteninhaber um Bestätigung. AusgeführtDas Plugin meldet nur bei einer ausgeführten oder autorisierten Zahlung einen Erfolg. FehlgeschlagenTHREEDS_FAILED, kein Erfolg: Das Plugin prüft die abschließende Operation. AbgebrochenZurück-Taste: Das Plugin macht aus dem Schweigen des SDK einen Abbruch. Die Seite verlassenDer eigene Abbrechen-Link von Nexi fragt nach einer Bestätigung.
Nächste Fallstudie
Referi →