XBezahldienste Verwendung

Geändert am Mo, 11 Mai um 3:32 NACHMITTAGS

Optionale ergänzende Erläuterungen zum Status. Diese Informationen werden Teil des Antrags und bieten dem Bezahldienst die Möglichkeit Informationen an das Fachverfahren / Sachbearbeitung zu schicken. Grundsätzlich ist dieses Feld nicht notwendig - Inhalte sind zwischen Bezahldienst und Fachverfahren abzustimmen.

Inhalt

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

Das kostenpflichtige XBezahldienste: ePayment Plugin ermöglicht es, 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.

Bestellung konfigurieren

Die Workflow-Aktion ist für das Erzeugen einer Bezahl-Transaktion zuständig. Hier werden alle notwendigen Daten, welche im Zusammenhang mit der Transaktion stehen und relevant für die Zuordnung sind, angegeben.

Verbindung
Eine Verbindung ist auszuwählen, welche in der entsprechenden Verwaltungsoberfläche XBezahldienste angelegt wurde.
APP-Kennung
Die APP-Kennung enthält Informationen zum auslösenden Online-Dienst, wie den fachlichen Kontext. Die technische Bezeichnung ist 'originatorId', maximal 36 Zeichen lang.

Mit einer korrekt eingerichteten und ausgewählten Verbindung sowie angegebener APP-Kennung kann ein Verbindungstest durchgeführt werden.

Verwendungszweck
Verwendungszweck bzw. Buchungstext der Transaktion.
Beschreibung
Die Beschreibung der Transaktion. Kann auf der Paypage bzw. PSP Seite angezeigt werden.
Anzahl
Die Anzahl dieser Bestellposition.
Netto-Preis (in €)
Nettobetrag dieser Bestellposition. Es ist eine Trennung von Euro und Cent mit Komma oder Punkt erlaubt.
Steuersatz (in %)
Steuersatz als Prozentbetrag.
Referenz
Eine fachliche Referenz auf den "Artikel" bzw. den Inhalt der Position.
Beschreibung
Die Beschreibung der Bestellposition. Kann auf der Paypage bzw. PSP Seite angezeigt werden.
Buchungsdaten
Jeder Eintrag besteht aus einer Kombination aus Schlüssel und Wert. Es können mehrere Buchungsdaten pro Bestellposition angegeben werden. Hilft der Zuordnung im Buchungssystem.

Es muss mindestens eine Bestellposition angegeben werden.

Angaben zum Antragsteller übermitteln
Mit dem Anhaken dieser Checkbox, werden Angaben zum Antragsteller übermittelt sowie validiert ob notwendige Angaben getätigt wurden.
Vorname
Der übermittelte Wert darf maximal 250 Zeichen lang sein.
Familienname
Der übermittelte Wert darf maximal 250 Zeichen lang sein.
Geschlecht
Erlaubte Werte: M=Männlich, F=Weiblich, D=Divers.
Antragsteller ist ein Organisation
Mit dem Anhaken dieser Checkbox, wird das technische Feld "isOrganization" als "true" übertragen sowie die Angabe eines Namens eingeblendet.
Name der Organisation
Der übermittelte Wert darf maximal 250 Zeichen lang sein.
Adresse des Antragstellers übermitteln
Mit dem Anhaken dieser Checkbox, werden etwaige Informationen zur Adresse übermittelt.
Straße
Der übermittelte Wert darf maximal 250 Zeichen lang sein.
Hausnummer
Der übermittelte Wert darf maximal 20 Zeichen lang sein.
Adresszusatz
Zum Abbilden von Internationalen Adressen werden generische "Adresszeilen" verwendet und nicht "Straße / Hausnummer". Es sind bis zu 9 Einträge im Array erlaubt. Bsp: ["Dienstsitz Berlin","Postanschrift: 11016 Berlin"].
Postleitzahl
Der übermittelte Wert muss genau 5 Zeichen lang sein.
Ort
Der übermittelte Wert darf maximal 250 Zeichen lang sein.
Land
ISO 3166-1, Alpha-2 code, zwei Großbuchstaben, z.B. DE für Deutschland.

Rückgabewerte der Workflow-Aktion

