Hybris

1. Motivation

In eCommerce-Systemen gehört die Integration von ePayment-Systemen zur Standardausstattung. Hierbei werden dem Endkunden im Online-Shop die verschiedensten Zahlungsarten von Kreditkarte bis Rechnung angeboten.

hybris Software bietet ein Product-Information-Management-System (PIM) mit den Ausgabekanälen Commerce und Print. Dabei kann mit hybris Commerce der komplette Verkaufszyklus im Internet vom Produkt über den Warenkorb bis zur Zahlung und Bestellbestätigung abgewickelt werden.

Mit dem Zahlungssystem SOFORT Überweisung bietet die SOFORT einen sicheren, bequemen und kostengünstigen Bezahldienst ohne eine Registrierung für den Endkunden an. Über Bankschnittstellen zum Online-Banking des Kunden wird eine sekundenschnelle, direkte und automatisierte Überweisung vom Konto des Käufers auf das Konto des Händlers ermöglicht. Der Clou: Dank der sofortigen Zahlungsbestätigung kann die Ware sofort versendet werden und mit den schnelleren Lieferkonditionen ihr Online-Umsatz gesteigert werden.

Um die Vorteile beider Systeme zu nutzen hat ARITHNEA eine Schnittstelle zwischen hybris und SOFORT Überweisung entwickelt. Dabei wird im Webshop eine neue, innovative Bezahlmöglichkeit ermöglicht: SOFORT SÜberweisung der Firma SOFORT.

Nachfolgend finden Sie die Schnittstellenbeschreibung zur hybris Extension "sofortüberweisung".

Für Fragen wenden Sie sich bitte an:

ecommerce@arithnea.de

2. Konfiguration

Zur Nutzung der hybris Extension muss diese im Projekt eingefügt und in der Datei extensions.xml registriert werden. Das System muss anschließend durch den in hybris integrierten ant-Task neu kompiliert werden.

Abbildung 1: Navigationsleiste hybris-Konsole

Zur Erstellung der hybris Typen und Deploymenttabellen muss über das Adminweb ein "Update Running System" durchgeführt werden. Im Anschluss daran steht die neue Bezahlmethode "sofortüberweisung" zur Verfügung (siehe Abbildung 1).

Im Menüpunkt "Konfiguration" werden die einzelnen Konfigurationen gespeichert.

Mögliche Konfigurationswerte (Accounts, Links, etc.) werden im Menüpunkt "Konfigurationswerte" angelegt. Über den Menüpunkt "Zahlungsreservierung" können per SOFORT Überweisung getätigte Zahlungen angezeigt werden.

2.1. Initialisierung

Es besteht die Möglichkeit das System auf zwei Wege initial mit Konfigurationswerten zu füllen. Nachfolgend sind diese Methoden aufgeführt.

Die Konfigurationen werden global in hybris gespeichert und können somit jederzeit im Projekt verwendet werden.

2.1.1. Per ImpEx

Über eine CSV-Datei (/resources/sofortueberweisung_config_1.csv) können Parameter für die Extension gesetzt werden.

INSERT_UPDATE ConfigurationAttributes	code[unique=true]	key	value
	REQUEST_URL	REQUEST_URL	https://www.sofortüberweisung.de/ payment/start
	USER_ID	USER_ID	12345
	PROJECT_ID	PROJECT_ID	67890
	PROJECT_PASSWORD	PROJECT_PASSWORD	password
	NOTIFICATION_PASSWORD	NOTIFICATION_PASSWORD	password

Tabelle 1: Attribute per ImpEx ändern I (Auszug)

Diese Parameter werden dann in der CSV-Datei  (/resources/sofortueberweisung_config_2.csv) einer Konfiguration zugeordnet.

INSERT_UPDATE Configuration	code[unique=true]	configValues(code)
	sofortueberweisung-default_pay_order	USER_ID,PROJECT_ID,REQUEST_URL, PROJECT_PASSWORD,NOTIFICATION_PASSWORD

