GiroSolution: ePayment-Plugin

author	version	line-number	content
1	{{content/}}
2
3	Das GiroSolution ePayment Plugin ermöglicht es, über die von GiroSolution bereitgestellte PayPage, einen Bezahlvorgang innerhalb eines Formularprozesses einzubauen.
4
5	{{info}}
6	Für die Nutzung des Plugins ist es im Vorfeld notwendig, dass ein Vertrag mit der Firma GiroSolution über zur Nutzung der Service-Schnittstelle abgeschlossen wird.
7	{{/info}}
8
9	== Aktions-Plugin //GiroSolution: Paypage: Initialisierung// ==
10
11	Mit der Einbindung des Aktions-Plugin //GiroSolution: Paypage: Initialisierung// ist es möglich ein Bezahl-Transaktion innerhalb der {{formcycle/}} Statusverarbeitung auszuführen. Nachfolgend werden die dafür notwendigen Konfigurations-Parameter näher beschrieben.
12
13	=== Transaktionsdaten ===
14
15	{{figure image="plugin_trans_data.png"}}
16	Konfiguration der Transaktionsdaten
17	{{/figure}}
18
19	; Automatisch zur Paypage witerleiten
20	: Diese Einstellung ist standardmäßig aktiviert. Dadurch wird nach dem Initialisieren der Bezahl-Transaktion automatisch auf die Payment-Page von //GiroSolution// weitergeleitet. Wenn dies nicht gewünscht ist, kann durch Deaktivierung dieser Einstellung eine Weiterleitung unterbunden werden.
21
22	{{info title="Hinweis:"}}
23	Wenn eine Transaktion auf Seiten von //GiroSolution// erfolgreich erzeugt wurde, wird die URL zur Paypage als Plugin-Rückgabe-Parameter zurückgeliefert. Diese kann dann zu einem späteren Zeitpunkt aufgerufen werden.
24	{{/info}}
25
26	; Betrag
27	: Hier ist der zu bezahlende Betrag in der kleinsten Währungseinheit (z.B.: Cent, Penny) anzugeben. Es werden Platzhalter unterstützt.
28
29	{{info title="Hinweis:"}}
30	Wenn die Werte direkt aus dem Formular kommen, beachten Sie, dass diese durch den Nutzer manipuliert sein könnten. Es empfiehlt sich deshalb an dieser Stelle mit festen Werten zur arbeiten oder die Zahlbeträge serverseitig zu berechnen.
31	{{/info}}
32
33	; Verwendungszweck
34	: Verwendungszweck der Transaktion, welcher später auf der Kartenabrechnung bzw. dem Kontoauszug erscheint. Es werden Platzhalter unterstützt. Maximal sind 20 (SEPA-konforme) Zeichen erlaubt:
35
36	* a b c d e f g h i j k l m n o p q r s t u v w x y z
37	* A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
38	* Zahlen von 0 – 9
39	* Sonderzeichen: ' : ? , - ( + . ) / \|
40
41	; Beschreibung für Bezahlung
42	: Definiert die Beschreibung zum Zahlbetrag, welcher auf der Bezahlseite von //GiroSolution// angezeigt wird. Es werden Platzhalter unterstützt. Maximal sind 60 Zeichen zulässig. Unterstützt werden Buchstaben aller Sprachen, also beispielsweise auch Umlaute und spanische Sonderzeichen usw., Satzzeichen, Ziffern und Symbole, die sich auf Währungen beziehen (also $ und € etc.).
43
44	=== Zielstatus ===
45
46	{{figure image="plugin_states.png"}}
47	Konfiguration des Zielstatus nach Rückkehr von der Bezahlseite in {{formcycle/}}
48	{{/figure}}
49
50	In diesem Bereich können Status festgelegt werden, in welchen der Vorgang versetzt wird, wenn {{formcycle/}} eine Rückmeldung von //GiroSolution// erhält:
51
52	; Zielstatus für Payment Server Rückmeldung
53	: Hier kann ein Status definiert werden, in dem gewechselt wird, wenn die Transaktions-Benachrichtigung bei einer Server-To-Server-Verbindung zurückgemeldet wird. In der jeweiligen Status-Verarbeitung stehen dann die unter //Notification-Parameter// aufgeführten Parameter zur Verfügung.
54	; Zielstatus für erfolgreiche Zahlung
55	: Hier kann ein Status festgelegt werden, in welchen gewechselt wird, wenn der Kunde die Zahlung erfolgreich abgeschlossen hat. In der jeweiligen Status-Verarbeitung stehen dann die unter //Notification-Parameter// aufgeführten Parameter zur Verfügung.
56	; Zielstatus für abgebrochenen Zahlvorgang
57	: Hier kann ein Status festgelegt werden, in welchen gewechselt wird, wenn der Kunde innerhalb der //GiroSolution// Bezahlseite auf "Zurück" klickt und damit den Bezahlvorgang abbricht.
58	; Zielstatus für erfolglose Zahlung
59	: Hier kann ein Status festgelegt werden, in welchen gewechselt wird, wenn der Bezahlvorgang erfolglos beendet wurde.
60
61	Nach dem Durchlaufen der jeweiligen Statusverarbeitung erfolgt standardmäßig eine Weiterleitung ins Formular.
62	Wenn in der Statusverarbeitung eine Aktion vom Typ "[[Abschlussseite (Template)>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.ResponsePage\|\|target="_blank"]]" definiert ist, erfolgt die Weiterleitung zu dieser Abschluss-Seite anstatt ins Formular.
63
64	=== Übersteuerung globaler Einstellungen ===
65
66	{{figure image="plugin_global_data.png"}}
67	Globale Einstellungen übersteuern
68	{{/figure}}
69
70	In diesem Bereich können die unter //[[Globale Einstellungen für Anbindung einer Paypage>>doc:\|\|anchor="global_config"]]// getroffenen Einstellungen übersteuert werden.
71
72	; Händler-ID
73	: Händler-ID aus einem //GiroSolution Payment Page// Projekt.
74	; Projekt-ID
75	: Projekt-ID aus einem //GiroSolution Payment Page// Projekt.
76	; Projekt-Passwort
77	: Projekt-Passwort aus einem //GiroSolution Payment Page// Projekt.
78	; Währung
79	: Währung mit der alle Payment Page Transaktionen ablaufen. Angabe muss im [[ISO 4217 Format>>https://de.wikipedia.org/wiki/ISO_4217\|\|rel="noopener noreferrer" target="_blank" title="ISO 4217"]] erfolgen.
80	; Sprache
81	: Sprache auf der Payment Page, mögliche Werte:
82
83	* de: Anzeige in deutscher Sprache
84	* en: Anzeige in englischer Sprache
85
86	; Anbietername
87	: Name des Anbieters auf der Bezahlseite. Wenn nichts festgelegt ist, wird der im //GiroSolution GiroCockpit// festgelegte Wert verwendet.
88	; Test-Modus?
89	: Legt fest, in welchem Modus die Zahlarten auf den Payment Page anzuzeigen sind. Wenn aktiviert ist der Test-Betrieb aktiv, sonst der Live-Betrieb.
90
91	=== Allgemeine Rückgabeparameter ===
92
93	{{figure image="plugin_result.png"}}
94	Allgemeine Rückgabeparameter
95	{{/figure}}
96
97	In diesem Bereich werden die vom Plugin als Ergebnis zurückgelieferten Parameter aufgeführt. Für die einzelnen Parameter kann ein Alias vergeben werden. In weiteren Aktionen kann auf den entsprechenden Rückgabeparameter per Platzhalter-Syntax zugegriffen werden. Der Platzhalter wird dabei nach dem folgenden Muster gebildet:
98
99	{{code}}
100
101	[%$<Plugin-Name>.RESULT[0].<Name oder vergebener Alias der Rückgabeparameters>%]
102	{{code}}
103
104	; ResultCode
105	: Enthält einen Zahlenwert, welcher den Abarbeitungs- bzw. Fehlerstatus des Plugins widergibt.
106	; ResultMessage
107	: Enthält eine Klartextmeldung, welche den zurückgelieferten //ResultCode// näher erläutert.
108	; ResultMerchantTxID
109	: Enthält die erzeugte Transaktions-ID enthält. Dieser Rückgabewert ist nur vorhanden, wenn auf Seiten von //GiroSolution// eine Transaktion erfolgreich erzeugt werden konnte.
110	; ResultPaypageUrl
111	: Enthält die Redirect-URL zur Payment-Page von GiroSolution. Dieser Rückgabewert ist nur vorhanden, wenn auf Seiten von //GiroSolution// eine Transaktion erfolgreich erzeugt werden konnte.
112	; ResultPaypageReferenceID
113	: Enthält die Referenznummer für die Payment Page. Dieser Rückgabewert ist nur vorhanden, wenn auf Seiten von //GiroSolution// eine Transaktion erfolgreich erzeugt werden konnte.
114
115	== Globale Plugin-Einstellungen ==
116
117	{{info}}
118	Dieser Abschnitt ist nur für {{formcycle/}}-Administratoren relevant, welche das Plugin-Bundle initial im System einrichten.
119	{{/info}}
120
121	=== Konfiguration der Plugin-Bundle Properties ===
122
123	Über die nachfolgend beschriebenen Einstellungen wird das Plugin an die durch GiroSolution zur Verfügung gestellte Schnittstelle angeschlossen.
124
125	{{id name="global_config"/}}
126
127	==== Globale Einstellungen für Anbindung einer Paypage ====
128
129	; payment.paypage.merchant.id (Pflicht)
130	: Händler-ID aus einem //GiroSolution Payment Page// Projekt.
131	; payment.paypage.project.id (Pflicht)
132	: Projekt-ID aus einem //GiroSolution Payment Page// Projekt.
133	; payment.paypage.project.pwd (Pflicht)
134	: Projekt-Passwort aus einem //GiroSolution Payment Page// Projekt.
135	; payment.paypage.testmode (Pflicht)
136	: Legt fest, in welchem Modus die Zahlarten auf den Payment Page anzuzeigen sind, mögliche Werte:
137
138	* true: Anzeige im Test-Betrieb
139	* false: Anzeige im Live-Betrieb
140
141	; payment.paypage.currency (Pflicht)
142	: Währung mit der alle Payment Page Transaktionen ablaufen. Angabe muss im ISO 4217 Format erfolgen.
143	; payment.paypage.locale (Pflicht)
144	: Sprache auf der Payment Page, mögliche Werte:
145
146	* de: Anzeige in deutscher Sprache
147	* en: Anzeige in englischer Sprache
148
149	; payment.paypage.organization
150	: Name des Anbieters der Payment Page. Wenn nichts festgelegt ist, wird der im //GiroSolution GiroCockpit// festgelegte Wert verwendet.
151	; payment.paypage.proxy.host
152	: Hostname eines Proxy-Servers, wenn die Kommunikation zwischen //GiroSolution// und {{formcycle/}} über einen Proxy-Server erfolgen soll
153	; payment.paypage.proxy.port
154	: Angabe eines Proxy-Server Ports, wenn die Kommunikation zwischen //GiroSolution// und {{formcycle/}} über einen Proxy-Server erfolgen soll.

Das GiroSolution ePayment Plugin ermöglicht es, über die von GiroSolution bereitgestellte PayPage, einen Bezahlvorgang innerhalb eines Formularprozesses einzubauen.

4

5

6

Für die Nutzung des Plugins ist es im Vorfeld notwendig, dass ein Vertrag mit der Firma GiroSolution über zur Nutzung der Service-Schnittstelle abgeschlossen wird.

7

8

9

== Aktions-Plugin //GiroSolution: Paypage: Initialisierung// ==

10

11

Mit der Einbindung des Aktions-Plugin //GiroSolution: Paypage: Initialisierung// ist es möglich ein Bezahl-Transaktion innerhalb der {{formcycle/}} Statusverarbeitung auszuführen. Nachfolgend werden die dafür notwendigen Konfigurations-Parameter näher beschrieben.

12

13

=== Transaktionsdaten ===

14

15

16

Konfiguration der Transaktionsdaten

17

18

19

; Automatisch zur Paypage witerleiten

20

: Diese Einstellung ist standardmäßig aktiviert. Dadurch wird nach dem Initialisieren der Bezahl-Transaktion automatisch auf die Payment-Page von //GiroSolution// weitergeleitet. Wenn dies nicht gewünscht ist, kann durch Deaktivierung dieser Einstellung eine Weiterleitung unterbunden werden.

21

22

23

Wenn eine Transaktion auf Seiten von //GiroSolution// erfolgreich erzeugt wurde, wird die URL zur Paypage als Plugin-Rückgabe-Parameter zurückgeliefert. Diese kann dann zu einem späteren Zeitpunkt aufgerufen werden.

; Betrag

: Hier ist der zu bezahlende Betrag in der kleinsten Währungseinheit (z.B.: Cent, Penny) anzugeben. Es werden Platzhalter unterstützt.

28

29

30

Wenn die Werte direkt aus dem Formular kommen, beachten Sie, dass diese durch den Nutzer manipuliert sein könnten. Es empfiehlt sich deshalb an dieser Stelle mit festen Werten zur arbeiten oder die Zahlbeträge serverseitig zu berechnen.

; Verwendungszweck

: Verwendungszweck der Transaktion, welcher später auf der Kartenabrechnung bzw. dem Kontoauszug erscheint. Es werden Platzhalter unterstützt. Maximal sind 20 (SEPA-konforme) Zeichen erlaubt:

35

36

* a b c d e f g h i j k l m n o p q r s t u v w x y z

37

* A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

38

* Zahlen von 0 – 9

39

* Sonderzeichen: ' : ? , - ( + . ) / |

40

41

; Beschreibung für Bezahlung

42

: Definiert die Beschreibung zum Zahlbetrag, welcher auf der Bezahlseite von //GiroSolution// angezeigt wird. Es werden Platzhalter unterstützt. Maximal sind 60 Zeichen zulässig. Unterstützt werden Buchstaben aller Sprachen, also beispielsweise auch Umlaute und spanische Sonderzeichen usw., Satzzeichen, Ziffern und Symbole, die sich auf Währungen beziehen (also $ und € etc.).

=== Zielstatus ===

Konfiguration des Zielstatus nach Rückkehr von der Bezahlseite in {{formcycle/}}

48

49

50

In diesem Bereich können Status festgelegt werden, in welchen der Vorgang versetzt wird, wenn {{formcycle/}} eine Rückmeldung von //GiroSolution// erhält:

51

52

; Zielstatus für Payment Server Rückmeldung

53

: Hier kann ein Status definiert werden, in dem gewechselt wird, wenn die Transaktions-Benachrichtigung bei einer Server-To-Server-Verbindung zurückgemeldet wird. In der jeweiligen Status-Verarbeitung stehen dann die unter //Notification-Parameter// aufgeführten Parameter zur Verfügung.

54

; Zielstatus für erfolgreiche Zahlung

55

: Hier kann ein Status festgelegt werden, in welchen gewechselt wird, wenn der Kunde die Zahlung erfolgreich abgeschlossen hat. In der jeweiligen Status-Verarbeitung stehen dann die unter //Notification-Parameter// aufgeführten Parameter zur Verfügung.

56

; Zielstatus für abgebrochenen Zahlvorgang

57

: Hier kann ein Status festgelegt werden, in welchen gewechselt wird, wenn der Kunde innerhalb der //GiroSolution// Bezahlseite auf "Zurück" klickt und damit den Bezahlvorgang abbricht.

58

; Zielstatus für erfolglose Zahlung

59

: Hier kann ein Status festgelegt werden, in welchen gewechselt wird, wenn der Bezahlvorgang erfolglos beendet wurde.

60

61

Nach dem Durchlaufen der jeweiligen Statusverarbeitung erfolgt standardmäßig eine Weiterleitung ins Formular.

62

Wenn in der Statusverarbeitung eine Aktion vom Typ "[[Abschlussseite (Template)>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.ResponsePage||target="_blank"]]" definiert ist, erfolgt die Weiterleitung zu dieser Abschluss-Seite anstatt ins Formular.

63

64

=== Übersteuerung globaler Einstellungen ===

65

66

67

Globale Einstellungen übersteuern

68

69

70

In diesem Bereich können die unter //[[Globale Einstellungen für Anbindung einer Paypage>>doc:||anchor="global_config"]]// getroffenen Einstellungen übersteuert werden.

71

72

; Händler-ID

73

: Händler-ID aus einem //GiroSolution Payment Page// Projekt.

74

; Projekt-ID

75

: Projekt-ID aus einem //GiroSolution Payment Page// Projekt.

76

; Projekt-Passwort

77

: Projekt-Passwort aus einem //GiroSolution Payment Page// Projekt.

78

; Währung

79

: Währung mit der alle Payment Page Transaktionen ablaufen. Angabe muss im [[ISO 4217 Format>>https://de.wikipedia.org/wiki/ISO_4217||rel="noopener noreferrer" target="_blank" title="ISO 4217"]] erfolgen.

80

; Sprache

81

: Sprache auf der Payment Page, mögliche Werte:

82

83

* **de**: Anzeige in deutscher Sprache

84

* **en**: Anzeige in englischer Sprache

85

86

; Anbietername

87

: Name des Anbieters auf der Bezahlseite. Wenn nichts festgelegt ist, wird der im //GiroSolution GiroCockpit// festgelegte Wert verwendet.

88

; Test-Modus?

89

: Legt fest, in welchem Modus die Zahlarten auf den Payment Page anzuzeigen sind. Wenn aktiviert ist der **Test-Betrieb** aktiv, sonst der **Live-Betrieb**.

90

91

=== Allgemeine Rückgabeparameter ===

92

93

94

Allgemeine Rückgabeparameter

95

96

97

In diesem Bereich werden die vom Plugin als Ergebnis zurückgelieferten Parameter aufgeführt. Für die einzelnen Parameter kann ein Alias vergeben werden. In weiteren Aktionen kann auf den entsprechenden Rückgabeparameter per Platzhalter-Syntax zugegriffen werden. Der Platzhalter wird dabei nach dem folgenden Muster gebildet:

[%$<Plugin-Name>.RESULT[0].<Name oder vergebener Alias der Rückgabeparameters>%]

; ResultCode

: Enthält einen Zahlenwert, welcher den Abarbeitungs- bzw. Fehlerstatus des Plugins widergibt.

106

; ResultMessage

107

: Enthält eine Klartextmeldung, welche den zurückgelieferten //ResultCode// näher erläutert.

108

; ResultMerchantTxID

109

: Enthält die erzeugte Transaktions-ID enthält. Dieser Rückgabewert ist nur vorhanden, wenn auf Seiten von //GiroSolution// eine Transaktion erfolgreich erzeugt werden konnte.

110

; ResultPaypageUrl

111

: Enthält die Redirect-URL zur Payment-Page von GiroSolution. Dieser Rückgabewert ist nur vorhanden, wenn auf Seiten von //GiroSolution// eine Transaktion erfolgreich erzeugt werden konnte.

112

; ResultPaypageReferenceID

113

: Enthält die Referenznummer für die Payment Page. Dieser Rückgabewert ist nur vorhanden, wenn auf Seiten von //GiroSolution// eine Transaktion erfolgreich erzeugt werden konnte.

114

115

== Globale Plugin-Einstellungen ==

116

117

118

Dieser Abschnitt ist nur für {{formcycle/}}-Administratoren relevant, welche das Plugin-Bundle initial im System einrichten.

119

120

121

=== Konfiguration der Plugin-Bundle Properties ===

122