Magento Community

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 Magento Community 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:

http(s)://-USER_VARIABLE_3-

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:

http(s)://-USER_VARIABLE_4-

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:

http(s)://-USER_VARIABLE_5- Please use "POST" as transmission method.

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

4.1. Uninstallation of the old module (Version < 1.1.0)

If you have already been using the old version of the SOFORT interface, you should uninstall it before installing the new module. Please proceed as follows:

Log in to your Magento Admin and navigate to “System → Magento Connect → Magento Connect Manager”
Go to the package „Mage_SOFORT Überweisung“, select the action „Uninstall“, and click the button „Commit Changes“.

4.2. Module installation

To provide the module for your Magento Shop, you have to install it using the Magento Connect Manager.

Request extension key

You will receive the corresponding extension key from the following URL:

http://www.magentocommerce.com/magento-connect/Payment-Network/extension/3725/pn_sofortueberweisung

Click „Install now“ and follow the instructions.

Instead of requesting the extension key there, you can also copy the following code to the corresponding field of your Magento Connect Manager (see below):

Magento Connect 1.0:

magento-community/pn_sofortueberweisung

Magento Connect > 1.0:

http://connect20.magentocommerce.com/community/pn_sofortueberweisung

4.3. Extension installation

Return to the admin area of your Magento Shop.

Go to the setting System → Magento Connect
Log in in the new window. You must have administration rights to install extensions with the Connect Manager.
Paste the corresponding extension key to the field „Paste extension key to install:“.
To install the extension, click the button „Install“. A console area will open to carry out the installation process. If the module has already been installed and a new module version is available, you can install an update by clicking „Check for Upgrades“.
The installation has been completed. If you activated the cache in Magento, you have to update it to display the module in the shop.

If you want to use modules for Magento which are still in the beta phase, you may have to allow modules with beta status to be installed. Click the tab „Settings“ in the Magento Connect Manager and select „Preferred State“ Beta in the dropdown list. Please note that beta modules are not final versions and may contain errors.

5. Module configuration

Go to System → Configuration in your shop backend.
Select „Payment methods“ in the left menu.
Select the module „sofort.com iDEAL“.
Activate iDEAL by choosing "Yes" in the dropwown "Acitvate Module".

The following settings can be made:

Holding order status:This status will be set when the payment has not been successfully accomplished.
Unconfirmed order status: This status will be set until the payment has been confirmed by iDEAL.
Confirmed order Status: This status will be set when the customer has completed the payment successfully.
Configuration key: Enter the configuration key from your project settings here. You have to enter the configuration key to use the module.
Project password: Enter the project password from your project settings here. You have to enter this password to use the module.
Notification password: Enter the notification password from your project settings here. You have to enter this password to use the module.
Sort sequence: You may determine the position in the payment selection.

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.