Inhalt

Achtung:
Bevor Sie die Workflow-Aktion des ePayBL-Plugin in ihre Formular-Prozesse einbinden, stellen Sie bitte sicher, dass die konfigurative Anbindung des Dienstes durch den FORMCYCLE-Administrator erfolgt ist!

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 FORMCYCLE einzubinden wird an dieser Stelle nicht eingegangen.

Prinzipiell sind immer folgende Schritte für eine Einbindung auszuführen:

1. Formular mit "bestellbaren" Artikeln und notwendigen Dateneingaben versehen
2. Workflow konfigurieren mit:
   • einer Aktionen zum Starten einer Bezahl-Transaktion
   • Ereignissen für eine gezielten Reaktion auf Rückmeldungen vom Bezahl-Portal
3. Anzeige des Ergebnisses der Bezahl-Transaktion

Formular für den Bezahlvorgang designen

Durch die Installation des Plugins im 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.

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. 

Es können Bestellpositionen 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.

Darstellung

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.
  
  

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,  Nettobetrag)

• 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.

Steuersatz

• Der Steuersatz der auf diesen Artikel angewandt werden soll. Die Auswahlmöglichkeiten sind kein Steuersatz (0%), ermäßigter Steuersatz (7%) sowie regulärer Steuersatz (19%).

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.

Buchungstext

• Der Buchungstext ist ein optionaler Wert, welcher maximal 250 Zeichen enthalten darf (Es werden Platzhalter unterstützt). Ist die Eigenschaft gesetzt, wird dieser Wert als Buchungstext für die Bestellposition an ePayBL übermittelt. Ist der Wert nicht gesetzt wird ein Buchungstext aus Artikelnummer und Anzahl erzeugt und dieser an ePayBL übergeben.

Belegnummer

• Die Belegnummer ist ein optionaler Wert, welcher zur weiterführenden Verarbeitung auf Seiten von ePayBL dient.

Haushaltsstelle

• Die Haushaltsstelle kann optional pro Artikel definiert werden.
• Wird nichts explizit festgelegt, so wird entweder der global definierte Wert aus dem ePayBL Setup herangezogen oder der übersteuerte Wert aus der Workflow-Aktion, welche für die Verarbeitung der EPayment Artikel verantwortlich ist.

Objektnummer

• Die Objektnummer kann optional pro Artikel festgelegt werden.
• Erfolgt keine explizite Festlegung, so wird entweder der global definierte Wert aus dem ePayBL Setup herangezogen oder der übersteuerte Wert aus der Workflow-Aktion, welche für die Verarbeitung des EPayment Artikel verantwortlich ist.

Bei Übermittlung einer Bestellung werden nur die Artikelnummer, sowie die jeweilige Anzahl von einem Bestellartikel, zum Server übertragen. Damit ein Artikel innerhalb einer Bestellung übermittelt wird, muss die "Bestellen"-Option angehakt sein.

Vor dem Absenden wird die Bestellmenge für "nicht bestellte" Artikel explizit auf 0 gesetzt.

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:

Bankverbindung

• Kontoinhaber
• IBAN
• BIC

Persönliche Daten/Kundendaten

• Firmenname
• Anrede
• Vorname
• Nachname
• E-Mail

Adressdaten/Rechnungsadresse

• Postfach
• Straße
• Hausnummer
• PLZ
• Ort
• Land

Die Vorlagen "Persönliche Daten" und "Rechnungsadresse" können im Zusammenspiel mit dem Bürgerkonto-Login verwendet werden. Sie sind nach einem erfolgreichen Login am Bürgerservice automatisch vorbelegt.

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.

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:

Ablaufbeschreibung des dargestellten Workflows

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 zum formcycle Formular 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.

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.

Wenn vor der Konfiguration des Plugins bereits mindestens ein EPayment-Artikel, sowie die Vorlage für die persönlichen Daten im Formular hinterlegt wurden, werden bei der Einrichtung der Bestellung übermitteln Plugin-Aktion die Eingabefelder mit entsprechenden Platzhaltern befüllt.

Falls das Formular im Nachhinein angepasst wurde, können über den Update-Button (Aktualisieren und validieren) erneut die Eingabefelder mit entprechenden Platzhaltern befüllt werden.

Die Konfigurationsoberfläche des Aktions-Plugins ist in einzelne Bereiche unterteilt die nachfolgend kurz beschrieben werden.

Kurzinfo der Plugin-Aktion

Rückgabewerte der Workflow-Aktion

