AKDB: EPayment-Plugin
Plugin download (requires login)
Das kostenpflichtige AKDB EPayment Plugin ermöglicht es, über das von der AKDB bereitgestellte ePay-BL Portal, einen Bezahlvorgang in einen Formularprozess einzubauen.
Der nachfolgende Artikel beschreibt beispielhaft die von einen Formular-Ersteller auszuführenden Schritte, um einen Bezahlvorgang in einem Formular zu integrieren.
Auf die notwendigen Schritte, um den Service technisch in Xima® Formcycle einzubinden wird an dieser Stelle nicht eingegangen.
Prinzipiell sind immer folgende Schritte für eine Einbindung auszuführen:
- Formular mit "bestellbaren" Artikeln und notwendigen Dateneingaben versehen
- Statusverarbeitung konfigurieren mit Aktionen zum Starten einer Bezahl-Transaktion und zum Kontrollieren des Status der Transaktion
- Anzeige des Ergebnisses der Bezahl-Transaktion
1. Formular für den Bezahlvorgang designen
Durch die Installation des Plugins im FORMCYCLE-System sind im Designer 2 zusätzliche Elemente, sowie 4 Vorlagen vorhanden, welche den Nutzer bei der notwendigen Konfiguration für das EPayment unterstützen sollen.
1.1. Artikel definieren durch das Formular-Element: EPayment Artikel:
Über das Formular-Element EPayment Artikel werden die für eine Bestell-Transaktion notwendigen Artikel definiert.
Das Formular-Element dient dabei zum Einen für eine visuelle Darstellung des Artikels (mit Bild, Preisangabe, Eingabemöglichkeit für Bestellmenge) innerhalb eines Formulars, als auch als Vorlage
für die notwendige serverseitige Konfiguration des Artikels innerhalb des Aktions-Plugins AKDB:EPayment initialisieren.
Grundeigenschaften:
- Angehackt, Versteckt
- Durch das initiale Auswählen dieser zwei Optionen wird es möglich einen Bestellartikel vor dem Nutzer zu verbergen und direkt bei Absenden eines Formulars in den Warenkorb zu legen.
- Dies kann immer dann der Fall sein, wenn dem Benutzer selbst keine Entscheidung für die Auswahl eines Bestellartikels ermöglicht werden soll, zum Beispiel bei der Erhebung einer Gebühr.
EPayment Bestellartikel Einstellungen:
- Artikelbeschreibung
- Nähere Beschreibung eines Artikels
- Artikel-Preis
- Der Preis für einen Artikel. Der an dieser Stelle konfigurierte Wert dient zum Einen für die Anzeige innerhalb des Formulars, als auch für eine Vorbelegung der Bestellinformationen bei der serverseitigen Konfiguration des EPayments.
- Artikelnummer
- Eine eindeutige Nummer für den einzelnen Artikel innerhalb des Formulars. Dient bei der Ausführung eines Bestell-Prozesses zur eindeutigen Identifizierung des jeweiligen Artikels.
1.2. Vorlagen zur Ermittlung von Bestellinformationen:
Durch das Plugin werden verschiedene Designer-Vorlagen bereitgestellt, mit denen es ermöglicht wird die nachfolgend aufgeführten Daten vom Benutzer zu ermitteln:
- Persönliche Daten: Anrede, Name, Vorname, E-Mail etc.
- Rechnungsadresse
- Lieferadresse
- Bankverbindung
1.3. Bestellprozess starten mittels Formular-Element EPayment Bestellen Button:
Über das Formular-Element EPayment Bestellen Button kann das Formular durch den Nutzer abgesendet und damit der Bezahlvorgang gestartet werden.
Bei Nutzung dieses speziellen Absende-Buttons werden zum Absende-Zeitpunkt alle ausgewählten Artikeln ermittelt und deren Artikelnummer sowie Bestellmenge zum Server übertragen.
EPayment Einstellungen:
- Schaltflächentext
- Beschriftung des Absenden-Buttons
- Eingaben pruefen vor Absenden
- Wenn ausgewählt, wird das Formular vor dem Absenden validiert, sonst erfolgt keine Prüfung.
2. Statusverarbeitung für EPayment konfigurieren
Um eine Bezahl-Transaktion in einen Formularprozess einzubauen werden die folgenden Aktions-Plugins zur Verfügung gestellt:
- AKDB:EPayment initialisieren: Dieses erzeugt eine neue Bezahl-Transaktion auf Seiten der AKDB und leitet den Benutzer auf dessen Portalseite weiter.
- AKDB:EPayment verifizieren: Prüft den aktuellen Status einer Bezahl-Transaktion
Ein Statusverarbeitung für einen einfachen Fall kann folgendermaßen konfiguriert sein:
Kurze Ablaufbeschreibung zur dargestellten Statusverarbeitung: 1. Nach dem Absenden des Bestellformulars wird in den Status Eingegangen gewechselt und dort das Aktions-Plugin AKDB:EPayment initialisieren ausgeführt. Dieses ermittelt die für den Bestellvorgang notwendigen Daten aus dem Formular und startet mit diesen eine Bezahl-Transaktion auf Seiten der AKDB. Wenn dies erfolgreich war, wird der Benutzer zum ePay-BL Portal der AKDB, unter vorheriger Angabe eines Rücksprung-Ziels (Realisiert über Festlegung eines Ziel-Status), weitergeleitet. 2. Nach Abschluss des Bezahlvorgangs im ePay-BL Portal wird der Benutzer wieder zum Xima® Formcycle-Formular zurückgeleitet. Dies erfolgt unter Benutzung des angegebenen Rücksprung-Ziels. 3. Die Statusverarbeitung Zahlung pruefen wird ausgeführt und dort das Aktions-Plugin AKDB:EPayment verifizieren durchlaufen. Unter Zuhilfenahme dieses Plugins wird der aktuelle Status der Bezahlung am EPayment-System geprüft und in der weiteren Statusverarbeitung (per Platzhalter) zur Verfügung gestellt. 4. Im Falle einer positiven Verifizierung des Bezahlvorgangs wird unter Zuhilfenahme der Aktion Statusänderung in den Status Bezahlt gewechselt. Innerhalb von diesem Status ist eine Weiterleitungs-Aktion zum aktuellen Formular konfiguriert, sodass dieses dem Benutzer wieder angezeigt wird. Innerhalb dieses Formulares kann dann ein Text-Element konfiguriert werden, welches nur im Status Bezahlt angezeigt wird und dem Benutzer eine positive Rückmeldung zum Ausgang seines Bezahlvorgangs anzeigt. Hinweis: Anstatt einer Rückleitung ins Formular kann im Status Bezahlt auch eine individuelle Abschluss-Seite konfiguriert sein. Dann würde diese dem Nutzer angezeigt werden. 5. Im Falle einer negativen Verifizierung des Bezahlvorgangs (z.B.: der Nutzer hat den Bezahlvorgang im ePay-BL Portal abgebrochen; während des Bezahlvorgangs ist ein Fehler aufgetreten) wird unter Zuhilfenahme der Aktion Statusänderung in den Status Bezahlung offen gewechselt. Es erfolgt wieder eine Weiterleitung ins aktuelle Formular, wo ein Text-Element konfiguriert ist, welches nur im Status Bezahlung offen angezeigt wird und dem Benutzer eine Rückmeldung zu seiner noch ausstehenden Bezahlung anzeigt.
|
2.1. Konfigurationsmöglichkeiten des Aktions-Plugins AKDB:EPayment initialisieren
Dieses Aktions-Plugin ist für das Erzeugen einer Bezahl-Transaktion im ePay-BL Portal zuständig. Hier werden im Vorfeld die Daten, welche im Zusammenhang mit der Transaktion stehen (bestellte Artikel, Preisbestimmung, persönliche Daten des Käufers, Rechnungsadresse etc.), festgelegt. Weiterhin erfolgt die Festlegung in welchen Status, nach Rückkehr aus dem ePay-BL Portal, gewechselt werden soll.
Die Konfigurationsoberfläche des Aktions-Plugins ist in einzelne Bereiche unterteilt die nachfolgend kurz beschrieben werden.
Konfiguration AKDB EPayment-Mandant
- Mandant-Nummer (Pflichtfeld)
- AKDB-Mandantennummer des aufrufenden eShops (FORMCYCLE) (Wird durch ePay-BL-System vorgegeben)
- Bewirtschafter-Nummer (Pflichtfeld)
- Bewirtschafternummer (Wird durch ePay-BL-System vorgegeben)
- Haushaltsstelle (Pflichtfeld)
- Nummer der Haushaltsstelle, welcher die Buchung zugeordnet werden soll. (Wird durch ePay-BL-System vorgegeben)
- Objektnummer (Pflichtfeld)
- Dient der internen Verbuchung im EPayment-System. (Wird durch ePay-BL-System vorgegeben)
- Kennzeichen-Mahnverfahren (Pflichtfeld)
- Einstellung für das Kennzeichen in einem Mahnverfahren. (Mögliche Werte werden durch ePay-BL-System vorgegeben)
- Fälligkeitszeitraum (Pflichtfeld)
- Einstellung für die Berechnung des Fälligkeitszeitraumes der Zahlung (Dauer in Tagen).
- Währung
- Währung in welcher der Betrag ausgewiesen wird. Ist nichts definiert wird als Wert EUR angenommen.
Konfiguration für die PayPage
- URL zur PayPage (Pflichtfeld)
- URL zur PayPage des EPayment-Systems. Die hier hinterlegte URL wird durch das ePay-BL-System vorgegeben und beinhaltete den Verweis auf die PayPage im ePay-BL-System.
- Automatische Weiterleitung zur PayPage verhindern
- Bei aktivierter Einstellung kann eine automatische Weiterleitung zur PayPage unterbunden werden.
- Status, in welchen nach erfolgreicher Transaktion gewechselt wird (Pflichtfeld)
- Hier muss ein Status festgelegt werden, in welchen gewechselt wird, wenn der Bezahlvorgang auf Seiten des ePay-BL-Systems erfolgreich durchlaufen wurde.
- Status, in welchen nach fehlerhafter oder abgebrochener Transaktion gewechselt wird (Pflichtfeld)
- Hier muss ein Status festgelegt werden, in welchen gewechselt wird, wenn der Bezahlvorgang auf Seiten des ePay-BL-Systems abgebrochen wurde.
- PayPage Buchungstext
- Dieser Buchungstext wird dem Benutzer auf der PayPage angezeigt.
- Fälligkeitsdatum
- Der konfigurierte Wert muss sich in ein gültiges Datum umwandeln lassen. Wenn an dieser Stelle ein Wert hinterlegt ist, wird dieser als Fälligkeitszeitpunkt für die Zahlung übermittelt und die Einstellung für den Fälligkeitszeitraum wird nicht beachtet.
Kundenstammdaten
- Anrede
- Titel
- Vorname
- Nachname (Pflichtfeld)
- Geburtsdatum
- Geburtsdatum muss in der Form dd.MM.yyyy übermittelt werden.
- Wird für die Zustellung von Emails an den Kunden in Abhängigkeit von der ePay-BL-Mandantkonfiguration benötigt.
- Telefon (privat)
- Telefon (dienstlich)
- Mobiltelefon
Bestellinformationen
- Artikelnummer (Pflichtfeld)
- Eine Nummer die den einzelnen Artikel innerhalb einer Bestellung eindeutig identifizierbar macht.
- Beschreibung (Pflichtfeld)
- Der Buchungstext darf nur folgende Zeichen enthalten: A-Za-z0-9,.:/+& -*$%ÄÖÜäöüß und ist in seiner Länge auf maximal 21 Zeichen begrenzt.
- Betrag (Pflichtfeld)
- Komma separierte Zahl, die den Preis eines Artikels definiert.
- Belegnummer
- Die Belegnummer ist optional und dient der weiterführenden Verarbeitung auf Seiten von ePay-BL.
Konfiguration Rechnungsadresse (optional)
- Strasse (bedingt verpflichtend)
- Wahlweise ist Strasse und Hausnummer oder Postfach bei Nutzung von Rechnungsadressdaten ein Pflichtfeld.
- Hausnummer (bedingt verpflichtend)
- Wahlweise ist Strasse und Hausnummer oder Postfach bei Nutzung von Rechnungsadressdaten ein Pflichtfeld.
- Postfach (bedingt verpflichtend)
- Wahlweise ist Postfach oder Strasse und Hausnummer bei Nutzung von Rechnungsadressdaten ein Pflichtfeld.
- Ort (bedingt verpflichtend)
- PLZ (bedingt verpflichtend)
- Postleitzahl
- Land (bedingt verpflichtend)
- Wenn gesetzt, muss die Angabe gemäß ISO 3166-1 erfolgen (zwei Großbuchstaben, z.B.: DE)
Konfiguration Lieferadresse (optional)
- Anrede
- Vorname
- Nachname
- Strasse (bedingt verpflichtend)
- Wahlweise ist Strasse und Hausnummer oder Postfach bei Nutzung von Lieferadressdaten ein Pflichtfeld.
- Hausnummer (bedingt verpflichtend)
- Wahlweise ist Strasse und Hausnummer oder Postfach bei Nutzung von Lieferadressdaten ein Pflichtfeld.
- Postfach (bedingt verpflichtend)
- Wahlweise ist Postfach oder Strasse und Hausnummer bei Nutzung von Lieferadressdaten ein Pflichtfeld.
- Ort (bedingt verpflichtend)
- PLZ (bedingt verpflichtend)
- Postleitzahl
- Land (bedingt verpflichtend)
- Wenn gesetzt, muss die Angabe gemäß ISO 3166-1 erfolgen (zwei Großbuchstaben, z.B.: DE)
Konfiguration für die Bankverbindung (optional)
- Kontoinhaber
- Falls der Inhaber des Kontos vom Namen des Kunden abweicht, muss dieser hier übertragen werden. Falls das Feld leer ist, wird bei den Zahlungsüberstellungen der Nachname des Kunden verwendet.
- Kontonummer (bedingtes Pflichtfeld)
- Kontonummer vom Zahlungspflichtigen. Wenn Kontodaten konfiguriert werden, ist dies ein Pflichtfeld.
- IBAN
- International Bank Account Number des Kontos
- BIC
- Bank Identification Code des Kontos
- BLZ (bedingtes Pflichtfeld)
- Bankleitzahl vom Konto des Zahlungspflichtigen. Wenn Kontodaten konfiguriert werden, ist dies ein Pflichtfeld.
Allgemeine Rückgabeparameter
- Kassenzeichen
- Das für die Transaktion, auf Seiten von ePay-BL erzeugte, notwendige Kassenzeichen.
- EShopKundenNr
- Die für die Transaktion automatisch erzeugte EShopKundenNr. (Dient der internen Verarbeitung.)
- Gesamtbetrag
- Der errechnete Gesamtbetrag der Bezahl-Transaktion. (Ergibt sich aus der Summe aller bestellten Artikel X deren Bestellmenge.)
2.2. Konfigurationsmöglichkeiten des Aktions-Plugins AKDB:EPayment verifizieren
Dieses Aktions-Plugin ist zum Auswerten des Status einer Bezahl-Transaktion zuständig. Im Standardfall muss innerhalb des Plugins keine weitere Konfiguration erfolgen, da alle notwendigen Parameter, für eine Prüfanfrage am ePay-BL-Service, intern hinterlegt sind.
Es besteht aber auch die Möglichkeit die AKDB-Mandantennummer und das Kassenzeichen durch eine Konfiguration zu übersteuern. Dies kann immer dann der Fall sein, wenn die Prüfung in einem anderem Formularvorgang erfolgen soll, in dem nicht die eigentliche Bezahl-Transaktion erzeugt wurde.
Allgemeine Rückgabeparameter
- PayPageStatus
- Enthält den vom ePay-BL-Service zurückgelieferten Statuscode. Die nachfolgende Tabelle gibt einen Überblick über die möglichen Statuscode und deren Bedeutung:
Statuscode | Bedeutung |
---|---|
INAKTIV | Die Bezahlung über die PayPage ist erfolgreich durchgeführt worden |
AKTIV | Die Bezahlung über die PayPage ist noch nicht erfolgt. |
MANDANT_NICHT_GEFUNDEN | Der Mandant wurde im ePayment-System nicht gefunden. |
MANDANT_INAKTIV | Der Mandant ist im ePayment-System derzeit als inaktiv gekennzeichnet. |
VERBINDUNG_OHNE_HTTPS | Die Verbindung zum Webservice erfolgte nicht über HTTPS mit Client-Zertifikaten. |
VERBINDUNG_ZERTIFIKAT_FEHLER | Das für die Verbindung verwendete Client-Zertifikat darf nicht für den gewählten Mandanten verwendet werden. |
KASSENZEICHEN_NICHT_VORHANDEN | Das gewählte Kassenzeichen ist nicht vorhanden. |
KASSENZEICHEN_NICHT_GEFUNDEN | Das gewählte Kassenzeichen konnte nicht gefunden werden. |
INTERNER_EPAYMENT_FEHLER | Interner nicht dokumentierter Fehler im ePayment-System. |
UNDEFINIERT | Ein im System nicht bekannter Status |
- WebserviceErgebnisText
- Enthält den vom ePay-BL Service zurückgelieferten Erläuterungstext zum übermittelten Status.
3. Ergebnisanzeige
Für die Anzeige des Ergebnisses bzw. dem Status einer Bezahl-Transaktion bestehen mehrere Möglichkeiten.
Man kann dem Nutzer dieses in einer extra dafür hinterlegten Abschluss-Seite oder durch die Wiederanzeige das Formulars anzeigen.
Ein Beispiel für die Ergebnisanzeige innerhalb des Formular ist unter dem Punkt Statusverarbeitung für EPayment konfigurieren aufgeführt.
In den meisten Fällen ist es gewünscht, dass je nach Status der Bezahl-Transaktion unterscheidliche Rückmeldungstexte angezeigt oder zusätzliche Aktionen ausgeführt werden.
Erreichen kann man dies über eine entsprechende Bedingung an der jeweiligen Aktion.
Weiterführende Informationen
Aktions-Plugin AKDB:EPayment PayPageURL bereitstellen
Durch dieses Aktions-Plugin kann die aktuell gültige URL zur Bezahl-Transaktion ins ePay-BL-Portal aus dem Formular-Vorgang ermittet werden.
Dadurch besteht die Möglichkeit eine noch nicht abgeschlossene Bezahl-Transaktion nochmals zur Anzeige zu bringen und die Zahlung durchzuführen. Dieses Aktions-Plugin muss dabei im zeitlichen Ablauf nach dem Plugin AKDB:EPayment initialisieren konfiguriert sein.
Formular-Projekt zum Download
Hier können Sie sich ein bereits vorkonfiguriertes Formular-Projekt herunterladen.
Versionshistorie
2.3.1
- Fehlerbehebung: JavaScript-Fehler, der bei Rückleitung vom EPayment-Portal über Frontend-Server auftrat, wenn als Ziel eine Weiterleitung konfiguriert ist.
2.3.0
- Fehlerbehebung: Wenn Payment-Transaktion über Frontend-Server stattfand, wurde bei der Rückleitung vom EPayment-Portal immer auf die Formularseite weitergeleitet. Dies wurde behoben, sodass jetzt eine wieder eine explizite Abschluss-Seite oder eine externe Weiterleitung definiert werden kann
- Intern: Javascript-Sourcen auf ECMASCRIT6 angepasst
2.2.1
- Fehlerbehebung: fehlender Rückfall auf Werte aus Bundle-Properties hinzugefügt
2.2.0
- Plugin benötigt mindestens Xima® Formcycle in der Version 6.6.0+
- Fehlerbehebung: Fehlende Beschriftungen an den Eigenschaften für die Formular-Elemente EPayment ArtikelEPayment Artikel und EPayment Bestellen Button wurden behoben.
2.1.0
- Bei Speicherung einer Konfiguration im Aktions-Plugin AKDB:EPayment initialisieren wird für den betroffenen Status immer die "Unregistrierte Wiederanzeige" gestattet.
- Anpassung Template-Vorlage für Rechungsadresse: Bei einem AKDB Bürgerkonto-Login werden die zurückgelieferten Adressdaten auf Strasse und Hausnummer aufgeteilt, wenn dies möglich ist.
- Überarbeitung der Konfigurationsoberfläche des Aktions-Plugin AKDB:EPayment PayPageURL bereitstellen
- Anpassung Aktions-Plugin AKDB:EPayment initialisieren: Einstellungen für den AKDB-Mandanten werden zur Laufzeit aus den Bundle-Properties bezogen, wenn nicht explizit konfiguriert
- Internes Refactoring: Umstellung von ID auf UUID
2.0.8
- Anpassung für PDF Blanko-Druck: Absenden-Button und einzelne Bestellartikel-Definitionen werden standardmäßig aus dem Blanko-Druck entfernt.
- Bestellen-Button um Auswahlmöglichkeit für Seitenvalidierung vor Beginn des EPayment-Prozesses erweitert
2.0.7
- Anpassungen für Zusammenspiel mit AKDB Bürgerkonto-Login bei Wiederanzeige
- Einführung Transaktions-Logging um Recherche des jeweiligen Status eines Kassenzeichens durchführen zu können.
- Fehlerbehebungen
- internes Refactoring im Zusammenhang mit Einführung des Transaktions-Loggings
2.0.6
- Bereitstellung Widgets für Xima® Formcycle Designer
- Widget für Definition von Bestell-Artikeln mit Konfigurationsmöglichkeit von Beschreibung und Preis
- Widget zum Absenden einer Bestellung
- Template-Vorlagen für: Persönliche Daten, Bankverbindung, Rechnungsadresse, Lieferadresse
- Umfangreiches Überarbeitung der bestehenden Logik und der Konfigurationsoberflächen der bereitgesteelten Aktions-Plugins
2.0.5
- Fehlerbehebung: Lauffähigkeit unter Java 11 sichergestellt
2.0.4
- Projekt um Changelog- und Readme - Datei ergänzt.
2.0.3
- Anpassung im Aktions-Plugin AKDB:EPayment initialisieren: Als Rückgabewert stehen jetzt die berechneten Gesamtkosten zur Verfügung (in vollen Cent)
- Im Falle von Bestell-Gesamtkosten mit Summe "0" werden keine Transaktionsdaten übermittelt und damit keine unnötige Transaktion auf Seiten des ePay-BL Portals erzeugt.
2.0.2
- Anpassung im Pre-Renderer zum Verifizieren des PayPage Results
2.0.1
- Template-Vorlage für EPayment Rechnungsadresse hinzugefügt.
2.0.0
- Bereitstellung der Plugin-Logik für Xima® Formcycle 6.0.0+