Wiki-Quellcode von Verwendung

Zeige letzte Bearbeiter
1 {{info}}
2 **Achtung:**
3 Bevor Sie die AKDB EPayment in ihren Formular-Prozessen einbinden, stellen Sie bitte sicher, dass die konfigurative Anbindung des Dienstes durch den {{formcycle/}}-Administrator erfolgt ist!
4 {{/info}}
5
6 Das kostenpflichtige AKDB EPayment Plugin ermöglicht es, über das von der AKDB bereitgestellte [[ePay-BL Portal>>https://www.epaybl.de/||rel="noopener noreferrer" target="_blank" title="E-Payment Bund und Länder"]], einen Bezahlvorgang in einen Formularprozess einzubauen.
7
8 Der nachfolgende Artikel beschreibt beispielhaft die von einen Formular-Ersteller auszuführenden Schritte, um einen Bezahlvorgang in einem Formular zu integrieren.
9 Auf die notwendigen Schritte, um den Service technisch in {{formcycle/}} einzubinden wird an dieser Stelle nicht eingegangen.
10
11 {{id name="config_reihenfolge"/}}
12 Prinzipiell sind immer folgende Schritte für eine Einbindung auszuführen:
13
14 1. Formular mit "bestellbaren" Artikeln und notwendigen Dateneingaben versehen
15 1. Workflow konfigurieren mit:
16 1*. einer Aktionen zum Starten einer Bezahl-Transaktion
17 1*. Ereignissen für eine gezielten Reaktion auf Rückmeldungen vom Bezahl-Portal
18 1. Anzeige des Ergebnisses der Bezahl-Transaktion
19
20 == 1. Formular für den Bezahlvorgang designen ==
21
22 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.
23
24 {{id name="epay_artikel"/}}
25
26 === 1.1. Artikel definieren durch das Formular-Element: //EPayment Artikel//: ===
27
28 {{figure image="hilfe_epay_artikel_form.png"}}
29 Konfigurationsmöglichkeiten am Formular-Element //EPayment Artikel//
30 {{/figure}}
31
32 Über das Formular-Element //EPayment Artikel// werden die für eine Bestell-Transaktion notwendigen Artikel definiert.
33 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 Erstellung einer
34 konkreten Bestell-Position zum Zeitpunkt der Ausführung einer Bezahl-Transaktion.
35
36 __Grundeigenschaften:__
37
38 ; Versteckt
39 : Durch das Auswählen dieser Option wird es möglich einen Bestellartikel vor dem Nutzer zu verbergen.
40 Wenn gleichzeitig dazu noch die Option **Pflicht-Artikel** ausgewählt wird, so wird beim Absenden des Formulars dieser Artikel automatisch der Bestellung hinzugefügt.
41 : 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.
42
43 __EPayment Bestellartikel Einstellungen:__
44
45 ; Pflicht-Artikel
46 : Diese Option ermöglicht es, einen Artikel als ausgewählt zu markieren, sodass er beim Absenden des Formulars automatisch der Bestellung hinzugefügt wird.
47 ; Beschreibung
48 : Nähere Beschreibung eines Artikels
49 ; Artikel-Preis (in Euro)
50 : 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.
51 ; Artikelnummer
52 : 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.
53 ; Max. Bestellmenge
54 : Hier kann die für den Nutzer maximal auswählbare Bestellmenge für einen Artikel definiert werden.
55 ; Belegnummer
56 : Die Belegnummer ist ein optionaler Wert, welcher zur weiterführenden Verarbeitung auf Seiten von ePay-BL dient
57
58 {{info}}
59 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.
60 {{/info}}
61
62 {{id name="epay_vorlage"/}}
63
64 === 1.2. Vorlagen zur Ermittlung von Bestellinformationen: ===
65
66 {{figure image="hilfe_epay_vorlagen_form.png"}}
67 Vorlagen zur Datenerhebung für das EPayment
68 {{/figure}}
69
70 Durch das Plugin werden verschiedene Designer-Vorlagen bereitgestellt, mit denen es ermöglicht wird die nachfolgend aufgeführten Daten vom Benutzer zu ermitteln:
71
72 * **Persönliche Daten**: Anrede, Name, Vorname, E-Mail etc.
73 * **Rechnungsadresse**
74 * **Lieferadresse**
75 * **Bankverbindung**
76
77 {{info}}
78 Die Vorlagen "Persönliche Daten" und "Rechnungsadresse" können im Zusammenspiel mit dem //Bürgerkonto-Login// der AKDB verwendet werden. Sie werden nach einem erfolgreichen Login automatisch vorbelegt.
79 {{/info}}
80
81 {{id name="epay_btn"/}}
82
83 === 1.3. Bestellung an den Server übermitteln: ===
84
85 Um eine Bestellung auszulösen und die bestellten Artikel zum Server zu übertragen muss dem Formular eine //Senden//-Schaltfläche hinzugefügt werden.
86 \\{{id name="config_process"/}}
87
88 == 2. Workflow für EPayment konfigurieren ==
89
90 Um eine Bezahl-Transaktion in einen Formularprozess einzubauen werden folgende Elemente vom Plugin zur Verfügung gestellt:
91
92 * Workflow-Aktion **[[Bestellung übermitteln>>doc:||anchor="plugin_epay_init"]]**: Diese erzeugt eine neue Bezahl-Transaktion auf Seiten der AKDB und leitet den Benutzer auf dessen Portalseite weiter.
93 * Workflow-Ereignis **[[Bezahlung erfolgreich>>doc:||anchor="plugin_event_epay_success"]]**: Verarbeitet ein Ereignis, welches auf der Rückmeldung über eine erfolgreiche Bezahlung auf dem ePay-BL Portal basiert.
94 * Workflow-Ereignis **[[Bezahlung nicht erfolgreich>>doc:||anchor="plugin_event_epay_error"]]**: Verarbeitet ein Ereignis, welches auf der Rückmeldung über eine noch offene Bezahlung auf dem ePay-BL 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 ePay-BL Portal gekommen.
95
96 Ein Workflow für einen einfachen Fall kann folgendermaßen konfiguriert sein:
97
98 {{figure image="hilfe_workflow.png"}}
99 Workflow mit EPayment Anbindung
100 {{/figure}}
101
102 __Kurze Ablaufbeschreibung zum dargestellten Workflow:__
103
104 ~1. Durch das Absenden des Bestellformulars wird das Ereignis //Bestellen// aufgerufen und dort das Aktions-Plugin **[[AKDB:Bestellung übermitteln>>doc:||anchor="plugin_epay_init"]]** ausgeführt. Dieses ermittelt die für den Bestellvorgang notwendigen Daten aus dem Formular und startet eine Bezahl-Transaktion auf Seiten der AKDB. Wenn dies erfolgreich war, wird der Benutzer zum [[ePay-BL>>https://www.epaybl.de/||rel="noopener noreferrer" target="_blank" title="E-Payment Bund und Länder"]] Portal der AKDB weitergeleitet.
105
106 2. Nach Abschluss des Bezahlvorgangs im ePay-BL Portal wird der Benutzer wieder zu {{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>>doc:||anchor="plugin_event_epay_success"]]**-Ereignis durch das System ausgelöst. In allen anderen Fällen ist es ein **[[Bezahlung nicht erfolgreich>>doc:||anchor="plugin_event_epay_error"]]** Ereignis.
107
108 3. Ist die Bezahlung erfolgt, wird in den Status //Bezahlt// gewechselt und dem Nutzer wird eine entsprechende Abschlussseite angezeigt.
109
110 4. Im Falle eines negativen Ergebnisses der Überprüfung des Bezahlvorgangs (z.B.: der Nutzer hat den Bezahlvorgang im ePay-BL 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
111 wird eine entsprechende Abschlussseite angezeigt.
112
113 {{id name="plugin_epay_init"/}}
114
115 === 2.1. Konfigurationsmöglichkeiten des Aktions-Plugins //Bestellung übermitteln// ===
116
117 Dieses Aktions-Plugin ist für das Erzeugen einer Bezahl-Transaktion im [[ePay-BL>>https://www.epaybl.de/||rel="noopener noreferrer" target="_blank" title="E-Payment Bund und Länder"]] 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.
118
119 {{info}}
120 Wenn vor der Konfiguration des Plugins bereits mindestens ein **[[EPayment-Artikel>>doc:||anchor="epay_artikel"]]**, sowie die **[[Vorlage>>doc:||anchor="epay_vorlage"]]** für die **persönlichen Daten** im Formular hinterlegt wurden, werden bei einer Neueinrichtung der //Bestellung übermitteln// Plugin-Aktion die notwendigen Pflicht-Konfigurationen bereits mit den ermittelten Daten aus dem Formular vorbelegt.
121
122 Es empfiehlt sich deshalb die in diesem Artikel beschriebene [[Konfigurations-Reihenfolge>>doc:||anchor="config_reihenfolge"]] einzuhalten.
123
124 Es ist aber auch möglich das Formular im Nachhinein anzupassen und anschließend die Daten innerhalb des Aktions-Plugins zu aktualisieren.
125 {{/info}}
126
127 Die Konfigurationsoberfläche des Aktions-Plugins ist in einzelne Bereiche unterteilt die nachfolgend kurz beschrieben werden.
128
129 {{panel title="Kundenstammdaten" fullwidth="true" initial="visible" triggerable="true"}}
130
131 {{figure image="plugin_init_config_kundenstammdaten.png"}}
132 Konfiguration für die Kundenstammdaten
133 {{/figure}}
134
135 In diesem Bereich werden die Daten des Benutzers hinterlegt, für den die Bezahl-Transaktion erzeugt werden soll.
136 Die einzelnen Parameter können per Platzhalter oder fest definiert hinterlegt werden.
137
138 {{info}}
139 Über den [[image:icon_update.png]]-Button können diese Felder durch Nutzung der EPayment-Vorlage //Persönliche Daten// vorbelegt werden.
140 {{/info}}
141
142 ; Anrede
143 ; Titel
144 ; Vorname
145 ; Nachname (Pflichtfeld)
146 ; Geburtsdatum
147 : Geburtsdatum muss in der Form **dd.MM.yyyy** übermittelt werden.
148 ; E-Mail
149 : Wird für die Zustellung von Emails an den Kunden in Abhängigkeit von der ePay-BL-Mandantkonfiguration benötigt.
150 ; Telefon
151 ; Mobiltelefon
152
153 {{/panel}}
154
155 {{id name="config_paypage"/}}
156
157 {{panel title="Konfiguration für die PayPage" fullwidth="true" initial="visible" triggerable="true"}}
158
159 Bei der "PayPage" handelt es sich um eine bereits vorbefüllte Bezahlseite zur Online-Bezahlung. Der Nutzer hat hier noch die Auswahl, mit welchem Bezahl-Dienstleister er bezahlen möchte (Paypal, SEPA-Lastschrift, giropay etc.). Die Art und Anzahl der dem Nutzer zur Auswahl stehenden Bezahl-Dienstleister hängt dabei davon ab, was im Vorfeld vertraglich mit der AKDB verbart wurde.
160
161 {{figure image="plugin_init_config_paypage.png"}}
162 Konfiguration für die PayPage
163 {{/figure}}
164
165 ; Automatische Weiterleitung zur PayPage verhindern
166 : Bei aktivierter Einstellung kann eine automatische Weiterleitung zur PayPage unterbunden werden.
167 ; Fälligkeitsdatum
168 : 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.
169 ; Buchungstext auf PayPage
170 : Der hier festgelegte Buchungstext wird dem Benutzer auf der PayPage angezeigt.
171 {{/panel}}
172
173 {{panel title="Konfiguration AKDB ePayment-Mandant" fullwidth="true" initial="visible" triggerable="true"}}
174
175 {{figure image="plugin_init_config_akdb_mandant.png"}}
176 Konfiguration AKDB EPayment-Mandant
177 {{/figure}}
178
179 In diesem Bereich können die globalen Einstellungen für den zu verwendenden ePay-BL Mandanten übersteuert werden. Die Einstellungen zum ePay-BL Mandanten sind notwendig, um später die Transaktion auf Seiten von ePay-BL
180 der richtigen Behörde (entspricht der festgelegten Mandant-Nummer), dem Bewirtschafter und der Haushaltsstelle zuzuordnen.
181 In den meisten Fällen sind diese Einstellungen bereits durch einen Plugin-Administrator global hinterlegt worden, sodass an dieser Stelle keine Konfiguration notwendig ist.
182
183 Die einzelnen Parameter können per Platzhalter oder fest definiert hinterlegt werden. Weiterhin kann über den Button [[image:icon_update.png]] //Webservice Erreichbarkeit prüfen// die generelle Erreichbarkeit des EPayment Webservice geprüft werden.
184
185 ; Mandant-Nummer
186 : AKDB-Mandantennummer des aufrufenden eShops (FORMCYCLE) (Wird durch ePay-BL-System vorgegeben)
187 ; Bewirtschafter-Nummer
188 : Bewirtschafternummer (Wird durch ePay-BL-System vorgegeben)
189 ; Haushaltsstelle
190 : Nummer der Haushaltsstelle, welcher die Buchung zugeordnet werden soll. (Wird durch ePay-BL-System vorgegeben)
191 ; Objektnummer
192 : Dient der internen Verbuchung im EPayment-System. (Wird durch ePay-BL-System vorgegeben)
193 ; Kennzeichen-Mahnverfahren
194 : Einstellung für das Kennzeichen in einem Mahnverfahren. (Mögliche Werte werden durch ePay-BL-System vorgegeben)
195 ; Fälligkeitszeitraum
196 : Einstellung für die Berechnung des Fälligkeitszeitraumes der Zahlung (Dauer in Tagen).
197
198 {{/panel}}
199
200 {{id name="plugin_event_epay_success"/}}
201
202 === 2.2. Workflow-Ereignis //Bezahlung erfolgreich// ===
203
204 Eine Workflow-Verarbeitungskette mit diesem Ereignis wird ausgeführt, wenn eine Rückleitung aus dem ePay-BL Portal erfolgt
205 und die Bezahlung erfolgreich durchgeführt wurde. Pro Formular-Vorgang kann dieses Ereignis genau einmal eintreten.
206 Das Ereignis stellt dabei folgende Werte bereit, die per Platzhalter in nachfolgenden Aktionen ausgewertet werden können:
207
208 ; **[%$TRIGGER.paymentStatus%]**
209 : Bezeichnung des Status, wie er vom ePay-BL Portal zurückgeliefert wird. (Möglicher Wert: INAKTIV)
210 ; **[%$TRIGGER.paymentStatusText%]**
211 : Eine Nachricht, die den zurückgelieferten Status näher beschreibt
212
213 {{id name="plugin_event_epay_error"/}}
214
215 === 2.3. Workflow-Ereignis //Bezahlung nicht erfolgreich// ===
216
217 Eine Workflow-Verarbeitungskette mit diesem Ereignis wird immer dann ausgeführt, wenn eine Rückleitung aus dem ePay-BL Portal erfolgte
218 und die Bezahlung nicht durchgeführt wurde. Pro Formular-Vorgang kann dieses Ereignis mehrfach eintreten (Bei Fehlern im ePay-BL Portal oder bei Abbruch des Bezahlvorgangs durch den Nutzer).
219 Das Ereignis stellt folgende Werte bereit, die per Platzhalter in nachfolgenden Aktionen ausgewertet werden können:
220
221 ; **[%$TRIGGER.paymentStatus%]**
222 : Bezeichnung des Status, wie er vom ePay-BL Portal zurückgeliefert wird.
223 : Folgende Werte sind möglich:
224 : **AKTIV**: Die Bezahlung über die PayPage ist noch nicht erfolgt.
225 : **MANDANT_NICHT_GEFUNDEN**: Der Mandant wurde im ePayment-System nicht gefunden.
226 : **MANDANT_INAKTIV**: Der Mandant ist im ePayment-System derzeit als inaktiv gekennzeichnet.
227 : **VERBINDUNG_OHNE_HTTPS**: Die Verbindung zum Webservice erfolgte nicht über HTTPS mit Client-Zertifikaten.
228 : **VERBINDUNG_ZERTIFIKAT_FEHLER**: Das für die Verbindung verwendete Client-Zertifikat darf nicht für den gewählten Mandanten verwendet werden.
229 : **KASSENZEICHEN_NICHT_VORHANDEN**: Das gewählte Kassenzeichen ist nicht vorhanden.
230 : **KASSENZEICHEN_NICHT_GEFUNDEN**: Das gewählte Kassenzeichen konnte nicht gefunden werden.
231 : **INTERNER_EPAYMENT_FEHLER**: Interner nicht dokumentierter Fehler im ePayment-System.
232 : **UNDEFINIERT**: Ein im System nicht bekannter Status
233 ; **[%$TRIGGER.paymentStatusText%]**
234 : Eine Nachricht, die den zurückgelieferten Status näher beschreibt
235 ; **[%$TRIGGER.paypageUrl%]**
236 : URL zur Paypage mit der aktuellen Transaktionsnummer. Damit ist ein nochmaliges Aufrufen und Bezahlen der offenen Transaktion möglich.
237
238 == 3. Ergebnisanzeige ==
239
240 Die Anzeige des Ergebnisses bzw. des Status einer Bezahl-Transaktion erfolgt standardmäßig mittels einer extra Abschluss-Seite.
241 Dafür stellt das Plugin 3 HTML-Templates bereit:
242
243 * **AKDB ePayment Bezahlung Erfolg**: Standard-Template für Anzeige bei erfolgreich abgeschlossener Bezahlung.
244 * **AKDB 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.
245 * **AKDB ePayment Fehler**: Standard-Template für Anzeige bei allgemeinen technischen Fehlern. Der genaue Fehler wird mittels enthaltener Platzhalter ausgewiesen.
246
247 {{info}}
248 Die durch das Plugin bereitgestellten HTML-Templates können bearbeitet werden. Änderungen haben dabei auf alle Formulare mit Bezahl-Workflow Auswirkungen, wenn Sie diese Standard-Templates nutzen.
249 Möchte man in einem einzelnen Bezahl-Workflow ein eigenes Abschluss-Seiten Template verwenden, so kann man dies über eine Aktion //HTML-Abschlussseite// in der jeweiligen Verarbeitungskette realisieren.
250 {{/info}}
251
252 == Versionshistorie ==
253
254 (% class="wikigeneratedid" %)
255 === 3.2.0 ===
256
257 * Erweiterung EPayment Bestellartikel: Am Element ist der Gesamtpreis (Anzahl * Einzelpreis) als verstecktes Element verfügbar. Dieser kann über die CSS-Klasse 'CXOrderItemTotalPrice' eingeblendet werden.
258 * Erweiterung Anzahl-Eingabe-Element am EPayment Bestellartikel: Bei einer direkten Werteingabe wird diese sofort gegen die definierte untere und obere Wertgrenze validiert.
259
260 === 3.1.4 ===
261
262 * Formatierung des Rückgabewertes für den Gesamtbetrag auf #0,00 €
263
264 === 3.1.3 ===
265
266 * Fehlerbehebung: Es wurden Problem behoben, welche beim Öffnen von EPayment-Formularen im Designe aufgetreten sind.
267
268 === 3.1.2 ===
269
270 * Neuer Pluginparameter *epayment.webservice.timeout* zum Konfigurieren des Timeouts zum Webservice in Sekunden.
271
272 === 3.1.1 ===
273
274 * Fehlerbehebung: Bei EPayment-Artikel Objekt werden bei fehlenden Werten, Defaultwerte angenommen.
275
276 === 3.1.0 ===
277
278 * Neue Eigenschaften am EPayment-Artikel Objekte hinzugefügt:
279 ** Pflicht-Artikel: Ein Artikel kann als Pflicht definiert werden und wird dadurch automatisch der Bestellung hinzugefügt, egal ob dieser durch Manipulation vor dem Absenden aus der Bestellung entfernt wurde
280 ** Maximale Bestellmenge: Die durch den Nutzer maximal auswählbare Bestellmenge lässt sich begrenzen
281
282 === 3.0.1 ===
283
284 * Plugin benötigt mindestens {{formcycle/}} in der Version {{version major="7" minor="0" patch="1"}}{{/version}}
285 ** Anpassungen der Validierungen im Designer für EPayment-Artikel Objekte
286
287 === 3.0.0 ===
288
289 * Plugin benötigt mindestens {{formcycle/}} in der Version {{version major="7" minor="0" patch="0"}}{{/version}}
290 ** Neue Workflow-Aktion für Initialisierung der Bezahl-Transaktion
291 ** Einführung Ereignisse für Absenden der Bestellung, sowie Verifizierung der erfolgreichen / nicht erfolgreichen Bezahltransaktion