[%$[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:

[%$[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 (in Euro)

[%$[Name der Aktion].RESULT.Kassenzeichen%]

• Das aktuelle Kassenzeichen unter dem die Zahlungstransaktion im ePayBL Portal geführt wird

[%$[Name der Aktion].RESULT.TxNummer%]

• Das aktuelle Transaktionsnummer für die Bezahltransaktion

[%$[Name der Aktion].RESULT.UrlToPaypage%]

• Die URL zur Bezahlseite auf Seiten von ePayBL, wo die Bezahlung der aktuellen Transaktion durchgeführt werden kann

[%$[Name der Aktion].RESULT.ZahlungsvorgangsId%]

• Das aktuelle ZahlvorgangsId für die Bezahltransaktion aus dem ePayBL Portal

Fehlercodes der Workflow-Aktion

• Fehlercode, wenn die Kombination aus Zertifikat und Zertifikatspasswort in der ePayBL Konfiguration nicht valide ist.

• Fehlercode für einen nicht nähere beschriebenen Fehler. Bei Auftreten von solchen Fehlertypen sollte das
  FORMCYCLE interne Fehler-Protokoll für eine tiefere Analyse einbezogen werden.+

• Fehlercode, wenn die URL in der ePayBL Konfiguration nicht valide ist.

• Fehlercode, wenn Pflichtparameter für einen Verbindungsaufbau in der ePayBL Konfiguration fehlen. Pflichtparameter sind die URL, Mandant- und Bewirtschafter-Nummer.

• Fehlercode, wenn keine ePayBL Konfiguration aus dem System (oder Mandant-Bereich) ermittelt werden konnte.

• Fehlercode, wenn zur Laufzeit keine Bestellpositionen übermittelt wurden. Diese kann beispielweise auftreten, wenn der Formular-Nutzer beispielsweise keine Artikel zum Bestellen ausgewählt hatte oder auch Angaben wie Haushaltstelle oder Objektnummer fehlen.

• Fehlercode, wenn eine ePayBL Webservice-Methode einen Fehler lieferte. Bei Auftreten von solchen Fehlertypen sollte das FORMCYCLE interne Fehler-Protokoll für eine tiefere Analyse einbezogen werden.

• Fehlercode, wenn der ePayBL Service nicht verfügbar ist.

• Fehlercode, wenn die zurückgelieferte Antwort nicht weiter verarbeitet werden kann. Die Konfiguration ist fehlerhaft. Dieser Fehler tritt oft auf, wenn der falsche Pfad einer URL abgefragt wird.

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.paymentMethod%]

• Parameter gibt Auskunft über das in der Bezahl-Transaktion angewendete Zahlverfahren

[%$TRIGGER.paymentProcessId%]

• Parameter gibt Auskunft über die ZahlungsvorgangsId der ausgeführten Bezahl-Transaktion

[%$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

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.paymentMethod%]

• Parameter gibt Auskunft über das in der Bezahl-Transaktion angewendete Zahlverfahren

[%$TRIGGER.paymentProcessId%]

• Parameter gibt Auskunft über die ZahlungsvorgangsId der ausgeführten Bezahl-Transaktion

[%$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.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

[%$TRIGGER.paypageUrl%]

• URL zur Paypage mit der aktuellen Transaktionsnummer. Damit ist ein nochmaliges Aufrufen und Bezahlen der offenen Transaktion möglich.

Ergebnisanzeige

Das Plugin stellt für beide Workflow-Ereignisse Standard HTML-Templates bereit. Diese werden automatisch ausgeliefert und können nicht bearbeitet werden. Eine eigene HTML-Abschlussseite kann durch die entsprechende Workflow-Aktion ausgeliefert werden und ein HTML-Template muss im Formular oder im Mandanten angelegt werden. Folgendes Beispiel kann als Grundlage genommen werden und beinhaltet Standard-CSS von formcycle:

<style type="text/css">
.xfc-template-body {width: 100%; height:100%; background-color: #EDEDED; margin: 0;}
.xfc-template {width: 100%; height:100%; font-family: Helvetica; font-size: 14px; background-color: #EDEDED}
.xfc-template H1 {font-size: 32px; color: #0082B4; padding: 20px 0; margin: 0;}
.xfc-template H2 {font-size: 18px; font-weight: normal; color: #000000; padding-bottom: 20px; margin: 0;}
.xfc-template DIV[lang] {margin: 0 auto; min-width: 300px; max-width: 750px; background-color: #FFFFFF;}
.xfc-template DIV.content { padding: 30px 60px 20px 60px;}
.xfc-template DIV.header {border-bottom: 1px solid #CCCCCC; background-color: #F7F7F7; padding: 0 60px;}
.xfc-template DIV.footer {border-top: 1px solid #CCCCCC; background-color: #F7F7F7; padding: 0 60px; font-size:12px; height: 20px; padding: 20px 60px 30px 60px;}
.xfc-template INPUT {border-color: #CCCCCC; color: #0082b4; border-radius: 4px; border-style: solid; border-width: 1px; padding: 7px 11px;}
</style>
<div class="xfc-template">
   <div lang="de">
      <div class="header">
         <h1>Die Bezahlung wurde erfolgreich durchgeführt.</h1>
      </div>
   </div>
</div>

In das Template können Platzhalter eingefügt werden und diese werden entprechend ersetzt. Um den Grund für einen Fehlschlag bei der Transaktion auf der Abschlussseite anzugeben sollte zB. der Platzhalter [%$TRIGGER.paymentStatusText%] verwendet werden.