1. Motivation

The integration of ePayment systems is a standard feature in eCommerce systems, offering the end customer in an online shop a wide variety of payment methods from credit card to purchase on account.

Hybris software provides a product information management system (PIM) serving the output channels commerce and print. Hybris Commerce allows processing the entire sales cycle on the Internet from the product to the shopping cart to the payment and the order confirmation.

With the payment system SOFORT provided by SOFORT, end customers benefit from a secure, convenient, and cost-effective payment service which does not require previous registration. Direct and automated credit transfers from the buyer's bank account to the merchant's bank account are processed within seconds via bank interfaces. The biggest benefit: Thanks to the prompt payment confirmation, the goods can be shipped immediately, and faster shipping conditions result in higher online sales.

To benefit from the advantages of both systems, ARITHNEA developed an interface between hybris and SOFORT, allowing a new, innovative payment method in the online shop: SOFORT provided by SOFORT.

The interface description of the hybris Extension "sofortüberweisung" is described in the following.

If you have any questions, please contact:

ecommerce@arithnea.de

2. Configuration

In order to use the hybris extension, it must be added to the project and registered in the file extensions.xml. The system must then be recompiled by the ant task integrated in hybris.

Figure 1: Navigation menu of the hybris console

An "update running system" must be executed via the admin web to generate the hybris types and deployment tables. The new payment method "sofortüberweisung" will then be available (see Figure 1).

The individual configurations are saved in the menu item "Configuration".

Possible configuration values (accounts, links, etc) can be created in the menu item "Configuration values". Payments made by SOFORT can be displayed under the menu item "Payment reservation".

2.1. Initialisation

Two procedures are available to initially fill the system with configuration values. They are described in the following.

The configurations are globally stored in hybris and can thus be used in the project at any time.

2.1.1. Via ImpEx

Parameters for the extension can be set by means of a CSV file (/resources/sofortueberweisung_config_1.csv).

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

Table 1: Change attributes via ImpEx I (extract)

These parameters are then assigned to a configuration in the CSV file  (/resources/sofortueberweisung_config_2.csv).

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

Table 2: Change attributes via ImpEx II

The generated CSV files including the values from table 1 and 2 can be uploaded to the system by means of the ImpEx interface of hybris.

Attention should be paid to the import coding for new hybris versions. Microsoft Windows users must select the coding "windows-1252" in most cases if the CSV file has been saved in this format.

2.1.2. Via hMC

The second option is to generate parameters directly via the hybris Management Console (hMC). For this purpose, a configuration interface has been integrated in the extension which allows to search for configurations or configuration values and to make changes if necessary.

Figure 2: Change attributes via hMC

2.2. Add payment method (PaymentMode)

The payment method "sofortüberweisung" must be registered in the system, either via ImpEx or hMC.

2.2.1. Via ImpEx