Tabelle 2: Attribute per ImpEx ändern II

Die erstellten CSV-Dateien mit den Werten aus Tabelle 1 und Tabelle 2 können über die ImpEx-Oberfläche von hybris in das System geladen werden.

Zu beachten ist bei neuen hybris-Versionen die Kodierung des Importes. Wenn mit Microsoft Windows gearbeitet wird, muss meist die Kodierung "windows-1252" ausgewählt werden, wenn die CSV-Datei in diesem Format gespeichert wurde.

2.1.2. Per hMC

Die zweite Möglichkeit ist, Parameter direkt über die hybris Management Console (hMC) anzulegen. Hierzu wurde eine Konfigurationsoberfläche in die Extension integriert, die es ermöglicht, nach Konfigurationen bzw. Konfigurationswerten zu suchen und diese ggf. abzuändern.

Abbildung 2: Attribute per hMC ändern

2.2. Hinzufügen der Zahlungsart (PaymentMode)

Die Zahlungsart "sofortüberweisung" muss im System registriert werden. Dies kann per ImpEx oder hMC erfolgen.

2.2.1. Per ImpEx

ImpEx erfolgt aus einer CSV-Datei (/resources/sofortueberweisung_config_3.csv).

INSERT_UPDATE StandardPaymentMode	code[unique]	name[lang=de]	name[lang=en]	...
	su	sofortüberweisung	sofortüberweisung
INSERT_UPDATE StandardPaymentModeValue	paymentmode(code) [unique=true]	currency(isoCode) [unique=true]	value
	su	EUR	0

...	description[lang=de]	description[lang=en]	active	paymentinfotype(code)
	per sofortüberweisung	payment with sofortüberweisung	true	Sofortueberweisung PaymentInfo

Tabelle 3: Payment Modes per ImpEx

2.2.2. Per hMC

Abbildung 3: Payment Modes per hMC

Über die Standard-hMC-Funktionen kann die Zahlungsart hier angelegt werden.

2.3. Hinzufügen von Transaktionskosten

Für jede Bezahlmethode sollte mindestens ein Transaktionskosteneintrag hinterlegt sein. Diese Transaktionskosten können wiederum per ImpEx oder über die hMC eingepflegt werden.

2.3.1. Per hMC

Die Zahlungsart "sofortüberweisung" muss im Anschluss zu den Lieferarten hinzugefügt werden. Dies ist bei allen Lieferarten notwendig, die diese Bezahlmethode anbieten sollen.

Abbildung 4: Versandkosten

Zur Veranschaulichung: Im Menüpunkt "Zahlungsarten" ist unter "sofortüberweisung" die Lieferart "DHL" registriert (siehe Abbildung 5).

Abbildung 5: Zahlungsart SOFORT Überweisung

Auf dem Tab "Transaktionskosten" der Bezahlmethoden können nun per rechter Maustaste neue Transaktionskosten angelegt werden (Abbildung 6).

Abbildung 6: Zahlungsart SOFORT Überweisung Transaktionskosten anlegen

2.4. Zusammenfassung

Die Konfiguration für den Bezahlvorgang mit "sofortüberweisung" erfolgt per ImpEx bzw. hMC. Mit diesen zwei Möglichkeiten ist es auch im späteren Betrieb eines Webshops  einfach, die Parameter an neue Bedürfnisse anzupassen.

3. Integration und Verwendung der Extension

Um die Integration der SOFORT Überweisungs-Extension in Ihren Webshop so einfach wie möglich zu gestalten, finden sich im Folgenden Hinweise zu Konfiguration und Integration in den Checkoutprozess. Dazu wird ein Workflow vorgeschlagen und nachfolgend die dazu notwendigen Java-Methoden erläutert.

3.1. Globale Konfiguration

Die SOFORT Überweisungs-Extension muss in der Frontend-Extension als "required extension" registriert werden (extensioninfo.xml).

Falls Sie JSF als Frontend-Technologie verwenden, können Sie die mitgelieferten Managed-Bean "SofortueberweisungJSFBean" verwenden. Sie muss dazu in der Datei faces-config.xml eingetragen werden.

