1. Einführung

Die E-Payment Middleware ist ein Webservice der Zahlungsdienstleister, wie z.B. ePayBL oder GiroCheckout an das Bibliotheksmanagementsystem Alma anbindet. Dadurch wird es Kunden der Bibliothek ermöglicht, Bibliotheksgebühren in Echtzeit zu bezahlen und in Alma buchen zu lassen.

Tipp: Es besteht die Möglichkeit in der Middleware für eine Bibliothek mehrere Konfigurationen parallel anzulegen. Damit kann z.B. eine Konfiguration für den Katalog Primo und eine weitere zur Anbindung einer Campus-App parallel verwendet werden. 

Die Testumgebung ist aktuell verfügbar unter  https://libpay.hbz-nrw.de/

2. Technischer Ablauf eines Bezahlvorgangs

2.1. Start eines Zahlvorgangs

Ein Kunde startet einen Zahlungsvorgang z.B. aus seinem Benutzerkonto über den Bezahllink (mehr dazu weiter unten) per GET-Request auf den Pfad /initiate_payment/v1 der jeweiligen Middleware-Instanz .

Beispiel:

https://libpay.hbz-nrw.de/initiate_payment/v1?apikey=Rj7SqDo...YSbOXXY&jwt=eEuVySIsImF1dGhlbnRp...TZXTdYtqzqE_g

Dabei werden folgende Parameter übergeben:

Name Inhalt
apikey In der Middleware für das jeweilige Frontend (z. B. Discovery-System) hinterlegte Zeichenkette für die Zuordnung zur passenden Bibliothek
jwt

Signiertes JSON Web Token (JWS, nicht JWE) mit den Daten zum jeweils einzuleitenden Zahlungsvorgang.

Die Verwendung eines durch eine kryptographische Signatur abgesicherten JWT stellt die Integrität der übermittelten Daten sicher und dient der Authentifizierung der aufrufenden Stelle, da nur diese den geheimen Schlüssel kennt, der in die Signatur bzw. Hash-Summe des JWT einfließt. 

Es werden zwei verschiedene Datenstrukturen des JWT für unterschiedliche Anwendungskontexte unterstützt (vgl. folgende Abschnitte).

2.1.1. Für Bibliotheken mit einem auf Introx basierenden Katalog oder zur Anbindung eigener Portale oder Apps

Als Hash-Algorithmus wird HS256 verwendet. Zur Berechnung der Signatur wird eine Zeichenkette benötigt, die sowohl dem aufrufenden System als auch der Middleware bekannt sein muss (darüber hinaus aber geheim zu halten ist). Diese wird bei der Einrichtung des Standorts von der Middleware erzeugt und der Bibliothek mitgeteilt.

2.1.1.1. Datenfelder

