commerce:SEO

Integration manual
IDEAL

1. Introduction to iDEAL

The payment method iDEAL is of particular interest to merchants who want to sell their product in the Netherlands. Here, the payment is carried out based on the online banking of the customers in the Netherlands.

Your Dutch customers (end customers) do not have to register for iDEAL: They can make a fast and easy payment using their online banking details. Thanks to real time acknowledgement of the transfer order, you as a merchant can immediately ship the goods or provide services.

From your customer's perspective, an iDEAL transaction consists of the following steps:

As soon as payment is requested by iDEAL, the customer selects the Dutch bank of his/her current account and is redirected via a SOFORT page to the iDEAL payment form.
Below the overview of the transfer data (recipient, reason, amount), your customer is requested to authorise the payment.
The next step is the selection of the account to be used for the payment.
After a successfully completed transaction, your customer is redirected back to your shop.

IMPORTANT!

You need a Deutsche Handelsbank account in order to use iDEAL.
The application must be integrated in the system of the provider in such manner that the URL and the SSL certificate of SOFORT can be recognised and verified for the customer of the provider.
The standard coding used for all parameters is UTF-8! Please bear this in mind especially for hash computation.
The account data (account number, IBAN) are transferred as masked entries for the redirection via the success link and the HTTP notification. Sole exception: HTTPS protocol with POST method

2. Integration steps

The following steps are required to integrate iDEAL in commerce:SEO iDEAL :

Register as a merchant on our website https://www.sofort.com/register
Create a new SOFORT project and configure it
Install the SOFORT module in the shop
Set up the SOFORT module in the administration backend of your shop

3. iDEAL project setup

3.1. Registration at ''Direct Bank Transfer''

In order to be able to offer ''Direct Bank Transfer'' in your shop, a customer account with ''Direct Bank Transfer'' is required.

If you do not have such an account you may register at https://www.sofort.com/register.

After your registration, you have to be logged on in the merchant area and have to create a project for your system / online shop. If you do not use ''Direct Bank Transfer'', you have to activate the desired product. Go to "My account > Product activation" in the left navigation bar.

3.2. Create a new SOFORT project

To set up a project, log in to the SOFORT merchant menu and click "New project" in the left column. Select "Create iDEAL Project" under SOFORT Classic Project.

IMPORTANT: Please choose iDEAL as the desired project.

You will be asked at this point whether you already have aDeutsche Handelsbank account. To apply for a Deutsche Handelsbank account, fill the account request and click "Save". The account request will be sent to you by email. Print out the request and send it back to Deutsche Handelsbank by PostIdent including all required documents.

NOTE!

Before the project can be used, it must be reviewed and activated by SOFORT.
You need a Deutsche Handelsbank account to create an iDEAL project. You can apply for an account during project setup. Please contact Deutsche Handelsbank by email at support@handelsbank.com for any questions.

Complete your project data now. The most important settings are:

General settings

Project name: Enter the name of your shop here.
Shop system: Select your shop system.
Test mode: By activating this option, you can test iDEAL. More information can be found in the "Testing" chapter. In activated test mode, you can generate test transactions which will not become effective and which therefore will not cause any cost. Real transactions cannot be carried out in test mode.

Address

Enter the data for form of address, first and last name, name additive, street, street additive, post code, city, and country to be displayed to the customer on the iDEAL payment wizard.
Industry: Select your industry.
Website: Enter the URL of your online shop.

Interface

Success link: Enter the URL (starting with "http://" or "https://") of your shop system to which your customers are to be redirected after successful completion of the iDEAL payment. If you use a standard shop module, you can find the necessary information at the top in the help text (blue "i") under "Shop System" or on the configuration pages of your shop module. Please enter the following for your shop system:

Abort link: Enter the URL (starting with "http://" or "https://") of your shop system to which your customers are to be redirected after an unsuccessful or faulty iDEAL payment process. If you use a standard shop module, you can find the necessary information at the top in the help text (blue "i") under "Shop System" or on the configuration pages of your shop module. Please enter the following for your shop system:

Timeout in seconds: Enter the time in seconds which may elapse when calling the iDEAL payment wizard before your customer will be redirected by SOFORT to the abort link.

Notifications

Activate email notification: Mark this checkbox if you want to be notified by email of an iDEAL payment.
Email address: Enter the email address to be used for notifications.
Language: Determine the language in which the confirmation email is to be written.
Activate HTTP(S) notification: Activate this checkbox if you want to be notified of an iDEAL payment by calling a HTTP(S) page (or a PHP script).
HTTP(S) URL: Enter the URL (starting with "http://" or "https://") of your shop system to be called in case of a notification of an iDEAL payment. Please enter the following for your shop system:

After you have saved the settings, please select the tab "Extended settings". Go to "Passwords and hash algorithm" to create a Project password and a Notification password and to determine the Hash algorithm " " for the input check.

If you desire, you can set a master password under "Extended settings > Master Password" to protect your project settings. Only those who know the master password can change the settings in the project. This is useful when a colleague for example is only allowed to verify the payments.

4. Interface installation

It is recommended to make a backup copy of your shop and database before you make any changes in your shop system.

NOTE:

Please carry out the following steps before the installation to safely remove non-compatible payment methods:
(if the payment methods "SOFORT Lastschrift" and "Vorkasse by SOFORT" are not displayed under " Modules > Payment Systems ", you can skip the next four steps, and continue at "Interface download")