Hinweis: Bitte beachten Sie, dass dieser Eintrag in Bezug auf die Package-Struktur ihres Projekts angepasst werden muss.

3.2. Integration in den Checkoutprozess

Zur Erweiterung des Checkoutprozesses um die Zahlungsart SOFORT Überweisung existieren mehrere Möglichkeiten. Hier ein Vorschlag zur Führung des Benutzers durch den Zahlungs-Prozess:

1. Warenkorb
2. Auswahl der Zahlungsart "SOFORT Überweisung"
3. Bestellübersicht
4. Klick auf Bezahlen (forwardToSofortueberweisung() bzw. getPaymentUrl())
5. Kunde befindet sich im SOFORT Überweisungs-Zahlungsfenster
6. Kunde bricht die Zahlung ab (getForwardToCancel() bzw. cancelPayment())
7. Kunde vervollständigt Zahlung
8. SOFORT Überweisung ruft Benachrichtungslink auf (getFinalizeOrder(), z.B. per Servlet)
9. SOFORT Überweisung ruft Erfolgslink auf (getFinalizeOrder())
10. Nachdem Ihr Shop aus dem Warenkorb eine Bestellung erzeugt hat, muss die Methode finalizePayment() aufgerufen werden, um die Zahlung der Bestellung zuzuordnen.

Im Folgenden werden die im Checkout-Prozess verwendeten Methoden erläutert:

3.2.1. Die Methode "forwardToSofortueberweisung"

Diese Methode kann genutzt werden, um den Kunden aus dem Shop auf das Zahlungsfenster von SOFORT Überweisung zu leiten und den Bezahlvorgang einzuleiten. Die dazu notwendige URL wird aus der Konfiguration ermittelt. Über die Verwendung der Methode forwardToSofortueberweisung() der Managed-Bean kann bspw. durch einen JSF-Button der Bezahlvorgang angestoßen werden.

3.2.2. Die Methode "getPaymentUrl"

Diese Methode dient dazu, aus den gespeicherten Daten in hybris die URL für den Aufruf von SOFORT Überweisung zurückzugeben. Hier werden auch die Betreffzeilen generiert. Dabei ist es wichtig, zumindest für Betreff 1 eine eindeutige Nummer zu erzeugen. Bei der Verwendung von forwardToSofortueberweisung() wird intern diese Methode aufgerufen.

3.2.3. Die Methode "getForwardToCancel"

Ähnlich wie die Methode forwardToSofortueberweisung() in Punkt 3.2.1 kann diese Methode aus dem Frontend aufgerufen werden, um einen Kunden nach dem Zahlungsabbruch auf eine spezifische Seite zu leiten (z.B. Seite zur Auswahl der Zahlungsarten). Als Beispiel finden Sie "langingpage_error.xhtml". In dieser Methode wird die Methode cancelPayment() aufgerufen, die das Löschen der gespeicherten Payment-Daten in hybris durchführt, wenn die Bezahlung abgebrochen wurde.

3.2.4. Die Methode "cancelPayment"

Soll die Bezahlung mit SOFORT Überweisung abgebrochen werden, dient diese Methode dazu, die bis dahin gespeicherten Transaktionsdaten zu löschen.

3.2.5. Die Methode "getFinalizeOrder"

Diese Methode kann in zwei Fällen aufgerufen werden. Zum einen per SOFORT Überweisungs-Zahlungsbenachrichtigungslink (Backend), zum anderen nach dem Erreichen der Erfolgslink-Seite(Frontend).

Als Zahlungsbenachrichtigung kann ein Servlet erstellt werden, das auf HTTP-POST bzw. HTTP-GET reagiert. Der Link dazu muss im SOFORT Überweisungs-Backend angegeben werden. SOFORT Überweisung ruft nach Erhalt einer Zahlung zuerst den Benachrichtigungslink auf. Über diesen werden alle wichtigen Zahlungsinformationen in Form von Parametern übermittelt. Im erstellten Servlet müssen diese mit Hilfe der hier beschriebenen Methode getFinalizeOrder() ausgewertet werden.

