Merchant Login
...

VirtueMart / Joomla!

Integration manual
IDEAL

PDF Download

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.
Ablauf iDEAL Kommunikation API-Classic

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 VirtueMart iDEAL :

  1. Register as a merchant on our website https://www.sofort.com/register
  2. Create a new SOFORT project and configure it
  3. Install the SOFORT module in the shop
  4. 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)://<URL to your shopsystem>/index.php?option=com_virtuemart&view=pluginresponse&task=pluginresponsereceived&on=-REASON_1-&pm=-USER_VARIABLE_0-

  • 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)://<URL to your shopsystem>/index.php?option=com_virtuemart&view=pluginresponse&task=pluginUserPaymentCancel&on=-REASON_1-&pm=-USER_VARIABLE_0-

  • 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)://<URL to your shopsystem>/index.php?option=com_virtuemart&view=pluginresponse&task=pluginnotification&tmpl=component

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. Payment method activation

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

As VirtueMart already integrates VirtueMart you only need to activate the payment method:

  1. Navigate in the VirtueMart shop backend to "Components > VirtueMart > Payment Methods".
  2. Click "New" in the icon bar and insert the text "iDEAL" as "Payment Name" (keep in mind that the name needs to be inserted for each language).
  3. Choose for "Published": "Yes".
  4. Choose "Sofort iDeal" in the dropdown "Payment Method".
  5. Configure the position of the payment method for the payment method selection in the checkout at "List Order" (Default: 1).
  6. Click "Save" in the icon bar.
Modul Aktivierung VirtueMart/Joomla (iDEAL)

5. Payment method configuration

After successful activation of the payment method the configuration follows:

  1. Open the Tab "Configuration" (in your backend at "Components > VirtueMart > Payment Methods > iDEAL").
  2. Insert the configuration key of your VirtueMart project at "Configuration key" (you can find this key in your project settings in the SOFORT merchant area).
  3. Also insert the "Project password" and the "Notification password" (you can find these passwords in your project settings in the SOFORT merchant area). If one of these passwords contains the letter "|", please generate a new password in the SOFORT merchant menu that does not contain this letter.
  4. Click "Save" in the icon bar. Your shop is now ready to accept payments via VirtueMart .
Modul Konfiguration VirtueMart/Joomla (iDEAL)

Integration of a logo for the payment method:

  1. You first need to download the current logo for iDEAL
  2. In your VirtueMart backend, go to Content, and then choose Media Manager from the list. You will see a list of images, and folders that are already in the Media manager.
  3. Select the folder stories, and then virtuemart, and then payment
  4. Go in the Upload files area, and click on Browse files
  5. Select on your computer the logo
  6. Press Start upload. The file will be transfered to the selected folder.
  7. Go to "Components > VirtueMart > Payment Methods > iDEAL > Configuration" and add the desired image at "Logos".

If you want to configure further settings you can use the fields described in the following:

  • Order status: in the following dropdowns you define the order status in VirtueMart that is set according to the status at SOFORT.
    • For Pending transactions: is set if the payment via VirtueMart has not been finished yet.
    • For Confirmed transactions: is set if the payment has been successfully.
    • For Canceled transactions: is set if the payment has been interrupted.
    • For Partially refunded Transactions: is set if the payment has been prepared and consolidated for a partial refund at SOFORT.
    • For Refunded transactions: is set if the payment has been prepared and consolidated for a complete refund at SOFORT.
  • Currencies: here you can configure the accepted currencies
    • Payment Currency
  • Restrictions:
    • Countries: select the countries in which you want to offer  VirtueMart (empty: no restriction) (default: empty)
    • Minimum Amount: minimum amount of a cart so that the customer can pay via VirtueMart . (default: empty)
    • Maximum Amount: maximum amount of a cart so that the customer can pay via VirtueMart . (default: empty)
    • Fee per transaction: fixed fee that a customer has to pay for the use of VirtueMart . (default: empty)
    • Precent of the total product amount: variable fee that a customer has to pay for the use of VirtueMart according to the amount of the cart. (default: leer)
    • Tax
  • Debug?: if activated, interface calls of the VirtueMart API will be logged. (default: no)

Information on orders, that have been payed with VirtueMart can be found in the order summary "Orders & Shoppers > Orders".

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:

  1. Activate test mode (see above)
  2. Place an order in your system and select iDEAL as payment method
  3. Transfer test data for the individual cases
  4. 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

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