Verwendung
Plugin download (Anmeldung erforderlich)
Das kostenpflichtige ePayBL EPayment Plugin ermöglicht es, über das ePayBL 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
- Workflow konfigurieren mit:
- einer Aktionen zum Starten einer Bezahl-Transaktion
- Ereignissen für eine gezielten Reaktion auf Rückmeldungen vom Bezahl-Portal
- Anzeige des Ergebnisses der Bezahl-Transaktion
1. Formular für den Bezahlvorgang designen
Durch die Installation des Plugins im Xima® Formcycle-System sind im Designer ein zusätzliches Element, 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, Beschreibung, Preisangabe, Eingabemöglichkeit für Bestellmenge) innerhalb eines Formulars, als auch als Vorlage für die Erstellung einer konkreten Bestellposition zum Zeitpunkt der Ausführung einer Bezahl-Transaktion.
Bestellpositionen können auch direkt in der Workflow-Aktion definiert werden.
Dadurch muss kein EPayment Artikel zwingend im Formular vorhanden sein. Bei Konfiguration der Workflow-Aktion Bestellung übermitteln wird geprüft, dass mindestens ein EPayment Artikel im Formular oder eine Bestellposition direkt in der Workflow-Aktion vorhanden ist.
Grundeigenschaften:
- Versteckt
- Durch das Auswählen dieser Option wird es möglich einen Bestellartikel vor dem Nutzer zu verbergen.
Wenn gleichzeitig dazu noch die Option Pflicht-Artikel ausgewählt wird, so wird beim Absenden des Formulars dieser Artikel automatisch der Bestellung hinzugefügt. - Dies kann immer dann sinnvoll 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:
- Pflicht-Artikel
- Diese Option ermöglicht es, einen Artikel als ausgewählt zu markieren, sodass er beim Absenden des Formulars automatisch der Bestellung hinzugefügt wird.
- Beschreibung
- Nähere Beschreibung eines Artikels
- Artikel-Preis (in Euro)
- Der Preis für einen Artikel. Der an dieser Stelle konfigurierte Wert dient zum Einen für die Anzeige innerhalb des Formulars, als auch zur Berechnung der Gesamtsumme im Fall einer Bestellung des Artikels.
- 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.
- Max. Bestellmenge
- Hier kann die für den Nutzer maximal auswählbare Bestellmenge für einen Artikel definiert werden.
- Belegnummer
- Die Belegnummer ist ein optionaler Wert, welcher zur weiterführenden Verarbeitung auf Seiten von ePayBL dient.
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. Bestellung an den Server übermitteln:
Um eine Bestellung auszulösen und die bestellten Artikel zum Server zu übertragen muss dem Formular eine Senden-Schaltfläche hinzugefügt werden.
2. Workflow für EPayment konfigurieren
Um eine Bezahl-Transaktion in einen Formularprozess einzubauen werden folgende Elemente vom Plugin zur Verfügung gestellt:
- Workflow-Aktion Bestellung übermitteln: Diese erzeugt eine neue Bezahl-Transaktion auf Seiten des ePayBL Anbieters und leitet den Benutzer auf dessen Portalseite weiter.
- Workflow-Ereignis Bezahlung erfolgreich: Verarbeitet ein Ereignis, welches auf der Rückmeldung über eine erfolgreiche Bezahlung auf dem ePayBL Portal basiert.
- Workflow-Ereignis Bezahlung nicht erfolgreich: Verarbeitet ein Ereignis, welches auf der Rückmeldung über eine noch offene Bezahlung auf dem ePayBL Portal basiert. Dabei kann dies verschiedene Ursachen haben. Zum einen kann die Bezahlvorgang durch den Nutzer abgebrochen worden sein oder es ist zu einem Fehler im ePayBL Portal gekommen.
Ein Workflow für einen einfachen Fall kann folgendermaßen konfiguriert sein:
Kurze Ablaufbeschreibung zum dargestellten Workflow:
1. Durch das Absenden des Bestellformulars wird das Ereignis Bestellen aufgerufen und dort das Aktions-Plugin ePayBL:Bestellung übermitteln ausgeführt. Dieses ermittelt die für den Bestellvorgang notwendigen Daten aus dem Formular und startet eine Bezahl-Transaktion auf Seiten des ePayBL Anbieters. Wenn dies erfolgreich war, wird der Benutzer zum ePayBL Portal der angebundenden Umgebung weitergeleitet.
2. Nach Abschluss des Bezahlvorgangs im ePayBL Portal wird der Benutzer wieder zu Xima® Formcycle zurückgeleitet. Dort erfolgt automatisch eine Überprüfung des Bezahlstatus am EPayment-System. Aus dem Ergebnis dieser Überprüfung ergibt sich das vom System ausgelöste Ereignis. Wenn die Überprüfung ergeben hat, dass die Bezahlung erfolgreich war, wird ein Bezahlung erfolgreich-Ereignis durch das System ausgelöst. In allen anderen Fällen ist es ein Bezahlung nicht erfolgreich Ereignis.
3. Ist die Bezahlung erfolgt, wird in den Status Bezahlt gewechselt und dem Nutzer wird eine entsprechende Abschlussseite angezeigt.
4. Im Falle eines negativen Ergebnisses der Überprüfung des Bezahlvorgangs (z.B.: der Nutzer hat den Bezahlvorgang im ePayBL Portal abgebrochen; während des Bezahlvorgangs ist ein Fehler aufgetreten), wird im vorliegenden Beispiel eine E-Mail erzeugt, in der der Benutzer auf die noch ausstehende Zahlung hingewiesen wird. Der Workflow wird in den Status Nicht bezahlt versetzt und dem Nutzer
wird eine entsprechende Abschlussseite angezeigt.
2.1. Konfigurationsmöglichkeiten des Aktions-Plugins Bestellung übermitteln
Dieses Aktions-Plugin ist für das Erzeugen einer Bezahl-Transaktion im ePayBL 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 etc.), festgelegt.
Die Konfigurationsoberfläche des Aktions-Plugins ist in einzelne Bereiche unterteilt die nachfolgend kurz beschrieben werden.
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
- Mobiltelefon
Konfiguration für die PayPage
- Automatische Weiterleitung zur PayPage verhindern
- Bei aktivierter Einstellung kann eine automatische Weiterleitung zur PayPage unterbunden werden.
- 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 globale Einstellung für den Fälligkeitszeitraum wird nicht beachtet.
- Buchungstext auf PayPage
- Der hier festgelegte Buchungstext wird dem Benutzer auf der PayPage angezeigt.
- Eingabe muss dem Pattern ^[\w\-\./+\ @,\:\&\'\?\#{}\(\)\[\]\u00C0-\u017F\u1E9E]*$ entsprechen.
- Server für die Rücksprungadresse
- Der Standardwert ist ein Platzhalter, welcher den aktuellen Server zurück gibt. Aktuell richtet sich hier nach dem Zeitpunkt und Ort der Ausführung der "Bestellung übermitteln" Aktion. Falls die Aktion auf einem anderen Server ausgeführt wird (z.B.: im Postfach), jedoch das Formular auf einem Frontend-Server ausgeliefert wird, muss dieser Frontend-Server hier ausgewählt werden. Ansonsten wird nach Abschluss der Bezahlung zurück auf Server geleitet, welcher möglicherweise nicht erreichbar ist für den/die Antragssteller*in.
Definition zusätzlicher Bestellpositionen
- Anzahl
- Definiert die für die Bestellposition geltende Anzahl. Der hier definierte Wert muss zur Laufzeit einer Zahl größer 0 entsprechen, damit die Bestellposition mit in die aktuelle Bestellung einbezogen wird. Die Anzahl dient weiterhin zur Berechnung des Gesamtpreises der Bestellposition innerhalb der Bestellung
- Buchungstext
- Der hier definierte Text wird als Buchungstext übermittelt. Er darf nur aus SEPA-konformen Zeichen bestehen und maximal 21 Zeichen lang sein. Der Text kann dabei auch aus Platzhaltern stammen. Er wird, wenn dies notwendig ist, automatisch auf 21 Zeichen eingekürzt.
- Netto-Preis (in Euro)
- Der (Einzel)Netto-Preis für die Bestellposition. Der an dieser Stelle konfigurierten Wert muss sich in eine kommaseparierte Zahl umwandeln lassen und dient zur Berechnung der Gesamtsumme für die Bestellposition. (Berechnung: Gesamtpreis = Anzahl x Preis)
- Steuersatz in %
- Der anzuwendende Steuersatz ist frei wählbar und wird mit den oben genannten Netto-Preis verrechnet zum endgültigen Brutto-Preis.
- Beschreibung
- Dient der interne Beschreibung der Bestellposition. Diese Information wird nicht an ePayBL weiter gegeben.
- Belegnummer
- Die Belegnummer ist ein optionaler Wert, welcher zur weiterführenden Verarbeitung auf Seiten von ePayBL dient.
Konfiguration ePayBL ePayment-Mandant
- Mandant-Nummer
- ePayBL-Mandantennummer des aufrufenden eShops (FORMCYCLE) (Wird durch ePayBL-System vorgegeben)
- Bewirtschafter-Nummer
- Bewirtschafternummer (Wird durch ePayBL-System vorgegeben)
- Haushaltsstelle
- Nummer der Haushaltsstelle, welcher die Buchung zugeordnet werden soll. (Wird durch ePayBL-System vorgegeben)
- Objektnummer
- Dient der internen Verbuchung im EPayment-System. (Wird durch ePayBL-System vorgegeben)
- Kennzeichen-Mahnverfahren
- Einstellung für das Kennzeichen in einem Mahnverfahren. (Mögliche Werte werden durch ePayBL-System vorgegeben)
- Fälligkeitszeitraum
- Einstellung für die Berechnung des Fälligkeitszeitraumes der Zahlung (Dauer in Tagen).
2.1.1 Rückgabewerte der Workflow-Aktion
Rückgabewerte
- [%$[Name der Aktion].RESULT.BestellPosition[i]['key']%]
- Eine Auflistung über alle Bestell-Positionen, welche in der aktuellen Bestellung enthalten sind.
Zu jeder Bestell-Position können folgende Werte abgefragt werden:
- Artikelnummer: Die am EPayment Artikel hinterlegte eindeutige Kennung für den Artikel
- Buchungstext: Der übermittelte Buchungstext (max.21 Zeichen, SEPA konform)
- Menge: Die bestellte Menge für die aktuelle Bestell-Position
- Beschreibung: Die am EPayment Artikel hinterlegte Artikel-Beschreibung
- Einzelpreis: Der am EPayment Artikel hinterlegte Preis für ein Stück. Ausgabe mit Währungssymbol.
- Preis: Der errechnete Gesamtpreis für die aktuelle Bestell-Position. Ergibt sich aus Menge x Einzelpreis. Ausgabe mit Währungssysmbol
Nachfolgend einige Beispiele für die Datenabfrage aus den Bestellpositionen:
Für die Beispiele wird folgender durch eine Aktion mit Namen Bestellung übermitteln bereitgestellter Platzhalter zu Grunde
gelegt: [%$Bestellung übermitteln.RESULT.Bestellung[i][''key'']%]
Die in den eckigen Klammern hinterlegten Werte sind variabel und haben folgende Bedeutung:
- i: Zählvariable für den Zugriff auf eine Bestell-Position aus der Gruppe aller Bestell-Positionen. Ein möglicher Wert muss sich im Bereich von 0 bis zum Wert der BestellPositionAnzahl -1 befinden.
- key: Schlüssel für den Zugriff auf die jeweilige Eigenschaft
Beispiele:
Abfrage des Einzelpreises an der 1. Bestell-Position: [%$Bestellung übermitteln.RESULT.Bestellung[0][''Einzelpreis'']%]
Abfrage der Menge an der 3. Bestell-Position: [%$Bestellung übermitteln.RESULT.Bestellung[2][''Menge'']%]
- [%$[Name der Aktion].RESULT.BestellPositionAnzahl%]
- Die Gesamtanzahl der Bestellpositionen, welche in der aktuellen Bestellung enthalten sind
- [%$[Name der Aktion].RESULT.Gesamtbetrag%]
- Der in der Zahlungstransaktion ausgewiesene zu zahlende Geldbetrag. Angabe in Euro
- [%$[Name der Aktion].RESULT.Kassenzeichen%]
- Das aktuelle Kassenzeichen unter dem die Zahlungstransaktion im ePayBL Portal geführt wird.
- [%$[Name der Aktion].RESULT.UrlToPaypage%]
- Die URL zur Bezahlseite auf Seiten von ePayBL, wo die Bezahlung der aktuellen Transaktion durchgeführt werden kann.
Fehlercodes
- NO_ORDER_DATA
- Fehlercode, wenn zur Laufzeit keine Bestellpositionen übermittelt wurden. Diese kann beispielweise auftreten, wenn der Formular-Nutzer beispielsweise keine Artikel zum Bestellen ausgewählt hatte.
- SRV_NOT_AVIALABLE
- Fehlercode, wenn der ePayBL Service nicht verfügbar ist.
- SRV_METHOD_ERROR
- Fehlercode, wenn eine ePayBL Webservice-Methode einen Fehler lieferte. Bei Auftreten von solchen Fehlertypen sollte das
Xima® Formcycle interne Fehler-Protokoll für eine tiefere Analyse einbezogen werden. - INTERNAL_ERROR
- Fehlercode für einen nicht nähere beschriebenen Fehler. Bei Auftreten von solchen Fehlertypen sollte das
Xima® Formcycle interne Fehler-Protokoll für eine tiefere Analyse einbezogen werden.
2.2. Workflow-Ereignis Bezahlung erfolgreich
Eine Workflow-Verarbeitungskette mit diesem Ereignis wird ausgeführt, wenn eine Rückleitung aus dem ePayBL Portal erfolgt
und die Bezahlung erfolgreich durchgeführt wurde. Pro Formular-Vorgang kann dieses Ereignis genau einmal eintreten.
Das Ereignis stellt dabei folgende Werte bereit, die per Platzhalter in nachfolgenden Aktionen ausgewertet werden können:
- [%$TRIGGER.paymentStatus%]
- Bezeichnung des Status, wie er vom ePayBL Portal zurück geliefert wird. (Möglicher Wert: INAKTIV)
- [%$TRIGGER.paymentStatusText%]
- Eine Nachricht, die den zurück gelieferten Status näher beschreibt
- [%$TRIGGER.paymentMethod%]
- Parameter gibt Auskunft über das in der Bezahl-Transaktion angewendete Zahlverfahren
2.3. Workflow-Ereignis Bezahlung nicht erfolgreich
Eine Workflow-Verarbeitungskette mit diesem Ereignis wird immer dann ausgeführt, wenn eine Rückleitung aus dem ePayBL Portal erfolgte
und die Bezahlung nicht durchgeführt wurde. Pro Formular-Vorgang kann dieses Ereignis mehrfach eintreten (Bei Fehlern im ePayBL Portal oder bei Abbruch des Bezahlvorgangs durch den Nutzer).
Das Ereignis stellt folgende Werte bereit, die per Platzhalter in nachfolgenden Aktionen ausgewertet werden können:
- [%$TRIGGER.paymentStatus%]
- Bezeichnung des Status, wie er vom ePayBL Portal zurückgeliefert wird.
- Folgende Werte sind möglich:
- AKTIV: Die Bezahlung über die PayPage ist noch nicht erfolgt (z.B. weil der Nutzer den Bezahlvorgang auf Seiten von ePayBL abgebrochen hat).
- 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
- [%$TRIGGER.paymentStatusText%]
- Eine Nachricht, die den zurückgelieferten Status näher beschreibt
- [%$TRIGGER.paypageUrl%]
- URL zur Paypage mit der aktuellen Transaktionsnummer. Damit ist ein nochmaliges Aufrufen und Bezahlen der offenen Transaktion möglich.
- [%$TRIGGER.paymentMethod%]
- Parameter gibt Auskunft über das in der Bezahl-Transaktion angewendete Zahlverfahren
- [%$TRIGGER.paymentVerifyUrl%]
- URL zum erneuten Prüfen des Bezahlstatus. Ein Aufruf der URL löst im Anschluss, an die Überprüfung des aktuellen Bezahlstatus, die entsprechenden Workflow-Ereignisse aus
3. Ergebnisanzeige
Die Anzeige des Ergebnisses bzw. des Status einer Bezahl-Transaktion erfolgt standardmäßig mittels einer extra Abschluss-Seite.
Dafür stellt das Plugin 3 HTML-Templates bereit:
- ePayBL ePayment Bezahlung Erfolg: Standard-Template für Anzeige bei erfolgreich abgeschlossener Bezahlung.
- ePayBL ePayment Bezahlung Fehler: Standard-Template für Anzeige bei offenen bzw. fehlerhaft beendeten Bezahlvorgang. Dieser Template enthält Platzhalter für Anzeige des konkreten Fehlers und einen Link zum Wiederaufruf des noch ausstehenden Bezahlvorgangs.
- ePayBL ePayment Fehler: Standard-Template für Anzeige bei allgemeinen technischen Fehlern. Der genaue Fehler wird mittels enthaltener Platzhalter ausgewiesen.