ImpEx uses a CSV file (/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

Table 3: Payment modes via ImpEx

2.2.2. Via hMC

Figure 3: Payment modes via hMC

 

The payment method can be created using the standard hMC functions.

2.3. Add transaction costs

For every payment method, at least one transaction cost entry should be made. These transaction costs may be entered via ImpEx or hMC.

2.3.1. Via hMC

The payment method "sofortüberweisung" must subsequently be added to the shipping methods. This is required for all shipping methods offering this payment method.

Figure 4: Shipping costs

 

For the purpose of illustration: In the menu item "Zahlungsarten - sofortüberweisung", the shipping method "DHL" is entered (see Figure 5).

Figure 5: Payment method sofortüberweisung

 

Under the tab "transaction costs" of the payment methods, new transaction costs can be entered with the right mouse button (Figure 6).

Figure 6: Payment method sofortüberweisung - enter transaction costs

2.4. Summary

The payment process for "sofortüberweisung" is configured via ImpEx or hMC. These two options allow to easily adjust the parameters to new requirements, even in the subsequent operation of a web shop.

3. Integration and use of the extension

To ensure the smooth integration of the SOFORT extension in your web shop, recommendations for the configuration and integration in the checkout process are given in the following. A workflow is suggested followed by the required Java methods.

3.1. Global configuration

The SOFORT extension must be registered as "required extension" in the frontend extension (extensioninfo.xml).

In case you use JSF as the frontend technology, you can use the provided managed bean "SofortueberweisungJSFBean". It must be entered in the file faces-config.xml.

Note: Please make sure that this entry must be adjusted concerning the package structure of your project.

3.2. Integration in the checkout process

Several possibilities are available to expand the checkout process by the payment method SOFORT. How to guide the user through the payment process is proposed here:

1. Cart
2. Select payment method SOFORT
3. Order overview
4. Click to pay (forwardToSofortueberweisung() or getPaymentUrl())
5. SOFORT  payment wizard is displayed
6. Customer aborts payment (getForwardToCancel() or cancelPayment())
7. Customer completes payments
8. SOFORT calls notification link (getFinalizeOrder(),z.B. per Servlet)
9. SOFORT calls success link (getFinalizeOrder())
10. After your shop has created an order based on the cart, the method finalizePayment() must be called to assign the payment to the order.

The methods used in the checkout process are described in the following:

3.2.1. The method "forwardToSofortueberweisung"

This method can be used to redirect the customer from the shop to the SOFORT payment wizard and to initiate the payment process. The necessary URL is determined by the configuration. The payment process can be initiated by using the method forwardToSofortueberweisung() of the managed bean, e.g. by a JSF button.

3.2.2. The method "getPaymentUrl"

This method is designed to return the URL for the SOFORT call from the stored data in hybris. The subject lines are also generated here. It is important to generate a unique number at least for subject 1. When using forwardToSofortueberweisung(), this method is called internally.

3.2.3. The method "getForwardToCancel"

Similar to the method forwardToSofortueberweisung() of item 3.2.1, this method can be called from the frontend to redirect a customer to a specific site if the payment was aborted (e.g. the page to select a payment method). An example is landingpage_error.xhtml. In this method, the method cancelPayment() is called which deletes the payment data stored in hybris if the payment was aborted.

3.2.4. The method "cancelPayment"

If the payment by SOFORT is to be aborted, this method serves to delete the transaction data stored so far.

3.2.5. The method "getFinalizeOrder"

This method can be called in two cases: first, via SOFORT payment notification link (backend), second, after reaching the success link page (frontend).

A servlet can be generated as payment notification which responds to HTTP-POST or HTTP-GET. The corresponding link must be specified in the SOFORT backend. After receipt of payment, SOFORT first calls the notification link. The important payment information are transferred via this link as parameters. These must be evaluated in the generated servlet by means of the method getFinalizeOrder() described here.

If one does not want to generate an own servlet, the frontend page "landingpage_finalize.xhtml" can be used for the payment notification. Please make sure that the notification method must be set to HTTP-GET in the SOFORT backend.

Subsequent to the notification, the success link is called. For this purpose, the template "landingpage_ok.xhtml" is provided.

In both cases (notification and success link), the method getFinalizeOrder() can be called. It is checked internally whether a payment has already been created. The transferred parameters are also checked by means of checkNotificationHash(). Subsequently, the transaction data is stored via assignRequestToPayment(). Finally, the user is redirected to a defined order confirmation page.

Note: Enhance the described method by your logic generating an order based on the cart.

The method "checkNotificationHash"

If a notification hash value is specified in the SOFORT configuration, it will be controlled by means of this method after the payment parameters have been returned with the notification. For this purpose, the payment information stored in the shop is compared with the data obtained from SOFORT. This method ensures the integrity of the data.

The method "assignRequestToPayment"

After the payment by SOFORT, the success link you defined is called, which has been specified on the project page of SOFORT. This method should be called for the processing of the request to store the data provided in the payment process in the database.

3.2.6. The method "finalizePayment"

This method is used to assign the stored transaction data to the order.

3.2.7. The method "isPaymentChosen"

This method allows to easily test whether the payment method "sofortueberweisung" has been set in the cart.

4. SOFORT backend settings

The SOFORT backend can be called via the URL www.sofort.com. The following settings must be made.

3.2.8. Success link

Various parameters can be transferred to the success link specified in the administration interface of SOFORT. Below is an example of potential transfer parameters:

It is recommended to transfer these parameters and to store the values in hybris for example to have all information at hand for customer service requests.

Please make sure that the parameters to be transferred are spelled correctly; otherwise, the information cannot be stored correctly in hybris.

On the grounds of data protection, the data to the sender is neither transferred nor stored in hybris.

3.2.9. Abort link

The abort link is analogous to the success link. All transferred parameters can be evaluated and stored in hybris.

In case of abort, the payment information should be deleted, similar to the process in the provided sample managed bean.

3.2.10. Notification link

The notification link is called by SOFORT to complete the order. It is called prior to the success link.

It must be ensured that the "HTTPSessionID" is transferred at any rate; otherwise, the order cannot be assigned. The parameter "hash" is transferred additionally as notification hash value.

3.2.11. Project password and notification password

In order to use the interface, a project password and notification password must be generated in the SOFORT backend.

3.2.12. Input check (hash)

When calling the payment wizard, a hash value is generated from the call parameters and transferred to the interface as the parameter "hash". This parameter is checked by the interface.

It must be ensured that the use of the input check in the administration interface must be activated by SOFORT.

4.1. Example of the payment method integration in the shop

Figure 7: Example of payment methods

The implementation of payment by SOFORT depends on your local conditions and can therefore be conducted in a number of different ways. Figure 7 shows a possible example of use.

4.1.1. SOFORT logos

We suggest the following SOFORT graphics to recommend the payment method to the customer.

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

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

Figure 8: Banners of payment methods

5. Support & Contact

The ''Direct Bank Transfer'' team will be available if you need help.

You may send us an email at service@sofort.com.

We are also glad to assist you in case of technical issues:

Technical support:
Phone: +49 (0)89 24 88 37 691
Email: integration@sofort.com

Business hours:
Monday to Thursday: 8:30 a.m. to 6:00 p.m.
Friday: 8:30 a.m. to 5:00 p.m.

6. Legal Notice

SOFORT GmbH
Theresienhöhe 12
80339 Munich
Germany

Support for customers
Phone: +49 (0)89 24 88 37 690

Support for merchants
Phone: +49 (0)89 24 88 37 692

info@sofort.com
www.sofort.com

Directors

Felix Würtenberger
Wilhelmus Geerling Klaassen

External Data Protection Officer
Mr. Michael Schramm, LL.M. 
For privacy questions please contact us at: datenschutz@sofort.com

Registered at the District Court Munich
HRB 218675
VAT-ID: DE248376956

© SOFORT GmbH. All rights reserved, including the translation.

The documentation including all published content is protected by copyright. Reprints or reproduction of any kind and processing, duplication, and distribution using electronic systems of any kind shall only be permitted with prior written consent of SOFORT GmbH.

The contents of this documentation and the implementation of the information contained therein may only be used at your own risk. SOFORT GmbH assumes no responsibility for the function of individual programmes or of parts of them. In particular, SOFORT GmbH assumes no responsibility for possible damages resulting from the use.