[%$Bestellung konfigurieren.RESULT.paymentInformation.paymentMethod%]
Die vom Benutzer ausgewählte Zahlart. Das Feld ist nur bei einer erfolgreichen Zahlung vorhanden / befüllt.
[%$Bestellung konfigurieren.RESULT.paymentInformation.paymentMethodDetail%]Weitere Erläuterung zur gewählten Zahlart.
[%$Bestellung konfigurieren.RESULT.paymentInformation.status%]Der Status der Transaktion soll dem EfA-Onlinedienst erkennbar machen, ob die Bezahlung erfolgreich durchgeführt wurde.
[%$Bestellung konfigurieren.RESULT.paymentInformation.statusDetail%]Optionale ergänzende Erläuterungen zum Status. Diese Informationen werden Teil des Antrags und bieten dem Bezahldienst die Möglichkeit Informationen an das Fachverfahren / Sachbearbeitung zu schicken. Grundsätzlich ist dieses Feld nicht notwendig - Inhalte sind zwischen Bezahldienst und Fachverfahren abzustimmen.
[%$Bestellung konfigurieren.RESULT.paymentInformation.transactionId%]Eine vom Bezahldienst vergebene Transaktions-ID beim POST des Requests. Diese ID wird für die späteren Abfragen (GET) verwendet. Dies kann schon das Kassenzeichen sein. Sofern dies später vergeben wird, kann hier eine 'technische' ID des Bezahldienstes vergeben werden. Falls der Bezahldienst keine eigenen IDs hier verwendet, kann die Schnittstelle auch die Request-ID zurück geben.
[%$Bestellung konfigurieren.RESULT.paymentInformation.transactionRedirectUrl%]Die Redirect-URL an die der Online-Dienst den Benutzer weiterleiten soll. Diese URL öffnet die "Paypage" / "Bezahlseite" des Bezahldienstes. Diese URL muss nur im Status "INITIAL" (also bei der Post-Response oder Statusabfrage vor Abschluss / Abbruch der Transaktion) enthalten sein. Nach Abschluss der Transaktion sollte diese URL nicht enthalten sein.
[%$Bestellung konfigurieren.RESULT.paymentInformation.transactionReference%]Das "fachliche" Kennzeichen für eine Bezahlung. Dieses kann bei dem POST des Requests vom Bezahldienst vergeben werden oder erst nach der Autorisierung durch den Bezahler. Daher ist die relevante ID für diese Schnittstelle die transactionId, die durch den Bezahldienst bei der Anlage des Payment-Requests vergeben wird.
[%$Bestellung konfigurieren.RESULT.paymentInformation.transactionTimestamp%]Zeitstempel der erfolgreichen Durchführung der Bezahlung.
[%$Bestellung konfigurieren.RESULT.paymentInformation.transactionUrl%]Die Rest-URL der Payment Transaction für die Statusabfrage. Diese Information könnte aus den Informationen generiert werden. Eine explizite Ablage der URL dient der Robustheit der Schnittstelle.
[%$Bestellung konfigurieren.RESULT.paymentRequest.description%]Die Beschreibung des Payment Requests. Kann auf der Paypage / PSP Seite angezeigt werden.
[%$Bestellung konfigurieren.RESULT.paymentRequest.grosAmount%]Der Gesamtbetrag dient dem Bezahldienst zur Validierung der einzelnen Positionen.
[%$Bestellung konfigurieren.RESULT.paymentRequest.purpose%]Verwendungszweck / Buchungstext der Payment Transaction.
[%$Bestellung konfigurieren.RESULT.paymentRequest.redirectUrl%]Rücksprung-URL vom Bezahldienst zum Online-Dienst. Der Status (Erfolg / Abbruch) muss über die Statusabfrage (GET) abgefragt werden.
[%$Bestellung konfigurieren.RESULT.paymentRequest.requestId%]Die Request-ID wird vom Online-Dienst vergeben und vom Bezahldienst abgelegt.
[%$Bestellung konfigurieren.RESULT.paymentRequest.requestTimestamp%]Zeitstempel des Online-Antrags / Payment-Requests.

Fehlerwerte der Workflow-Aktion

PAYMENT_REQUEST_BUILD

Für die Übertragung des Preises wird von der pmPayment REST API ein Integer erwartet. Falls die Angabe an der Workflow-Aktion nicht erfolgreich in einen Integer umgewandelt werden kann, wird dieser Fehlercode ausgegeben.

INVALID_STATUS