Will man kein eigenes Servlet erstellen, kann die Frontend-Seite  "landingpage_finalize.xhtml" für die Zahlungsbenachrichtigung verwendet werden. Bitte beachten Sie, dass hierbei im SOFORT Überweisungs-Backend die Benachrichtigungsmethode auf HTTP-GET gesetzt werden muss.

Im Anschluss an die Benachrichtigung wird der Erfolgslink aufgerufen. Hierzu ist die Vorlage "landingpage_ok.xhtml" mitgeliefert.

In beiden Fällen (Benachrichtigung und Erfolgslink) kann die Methode getFinalizeOrder() aufgerufen werden. Es wird intern geprüft, ob bereits eine Zahlung angelegt worden ist. Ebenso werden mittels checkNotificationHash() die übermittelten Parameter überprüft. Im Anschluss daran werden die Transaktionsdaten per assignRequestToPayment() gespeichert. Danach wird der Benutzer schließlich auf eine definierte Bestellbestätigungsseite geleitet.

Hinweis: Ergänzen Sie die beschriebene  Methode um Ihre Logik, die aus dem Warenkorb eine Bestellung erzeugt.

Die Methode "checkNotificationHash"

Ist ein Notification-Hashwert in der SOFORT Überweisungs-Konfiguration angegeben, so wird dieser nach Rückgabe der Zahlungsparameter über die Benachrichtigung (Notification) mit Hilfe dieser Methode kontrolliert. Dabei werden die im Shop gespeicherten Zahlungsinformationen mit den von SOFORT Überweisung erhaltenen, verglichen. Diese Methode dient zur Sicherstellung der Integrität der Daten.

Die Methode "assignRequestToPayment"

Nach der Bezahlung mit SOFORT Überweisung wird Ihr definierter Erfolgslink aufgerufen, der auf der Projektseite von SOFORT Überweisung angegeben wurde. In Folge der Abarbeitung des Requests sollte diese Methode aufgerufen werden, um die gelieferten Daten des Bezahlvorganges in der Datenbank zu speichern.

3.2.6. Die Methode "finalizePayment"

Mit Hilfe dieser Methode werden der Bestellung die gespeicherten Transaktionsdaten zugeordnet.

3.2.7. Die Methode "isPaymentChosen"

Mit dieser Methode kann einfachgetestet werden, ob die Bezahlmethode "SOFORT Überweisung" im Warenkorb gesetzt ist.

4. SOFORT Überweisung Backend Einstellungen

Das SOFORT Überweisung Backend kann über die URL www.sofort.com aufgerufen werden. Dabei müssen folgende Einstellungen durchgeführt werden.

3.2.8. Erfolgslink

Dem in der Administrationsoberfläche von SOFORT Überweisung gepflegten Erfolgslink können verschiedene Parameter übergeben werden. Hier finden Sie einen Beispiellink mit möglichen Übergabeparametern:

Es wird empfohlen diese Parameter zu übergeben und die Werte in hybris zu speichern, um bspw. bei Anfragen beim Kundenservice alle Informationen vorrätig zu haben.

Bitte achten Sie auf die korrekte Schreibweise der zu übergebenden Parameter, da sonst die Informationen nicht korrekt in hybris gespeichert werden können.

Aus Datenschutzgründen werden die Daten zum Sender allerdings nicht mit übergeben und auch nicht in hybris gespeichert.

3.2.9. Abbruchlink

Der Abbruchlink verhält sich analog dem Erfolgslink. Alle übergebenen Parameter können in hybris ausgewertet und gespeichert werden.

Im Abbruchsfall sollte die Payment-Information gelöscht werden, ähnlich wie es in der mitgelieferten Beispiel-Managed-Bean erfolgt.

3.2.10. Benachrichtigungslink