Name Inhalt Beschreibung
institution Zeichenkette Alma Institutions-Kennung, z. B.  49HBZ_XYZ
language de | en Gewünschte voreinzustellende Sprache für die Bezahlseite und ggf. zu verwendende Meldungen
user Zeichenkette Benutzer-ID aus dem Bibliothekssystem; aktuell i. d. R. Alma primary_id - bei Vertretungszugriff (Proxy) natürlich die ID der Schuldnerin / des Schuldners, NICHT die ID des Proxy-Kontos!
return_url URL Die Rückkehr-URL, zu der die Middleware die Kunden nach Abschluß des Zahlungsvorgangs (erfolgreiche Zahlung oder Abbruch) per Redirect weiterleitet.
I. d. R. eine HTTPS-URL; bei Aufrufen aus Smartphone-App o. ä. aber auch mit anderen Protokoll-Angaben (fiktives Beispiel: campusapp://bibliothek/konto )
custom_data Datenstruktur

In diesem Feld können optional Daten in Unterfeldern übermittelt werden, die für den weiteren Zahlungsworkflow benötigt werden, aber nicht in Alma verfügbar sind.

Anwendungsfall Unterfeld Inhalt / Unter-Unterfelder
Übergabe von Adressdaten für die Nutzung von Apple Pay bzw. Google Pay via GiroCheckout billingAddress Laut Dokumentation von GiroCheckout ist es für die Nutzung der Zahlungsmethoden "Apple Pay" und "Google Pay" erforderlich, bereits bei der Initialisierung eines Zahlungsvorgangs bestimmte Daten zur Rechnungsadresse der zahlenden Person zu übermitteln. Sofern die Middleware erkennt, daß eine dieser Zahlungsmethoden auf der Bezahlseite angeboten werden wird, übergibt sie die minimal notwendigen Felder (und auch nur diese) an die GiroCheckout-API.
Wenn klar ist, daß die benötigten Angaben nicht aus dem Alma-Konto entnommen werden können, muss die aufrufende Stelle diese Angabe über das JWT mitliefern.
Mitgelieferte Daten, die mangels aktiver Zahlungsmethoden nicht benötigt werden, werden auch nicht an GiroCheckout weitergegeben.
Name Type Beschreibung
address_line_1 String(60) Hauptstraße und Hausnummer der Rechnungsadresse. Erlaubt sind mindestens zwei Zeichen bestehend aus Buchstaben (aller Sprachen), Ziffern, Leerzeichen, dem normalen Bindestrich, Apostroph- und Akzentzeichen, Anführungszeichen, Komma, Punkt, Doppel- und Semikolon, Nummernzeichen (#), kaufmännischem Und (&), Schrägstrich (/), Klammern, Plus- und At-Zeichen, sowie den Symbolen °, º, ᵃ, ª und Unterstrich.
postal_code String(10) Postleitzahl der Rechnungsadresse. Erlaubt sind Postleitzahlen mit 2–10 Zeichen, die mit einem Buchstaben oder einer Ziffer beginnen und enden und dazwischen nur Buchstaben, Ziffern, Leerzeichen, Bindestriche, Punkte oder Schrägstriche enthalten dürfen.
city String(50) Stadt der Rechnungsadresse. Selbe Formatvorgaben wie bei den Straßenfeldern.
country String(2) Zweibuchstabiger Ländercode der Rechnungsadresse (ISO 3166).


2.1.2. Für Bibliotheken mit dem Katalog Primo

Dieser JWT verwendet ein Public-Key-Verfahren von Exlibris. Dieses Verfahren ist nur für Bibliotheken mit dem Katalog Primo gedacht und kann nicht für eigene Anbindungen verwendet werden. Bitte verwenden Sie für eigene Anbindungen die Variante 1. Falls sie Primo und eine eigene Anwendung parallel verwenden wollen, können mehrere Konfigurationen angelegt werden.

In Alma kann ein Payment-Link konfiguriert werden (siehe unten), der im Onlinekatalog Primo im Benutzerkonto automatisch einen Bezahllink erzeugt. Der Inhalt des Tokens ist in der Primo-Dokumentation beschrieben.

Erwähnenswert ist hier der Umstand, dass dieser JWT keine return_url beinhaltet. Beim Start eines Zahlungsvorgangs versucht deswegen die Middleware die aufrufende Webseite (also normalerweise das Benutzerkonto) per request.referer zu ermitteln, um am Ende der Zahlung (oder dessen Abbruch) dorthin zurück zu leiten.

2.2. Abruf der Gebühren

Die Middleware ruft die offenen Gebühren des Kunden aus Alma ab und legt beim Zahlungsdienstleister eine Buchung an. Anschließend wird der Kunde per Redirect auf die Zahlseite weitergeleitet.

Einige Zahlungsverkehrsdienstleister erfordern die Übermittlung bestimmter Informationen durch den "Händler" oder Shop - in diesem Fall durch die Middleware in Vertretung der Bibliothek - bereits bei der Initialisierung eines Zahlungsvorgangs; d. h. eine spätere Eingabe auf der Bezahlseite durch die Nutzer:innen selbst ist für diese Angaben nicht ausreichend. Beispielsweise erfordern ApplePay und GooglePay zwingend die Angabe einer Rechnungsadresse.

Diese Angaben kann die Middleware ausschließlich aus Alma beziehen ("preferred address"). Liegen die benötigten Informationen nicht vollständig in Alma vor (ist z. B. keine Länderzuordnung vorhanden), kann der betreffende Zahlungsverkehrsdienstleister nicht genutzt werden!

Abhängig von den gewünschten Zahlungsverkehrsdienstleistern müssen daher die benötigten Informationen ggf. in den Alma Nutzerkonten nachgetragen werden; ggf. ist also auch eine Anpassung der aus dem IdM der jeweiligen Hochschule an Alma zu übertragenden Daten notwendig!

2.3. Gebührenbezahlung

Der Kunde bezahlt die offenen Gebühren über den Zahlungsdienstleister oder bricht den Vorgang ab.

2.4. Ergebnis der Gebührenbezahlung

Der Zahlungsdienstleister informiert über einen internen Link die Middleware über den Ausgang der Zahlung (Erfolg oder Abbruch) und leitet den Kunden per Redirect zurück zur Middleware.

2.5. Mitteilen des Ergebnisses

2.5.1. Rückkehr der Nutzer:innen ins Ausgangssystem

Nach Abschluss eines Zahlungsvorgangs - egal ob Erfolg oder Abbruch - sowie in Fällen, in denen die Middleware einen Fehler feststellt, sollen die Kunden zum Ausgangsort bzw. zur angegebenen return_url zurückgeführt werden.

Es ist nicht garantiert, dass diese Rückkehr tatsächlich stattfindet!
Ebenso ist nicht garantiert, dass im Moment der Rückkehr die Middleware oder Alma bereits den finalen Stand des Bezahlvorgangs kennt!
Vgl. dazu den unten folgenden Abschnitt "Information der Middleware und darüber von Alma".

Der Aufruf der return_url erfolgt per GET-Request. Dem Aufruf wird durch die Middleware ein JSON Web Token als Parameter jwt beigefügt.
Er enthält die folgenden Datenfelder:

Name Inhalt Beschreibung
action success | cancel | failed Statuscode 
amount Dezimal-Zahl Die Summe der im Zahlungsvorgang bezahlten Gebühren, ohne Währungseinheit. Beispiel: 5.12 oder 1123.45
code Dreistellige Zahl Numerische Repräsentation des Status
message Zeichenkette

Hinweis für Nutzerinnen, z. B. "Die Zahlung über 5.25€ war erfolgreich"; 

Die Texte können nicht konfiguriert werden; die Erzeugung und Ausgabe individueller Meldungstexte ist Aufgabe des jeweiligen Discovery-Systems o.ä.!

Aktuell können folgende Status-Varianten vorkommen:

action code message Erläuterung

success

200

Die Zahlung über {amount} war
erfolgreich

  
cancel

303

Die Zahlung wurde abgebrochen!

 

failed

500

Für diesen Betrag steht kein
unterstütztes Zahlverfahren
zur Verfügung.

In der ePayBL Konfiguration können Institutionen für jedes Zahlverfahren einen Minimal- und/oder einen Maximal-Betrag festlegen. Es kann daher vorkommen, daß die Middleware bei der Initialisierung eines Bezahlvorgangs von ePayBL die Rückmeldung erhält, daß für den angegebenen Betrag überhaupt kein Zahlverfahren genutzt werden kann. In diesem Fall werden die Benutzer:innen erst gar nicht zur Bezahlseite weitergeleitet, sondern die Middleware leitet direkt zurück zum aufrufenden System, welches dann die Verantwortung dafür trägt, einen entsprechenden Hinweis anzuzeigen.

failed

501

Die Zahlung wurde vom
Zahlungsdienstleister abgebrochen!

 Dieser Code signalisiert, dass während der Interaktion der Benutzer:innen mit dem Zahlungsdienstleister (PayPal etc.) ein Problem aufgetreten und der Vorgang deswegen fehlgeschlagen ist.

failed

502

Sie haben keine offene Gebühren!

Primo bietet den Bezahllink auch an, wenn keine offene Gebühren vorhanden sind.

failed

503

Für die gewählte Zahlungsart ist eine
vollständige Rechnungsadresse erforderlich.
Bitte hinterlegen/aktualisieren Sie Ihre Adresse in Alma.

Dieser Meldungstext wird mit dem nächsten Update der Middleware neutraler formuliert

Sind als Zahlungsdienste ApplePay oder GooglePay konfiguriert, werden vom Kunden aus Alma die Felder Adresse, PLZ, Stadt und Land geladen. Sind diese nicht gefüllt, erscheint diese Fehlermeldung.



Hinweise:

  • Ist das Land nicht gesetzt, wird von der Middleware automatisch "Deutschland" vorbelegt.
  • Gibt es mehrere Adressen wird die bevorzugte Adresse verwendet.

Für weitere Fehlertypen wird der code jeweils um 1 inkrementiert (501, 502, ...).

Die Kodierung des Tokens erfolgt - analog zum Start einer Zahlung - auf zwei Arten.

2.5.2. E-Mail-Benachrichtigung der Nutzer:innen durch Alma

Ist in Alma eine Zahlungsbestätigung per E-Mail konfiguriert, wird diese im Moment der Verbuchung der Zahlung an den Kunden geschickt!

2.5.3. Information der Middleware und darüber von Alma

Der finale Status des Zahlungsvorgangs wird außerdem über den direkten Aufruf einer API-Funktion der Middleware seitens des PSP im Hintergrund übermittelt. Diese Entkopplung von den Aktionen der Nutzer:innen ist wichtig, weil dies zum einen Manipulationen an den übermittelten Information verhindert und zum anderen die Zuverlässigkeit erhöht, weil z. B. die Übermittlung nicht durch ein Schließen des Browsers durch die Nutzer:innen verhindert werden kann.

Scheitert die Übermittlung dennoch zunächst - z. B. weil die Middleware aufgrund von Systemarbeiten vorübergehend für den PSP nicht erreichbar ist - erfolgen weitere Übermittlungsversuche durch den PSP über einen gewissen Zeitraum hinweg.

Ebenso ist vorstellbar, dass die Alma API aufgrund von Systemarbeiten die Aufrufe der Middleware zur Verbuchung der Zahlung im Nutzer:innen-Konto temporär nicht annehmen kann. In diesem Fall erfolgen weitere Aufrufversuche durch die Middleware.

2.6. Abgleich der gezahlten Gebühren zwischen Alma und GiroCockpit

Es besteht die Möglichkeit, die in GiroCockpit protokollierten Zahlungen mit den in Alma gebuchten Zahlungen abzugleichen. Dazu wird die von GiroCockpit eindeutig vergebene GiroCheckout Referenz bei den Zahlungen in Alma in der Spalte Vorgangs-ID angezeigt. Folgendes Beispiel dient zur Veranschaulichung:

In Girocockpit wurde die Buchung c37b5946-c062-4b6b-ba1b-c43beb2b9173 über 2€ durchgeführt:



Diese Buchung besteht in Alma aus zwei Position zu jeweils einem Euro, die im Benutzerkonto bei den Status: Geschlossen stehen. Dort können weitere Informationen angezeigt werden, wenn auf die offene Gebühren geklickt wird:



Es öffnet sich diese Detailansicht: 


  • Die Spalte Vorgangs-ID  beinhaltet die GiroCheckout Referenz.
  • Die Spalte Referenz wird von Alma befüllt und beinhaltet eine eindeutige Nummer zu allen Posten einer gemeinsamen Zahlung. In diesem Beispiel ist sie somit für die beiden Gebühren über jeweils einen Euro identisch.
  • Die Spalte Anmerkung beinhaltet eine Transaktionsnummer von der Middleware LibPay.
  • Die Zahlungsmethode Online weißt daraufhin, dass ein Onlinebezahlverfahren verwendet wurde.

Mit diesem Wissen sollte es leicht möglich sein, in Analytics z.B. einen monatlichen Report zu generieren, welcher mit einem Export aus GiroCockpit abgeglichen werden kann.

Wie im GiroCockpit zu sehen, wird als Verwendungszweck der Zahlung jeweils "Bibliotheksgebühren" angegeben.
Anders als in den Screenshots zu sehen, erhält die Zahlungs-Referenz ("Verkäufer Tx-ID" bei GiroCockpit) künftig noch das Präfix "BIB-" um leichter gefiltert werden zu können.

2.6.1. Für Bibliotheken mit dem Katalog Introx oder zur Anbindung eigener Portale oder Apps

Die Kodierung und Dekodierung erfolgt über die gemeinsame (geheime) Zeichenkette. Die Dekodierung erfolgt serverseitig.
Hinweis: Ob das für eine App auch so sinnvoll ist, muss noch evaluiert werden. Vielleicht möchte man nicht die geheime Zeichenkette in der App hinterlegen?

2.6.2. Für Bibliotheken mit dem Katalog Primo

Im Gegensatz zur vorstehenden Variante muss in Primo der JWT im Browser per Javascript dekodiert werden, da es keine Möglichkeit gibt, serverseitige Scripte auszuführen. Von daher kann keine geheime Zeichenkette verwendet werden, da diese im Javascript zu hinterlegen wäre und somit öffentlich werden würde. Stattdessen wird der JWT per Public-Key Verfahren erstellt. Das Javascript ruft dann zunächst den passenden Public-Key ab und dekodiert damit den JWT. 

3. Einrichtung der Middleware durch die teilnehmende Bibliothek

3.1. Konfiguration von Alma

  1. Erstellen Sie in der API-Konsole einen Key mit Lese- und Schreibberechtigung auf den API-Bereich "Users" (vgl. in der Dokumentation den Abschnitt Users and Fulfillment).
  2. Notieren Sie sich den Institution-Code aus Alma. Dieser steht in der Administration unter Konfiguration → Allgemein → Eine Bibliothek hinzufügen oder Bibliotheksinformationen bearbeiten Beispiel: 49HBZ_ZBS ist der Code der Deutschen Sporthochschule Köln.
  3. Übermitteln Sie dem hbz den API-Key und den Institution-Code.

3.2. Konfiguration eines Zahlungsdienstleisters durch die teilnehmende Bibliothek

3.2.1. Anbindung an Payone / S-Public Services

Zur Nutzung der Middleware ist zwingend ein Projekt vom Typ "Payment Page" erforderlich!
Ein solches Projekt kann offenbar im GiroCockpit nicht selbständig eingerichtet werden; hier stehen nur Projekte zur Auswahl, die direkt an einzelne Bezahlmethoden gekoppelt sind.
Bitte wenden Sie sich daher an die Firma S-Public Services, die ein entsprechendes Projekt auf Anforderung einrichtet.



Nach Einrichtung des Projekts können einige Einstellungen für die Paypage (u. a. die darauf anzubietenden Bezahlmöglichkeiten = andere Projekte) im Cockpit vorgenommen werden.

Übermitteln Sie dem hbz die auf der Projektseite angezeigte Verkäufer-ID sowie die Projekt-ID und das Projekt-Passwort.

Klicken Sie im Projekt Payment Page auf Projekt bearbeiten und wählen dort Redirect über GET senden aus:


3.2.2. Anbindung an ePayBL

tbd.

3.3. Konfiguration des Bezahllinks für einen Onlinekatalog

Nachdem Sie alle Informationen dem hbz übermittelt haben und dort die Einrichtung der Middleware erfolgt ist, kann die Anbindung an den Onlinekatalog erfolgen.

3.3.1. Anbindung an Primo VE

In Alma muss zunächst für Primo ein sogenannter "Pay Fine Link" konfiguriert und aktiviert werden; vgl. die entsprechende offizielle Dokumentation von Ex Libris.
Der Screenshot zeigt den Eintrag im Administrationsmenü von Alma:



Die anzugebende URL dient zur Initialisierung eines Zahlungsvorgangs. Sie wird Ihnen vom hbz mitgeteilt und lautet beispielsweise:
https://libpay.hbz-nrw.de/initiate_payment/v1?apikey=XYZ

Wenn Sie den Link in Alma hinterlegt und aktiviert haben, wird in Primo im Benutzerkonto ein Bezahllink angezeigt:



Um nach der Rückkehr der Nutzer:innen von einem Zahlungsvorgang eine aktive Information als Pop-Up-Meldung anzuzeigen, kann entsprechender JavaScript-Code in Primo VE integriert werden (custom.js).
Ein passendes Code-Fragment wird vom hbz bereitgestellt und kann frei an lokale Bedürfnisse angepasst werden.


3.3.2. Anbindung an DigiBib IntrOX

Die Konfiguration wird durch die Mitarbeiter:innen des hbz vorgenommen.


3.3.3. Alternativ: Anbindung an andere lokale Systeme

Der Einbau des oben beschriebenen Aufrufs der Middleware sowie der Verarbeitung der Rückkehr-URL nach einem Zahlungsvorgang sollte keine besondere Herausforderung darstellen.

Es wurde darauf geachtet, weit verbreitete technische Komponenten zu verwenden und die Anforderungen an Discovery-Systeme und sonstige Frontends möglichst gering zu halten, indem die wesentliche Funktionalität innerhalb der Middleware gekapselt wird.

4. FAQ

Was passiert wenn sich die offenen Gebühren während eines Bezahlvorgangs ändern?

  1. Wenn sich die offenen Gebühren  erhöht  haben, verbleibt ein offener Betrag der anschließend über einen weiteren Bezahlvorgang bezahlt werden kann.
  2. Wenn sich die offenen Gebühren  verringert  haben, führt das zu einer Gutschrift auf dem Bibliothekskonto.

Somit ist sichergestellt,   dass kein Geld verloren gehen kann.

Wie kann in Alma bei einem Kunden kontrolliert werden, ob und wie eine Zahlung erfolgt ist?

Im Gebührenkonto kann bei jedem Gebührensatz in der Spalte  "offene Gebühren"  auf die Zahl geklickt werden.   Dort erfolgt eine Auflistung wie die Zahlung durchgeführt wurde.

  • Keine Stichwörter