Der aktuelle Status der Transaktion erlaubt die angeforderte Operation nicht. Entweder ist die Transaktion bereits bezahlt, fehlgeschlagen oder abgebrochen.

API

Ein Fehler ist direkt beim Bezahldienst aufgetreten. Die Rückmeldung des Bezahldienst wird im Protokoll festgehalten.

GENERAL

Ein unbekannter Fehler ist aufgetreten.

NO_CONNECTION

Es wurde keine Verbindung gefunden, möglicherweise wurde diese in der Zwischenzeit gelöscht.

Bestellung abgeschlossen

Das Workflow-Ereignis erlaubt formcycle eine Rückmeldung des entsprechenden angebundenen XBezahldienste System zu verarbeiten. Entscheidend dafür ist der Status der Transaktion, welcher Bestandteil der Rückgabewerte ist.

Die Status:INITIAL der Antrag hat einen 
Payment-Request ausgelöst und eine Payment-Transaction wurde angelegt. 
Der Nutzer hat aber im Bezahldienst noch keine Wirkung erzeugt. Der 
Benutzer kann mit dem Link zum Bezahldienst weitergeleitet werden. NEUE /
 Eränzende Info: Solange der Benutzer eine bestimmte Zahlart ausgewählt 
und abgebrochen hat - aber noch die Option hat, stattdessen eine andere 
Zahlart zu verwenden, so bleibt der Status auf INITIAL
PAYED der Nutzer hat die Bezahlung im Bezahldienst erfolgreich durchgeführt.
FAILED der Vorgang wurde vom Bezahldienst aufgrund der Nutzereingaben final abgebrochen.
CANCELED der Nutzer hat die Bezahlung im Bezahldienst final abgebrochen.

Rückgabewerte des Workflow-Ereignis

[%$TRIGGER.paymentMethod%]
Die vom Benutzer ausgewählte Zahlart. Das Feld ist nur bei einer erfolgreichen Zahlung vorhanden / befüllt.
[%$TRIGGER.paymentMethodDetail%]
Weitere Erläuterung zur gewählten Zahlart.
[%$TRIGGER.status%]
Der Status der Transaktion soll dem EfA-Onlinedienst erkennbar machen, ob die Bezahlung erfolgreich durchgeführt wurde.
[%$TRIGGER.statusDetail%]
Optionale ergänzende Erläuterungen zum Status. Diese Informationen werden Teil des Antrags und bieten dem Bezahldienst die Möglichkeit Informationen an das Fachverfahren / Sachbearbeitung zu schicken. Grundsätzlich ist dieses Feld nicht notwendig - Inhalte sind zwischen Bezahldienst und Fachverfahren abzustimmen.
[%$TRIGGER.transactionId%]
Eine vom Bezahldienst vergebene Transaktions-ID beim POST des Requests. Diese ID wird für die späteren Abfragen (GET) verwendet. Dies kann schon das Kassenzeichen sein. Sofern dies später vergeben wird, kann hier eine 'technische' ID des Bezahldienstes vergeben werden. Falls der Bezahldienst keine eigenen IDs hier verwendet, kann die Schnittstelle auch die Request-ID zurück geben.
[%$TRIGGER.transactionRedirectUrl%]
Die Redirect-URL an die der Online-Dienst den Benutzer weiterleiten soll. Diese URL öffnet die "Paypage" / "Bezahlseite" des Bezahldienstes. Diese URL muss nur im Status "INITIAL" (also bei der Post-Response oder Statusabfrage vor Abschluss / Abbruch der Transaktion) enthalten sein. Nach Abschluss der Transaktion sollte diese URL nicht enthalten sein.
[%$TRIGGER.transactionReference%]
Das "fachliche" Kennzeichen für eine Bezahlung. Dieses kann bei dem POST des Requests vom Bezahldienst vergeben werden oder erst nach der Autorisierung durch den Bezahler. Daher ist die relevante ID für diese Schnittstelle die transactionId, die durch den Bezahldienst bei der Anlage des Payment-Requests vergeben wird.
[%$TRIGGER.transactionTimestamp%]
Zeitstempel der erfolgreichen Durchführung der Bezahlung.
[%$TRIGGER.transactionUrl%]
Die Rest-URL der Payment Transaction für die Statusabfrage. Diese Information könnte aus den Informationen generiert werden. Eine explizite Ablage der URL dient der Robustheit der Schnittstelle.