Please write down the settings of the used SOFORT payment methods.
Uninstall all SOFORT payment methods ("SOFORT", "Rechnung by SOFORT", "Lastschrift by SOFORT", "SOFORT Lastschrift" and "Vorkasse by SOFORT"). Click " Modules > Payment " in the shop backend, select the corresponding payment method, and click "Uninstall".
Then delete the files (even if you did not install the payment methods) "/<path to shoproot>/includes/modules/payment/sofort_sofortlastschrift.php" and "/<path to shoproot>/includes/modules/payment/sofort_sofortvorkasse.php".
Install the new SOFORT payment methods as described below.

Interface download

In order to use iDEAL in your shop system, you first have to download the SOFORT module for commerce:SEO : https://www.sofort.com/integrationCenter-eng-DE/.

Extract the file to your local hard drive (e.g. by 7-Zip or WinRAR).

4.1. SOFORT module upload to your web server

Copy the content of the folder " sofort_cseo_5.3.1.zip " to the web server running your shop by means of an FTP programme (e.g. FileZilla).

Open the directory of the SOFORT module in the FTP programme (see figure, left) until the three folders "callback", "includes", and "lang" are displayed. Go to the basic directory in your commerce:SEO shop on your web server (see figure, right). You will also see the directories "includes" and "lang". Now move the directories of the SOFORT module to commerce:SEO on your web server as shown in the figure (exemplary figure as directory structure may differ in your shop).

4.2. Payment method installation in the shop

Go to " Modules > Payment " in your shop backend.
Select the desired payment method. The payment method is always sofort_(product name)
To install a payment method, click the payment method and then the button "Install" in the right window. To configure the module, click "Edit".

5. Module configuration

To configure the payment method, go to " Modules > Payment ", select the module " iDEAL ", and click "Edit".

The following settings can be made:

iDEAL - Activate sofort.de module: Determines whether the payment method is to be displayed in the payment method selection (true) or not (false)
recommended payment method: Activate this setting (true) to make the respective SOFORT product a recommended payment method.
Assigned configuration key by SOFORT: Enter the configuration key from your project settings in the SOFORT merchant menu here. You have to enter the configuration key to use the module.
test configuration key: By clicking the button "Test", an API call is made and the communication between the shop module and the API is tested
project password: Enter the project password assigned by SOFORT (can be found in the SOFORT merchant menu).
notification password: Enter the notification password assigned by SOFORT (can be found in the SOFORT merchant menu).
Payment zone: If a zone is selected, this payment method only applies to this zone. Otherwise ("--none--"), the payment zones are not restricted.
Payment zone: Enter individual zones of the shop which are to be allowed for this module (e.g. AT, DE - if left empty, all zones are allowed).
Reason 1: You can determine that the order number ({{order_id}}) and customer number ({{customer_id}}) are to be entered as a reference on the iDEAL transfer form.
Reason 2: You can enter another static reason (maximum of 27 characters) as a reference on the iDEAL transfer form.
logo+text: The selection defines the display of the respective payment method in the payment method selection. It can be displayed as a banner (info graphic) or as a logo with a descriptive text (logo and text)
Temporary order status: order status for non-completed transactions. The order was made, but the transaction has not yet been confirmed by SOFORT. (Standard: "Payment pending")
Confirmed order status: order status after a successfully completed transaction. (Standard: "Confirmed")
Order state at aborted payment: order status for orders which have been cancelled during the payment process (either by the customer or by SOFORT). (Standard: "Payment aborted")
Order status at full cancellation: order status for orders which have been completely cancelled. (Standard: "Cancelled")
Partial refund: order status if part of the amount has been refunded to the customer. (Standard: "Partial refund")
Full refund: order status if the full amount has been refunded to the customer. (Standard: "Refund")
Automatic cancellation of refund: status of orders for which the payment was received after the timeout specified in the SOFORT project and which were therefore automatically cancelled. The refund to the buyer account will also be transferred automatically. (Standard: "Refund")
Sort sequence: You can determine here the sequence of the payment method selection (e.g. "0" topmost).

6. Testing

You can activate the test mode for your project in the merchant area (under "My projects > Select project > Base settings> Test mode") to test the correct integration and the functionality of the HTPP(S) notification.

As soon as the test mode has been activated, the following iDEAL status messages can be activated by the following amounts:

1 EUR => Successful payment
2 EUR => Payment aborted
3 EUR => Expired payment (errorCode 6001)
4 EUR => Pending payment
5 EUR => Payment error (errorCode 6000)

The amounts with the corresponding status messages are also listed in a drop down list which is displayed in the SOFORT merchant area with activated test mode.

NOTE!

Real transactions cannot be carried out if test mode is active.

6.1. Functional test

In order to fully test the functionality of the iDEAL integration, please carry out a test transfer directly in your system. Please follow these steps:

Activate test mode (see above)
Place an order in your system and select iDEAL as payment method
Transfer test data for the individual cases
Check correct redirection
- Is the customer redirected to the confirmation page after the transaction?
- Are all notifications received correctly?
- Is the order status set correctly and is the order created correctly?

6.2. System test (payment wizard)

In the merchant area, the tab "Test project" provides a test opportunity in your iDEAL project with SOFORT. You can specify different parameters to issue the HTML code for calling the interface and the string for hash generation. Additionally, you can call the payment wizard and go through all steps of the transfer.

This way of testing is not appropriate to simulate the entire process.

7. 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.

8. 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

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.