Der Benachrichtigungslinkwird von SOFORT Überweisung aufgerufen, um die Bestellung abzuschließen. Er wird vor Aufruf des Erfolgslinks aufgerufen.

Zu berücksichtigen ist hier, dass in jeden Fall die "HTTPSessionID" mit übergeben werden muss, da sonst keine Zuordnung zur Bestellung möglich ist. Der Parameter "hash" wird zusätzlich als Benachrichtigungs-Hashwert übermittelt.

3.2.11. Projektpasswort und Benachrichtigungspasswort

Zur Verwendung der Schnittstelle müssen Sie ein Projektpasswort und ein Benachrichtigungspasswort generieren lassen. Dies erfolgt im SOFORT Überweisung Backend.

3.2.12. Inputprüfung (Hash)

Bei Aufruf des Zahlungsfensters wird ein Hashwert aus den Aufrufparametern gebildet und an die Schnittstelle in als Parameter "hash" übermittelt. Dieser wird von der Schnittstelle überprüft.

Zu beachten ist, dass die Benutzung der Inputprüfung in der Administrationsoberfläche von SOFORT Überweisung aktiviert werden muss.

4.1. Beispiel der Integration der Zahlungsart in den Shop

Abbildung 7: Zahlungsarten Beispiel

Die Implementierung der Bezahlung mit SOFORT Überweisung obliegt Ihren lokalen Gegebenheiten und kann daher von Ihnen auf verschiedene Art und Weise durchgeführt werden. In Abbildung 7 sehen Sie ein mögliches Anwendungsbeispiel.

4.1.1. SOFORT Überweisung-Logos

Um dem Endkunden die Zahlungsart näher zu bringen, werden folgende Grafiken von SOFORT empfohlen.

https://images.sofort.com/de/su/banner_300x100.png

https://images.sofort.com/en/su/banner_300x100.png

Abbildung 8: Banner Zahlungsarten

5. Support & Kontakt

Das Team von Sofort steht Ihnen zur Verfügung, sollten Sie Hilfe benötigen.

Sie können uns eine E-Mail an service@sofort.com schreiben.

Auch bei technischen Fragen helfen wir Ihnen gerne weiter:

Technische Beratung:
Telefon: +49 (0)89 24 88 37 691
E-Mail: integration@sofort.com

Geschäftszeiten:
Montag-Donnerstag: 08:30-18:00 Uhr
Freitag: 08:30-17:00 Uhr

6. Impressum

SOFORT GmbH
Theresienhöhe 12
80339 München
Deutschland

Informationen für Käufer und Online-Shopper:
Telefon: +49 (0)89 24 88 37 690

Informationen für Verkäufer und Händler:
Telefon: +49 (0)89 24 88 37 692

info@sofort.com
www.sofort.com

Geschäftsführung

Felix Würtenberger
Wilhelmus Geerling Klaassen

Externer Datenschutzbeauftragter

Hr. Michael Schramm, LL.M. 
Für Fragen zum Datenschutz wenden Sie sich bitte an: datenschutz@sofort.com

Eingetragen beim Amtsgericht München
HRB 218675
USt-ID: DE248376956

© SOFORT GmbH. Alle Rechte, einschließlich der Übersetzung, vorbehalten.

Die Dokumentation einschließlich aller veröffentlichten Inhalte ist urheberrechtlich geschützt. Nachdruck oder Reproduktion jeglicher Art sowie die Verarbeitung, Vervielfältigung und Verbreitung unter Verwendung elektronischer Systeme in irgendeiner Form bedarf der vorherigen schriftlichen Genehmigung der SOFORT GmbH.

Die Verwendung dieser Dokumentation und die Umsetzung der darin enthaltenen Angaben erfolgt ausdrücklich auf eigenes Risiko. Die SOFORT GmbH übernimmt keine Gewähr für die Funktion einzelner Programme oder von Teilen derselben. Insbesondere übernimmt die SOFORT GmbH keine Haftung für etwaige, aus dem Gebrauch resultierende Folgeschäden.