Händler-Login

API Dokumentation

iDEAL

1. Einführung zu iDEAL

Die Zahlart iDEAL ist insbesondere für Anbieter/Händler interessant, die Produkte in den Niederlanden verkaufen wollen. Hierbei wird auf Basis des Online Bankings der Kunden in den Niederlanden die Zahlung durchgeführt.

Für iDEAL müssen sich Ihre niederländischen Kunden (Endkunden) nicht registrieren: Sie bezahlen schnell und einfach mit ihren bekannten Online-Banking Daten. Dank Echtzeitbestätigung des Überweisungsauftrags können Sie als Händler die Ware sofort versenden beziehungsweise Dienstleistungen sofort erbringen.

Eine Transaktion mit iDEAL gliedert sich aus Sicht Ihrer Kunden in folgende Schritte:

  • Sobald ein Kunde per iDEAL bezahlen möchte, wählt er die niederländische Bank seines Girokontos und wird über eine Seite von SOFORT auf das iDEAL Zahlformular geleitet.
  • Unter der dortigen Übersicht der Überweisungsdaten (Zahlungsempfänger, Verwendungszweck, Betrag) wird Ihr Kunde aufgefordert, die Zahlung zu autorisieren.
  • Anschließend folgt die Auswahl des Kontos, über das die Zahlung abgewickelt werden soll.
  • Nach erfolgreicher Transaktion gelangt Ihr Kunde wieder zurück zu Ihrem Webshop.
Ablauf iDEAL Kommunikation API-Classic

WICHTIG!

  • Für die Nutzung von iDEAL ist ein Konto bei der Deutschen Handelsbank notwendig.
  • Die Anwendung muss in das System des Anbieters dergestalt integriert werden, dass die URL und das SSL-Zertifikat der SOFORT für den Kunden des Anbieters erkennbar und überprüfbar ist.
  • Die verwendete Standardcodierung für alle Parameter ist UTF-8! Bitte beachten Sie dies besonders bei der Hash-Berechnung.
  • Die Kontodaten (Kontonummer, IBAN) werden bei der Rückleitung über den Erfolgslink und die HTTP-Benachrichtigung maskiert übertragen. Einzige Ausnahme: HTTPS-Protokoll mit Methode POST

2. Integrationsschritte

Um iDEAL über SOFORT in Ihr System zu integrieren, sind allgemein folgende Schritte notwendig. Eine detaillierte Beschreibung der einzelnen Schritte folgt anschließend:

  1. Erstellen Sie ein Testprojekt bei SOFORT:
    1. Registrieren Sie sich als Anbieter auf unserer Seite https://sofort.com/register.
    2. Aktivieren Sie im Anbietermenü das Produkt "iDEAL" (unter "Mein Konto > Produkt-Aktivierung")
    3. Erstellen Sie ein neues iDEAL-Projekt (unter "Projekte > Neues Projekt > SOFORT-Classic-Projekt > iDEAL-Projekt anlegen").
    4. Nachdem für "iDEAL" ein Konto bei der Deutschen Handelsbank benötigt wird, müssen Sie im nächsten Schritt auswählen, dass Sie bereits über ein solches verfügen oder aber ein neues anlegen wollen ("Ich habe ein Deutsche Handelsbank Konto" bzw. "Ich habe noch kein Deutsche Handelsbank Konto").
    5. Konfigurieren Sie Ihr iDEAL-Projekt (Erfolgs-/Abbruch-/Benachrichtigungslink & Hashalgorithmus - abhängig von der Implementierung).
    6. Nach Projektanlage und -konfiguration erhalten Sie einen API-Key sowie ein Projekt- und ein Benachrichtigungspasswort. (den API-Key finden Sie auch im linken Menü unter "Weitere Dienste > API-Key", bzw. die Passwörter, wenn Sie im iDEAL Projekt unter "Erweiterte Einstellungen > Passwörter und Hashalgorithmus" öffnen).
    7. Melden Sie sich bei SOFORT, um Ihren Anbieteraccount als Testaccount zu konfigurieren.
  2. Anschließend folgt die Shop Integration:
    1. Im Checkout ist die Zahlart iDEAL als Auswahl inklusive der Bankenauswahl per Dropdown-Feld zu integrieren.
    2. Sobald ein Kunde mit iDEAL bezahlen möchte, leiten Sie ihn an unsere Schnittstelle mit den jeweiligen Zahlungsdaten weiter.
    3. Der Kunde wickelt die Zahlung auf unseren bzw. den iDEAL Seiten ab und wird anschließend auf die von Ihnen definierte Erfolgs- bzw. Abbruchseite Ihres Shops zurückgeleitet.
    4. Im Fall einer erfolgreichen iDEAL Transaktion (d.h. die Überweisung wurde von Ihrem Kunden in Auftrag gegeben), sowie bei weiteren Statusänderungen, werden Sie automatisch von SOFORT über diese Transaktion benachrichtigt. Anschließend können sie sofort weitere Schritte, wie bspw. Warenversand oder Freischaltung zum Online-Angebot, veranlassen. Die Benachrichtigung kann dabei sowohl per E-Mail, als auch via XML-HTTP-Benachrichtigung an die Benachrichtigungsseite im Shop erfolgen.
    5. Das Shopsystem verarbeitet die Benachrichtigungen automatisch und ändert die Bestell-/Zahlungsstatus entsprechend.

3. Integration von iDEAL

Damit Ihre Kunden iDEAL als Zahlungsverfahren auswählen können, müssen Sie in einem ersten Schritt iDEAL im Checkout Ihres Shops einbinden. Wählt der Kunde iDEAL als Zahlungsverfahren und bestätigt seine Bestellung, beginnt die Kommunikation zwischen Ihrem Shop und unserer Schnittstelle (API). Bevor einzelne Schritte des Prozesses zu iDEAL inklusive der API-Aufrufe detailliert beschrieben werden, folgen einige Rahmenbedingungen, die für eine erfolgreiche Ausführung von iDEAL Überweisungen notwendig sind.

3.1. Einbindung von iDEAL im Checkout

Zur Einbindung von iDEAL im Checkout, ist es notwendig bei der Auswahl der Zahlarten eine weitere Option für iDEAL hinzuzufügen (bspw. als neuer Radiobutton, Link, ... - Details hierzu finden Sie in der Dokumentation Ihres Shopsystems). Da Kunden bei der Bezahlung mit iDEAL über SOFORT auf das Portal der jeweiligen niederländischen Bank weitergeleitet werden, muss der Kunde bereits bei der Zahlartenauswahl seine Bank (idealerweise aus einem Dropdown-Feld) auswählen. Der Inhalt des Dropdown-Felds ist über eine XML-API abzurufen.

3.2. Kommunikation mit den Schnittstellen für iDEAL

Der erste Aufruf - die Abfrage der verfügbaren Banken für die Bankenauswahl im Checkout - unserer Schnittstelle (API) erfolgt aus Ihrem Shop durch ein HTTP Aufruf. Die Antwort der API ist XML-formatiert.

  • (API-Schritt 0) Abruf der iDEAL Bankeninformation inkl. Antwort der API

Alle weiteren Aufrufe unserer API erfolgen aus Ihrem Shop heraus durch ein HTTP Aufruf (entweder per GET oder POST) mit Name-Value-Pair (NVP) Parametern. Die Antworten erfolgen nach dem gleichen Prinzip.

Die direkte Kommunikation mit unserer Schnittstelle über NVP-HTTP Nachrichten läuft immer nach demselben Prinzip ab:

  • (API-Schritt 1) Weiterleitung des Kunden auf das iDEAL Zahlformular (über SOFORT) und Übergabe der Transaktionsparameter
  • (Kundenschritt) Einstellung der Überweisung auf iDEAL und Weiterleitung auf Erfolgs-/Abbruchlink.
  • (API-Schritt 2) Benachrichtigung über eine Änderung des Transaktionsstatus

Wenn Sie für die Integration die Programmiersprache PHP verwenden, stellen wir dazu eine Programmier-Bibliothek (SOFORTLib) zur Verfügung, welche die Implementierung in Ihr System wesentlich erleichtert. Implementierungsbeispiele und eine kurze Anleitung zur Verwendung der SOFORTLib finden Sie im Integrations-Center.

Detailinformationen zu den einzelnen API Aufrufen und Antworten finden Sie im Abschnitt "Parameterübersicht".

3.3. Abruf der iDEAL Bankeninformation inkl. Antwort der API (API-Schritt 0)

Da die Abwicklung der iDEAL Zahlungen auf den Portalen der jeweiligen niederländischen Sender Bank durchgeführt wird, muss der Kunde bereits im Checkout seine Bank wählen. Die Auswahl wird anschließend in der Weiterleitung des Kunden an SOFORT als BIC übergeben. Dazu soll der Kunde auf der Zahlungsauswahlseite im Shop seine Bank per Dropdownmenü auswählen. Für den anschließenden Aufruf (API-Schritt 1) übergeben Sie bitte die korrekte BIC (im Feld sender_bank_code) an uns.

3.3.1. Aufruf der API und Authentifizierung 

Um Missbrauch der Schnittstelle zu verhindern, wird für jeden Aufruf der XML-Schnittstelle eine Authentifizierung durchgeführt. Hierzu wird Ihre Kundennummer als Benutzername und der API-Key als Passwort übergeben. Den API-Key können Sie im Anbietermenü unter Weitere Dienste → API-Key einsehen. Um die Schnittstelle verwenden zu können, müssen Sie folgende Dinge beachten, die in der Parameterübersicht auch detailliert erklärt werden:

  • Sie müssen die korrekte URL aufrufen und dabei HTTPS als Protokoll verwenden.
  • Sie müssen die korrekten Authentifizierungsinformationen übermitteln. Zur Authentifizierung wird die Basic-HTTP-Authentication (RFC 2617) verwendet.
  • Sie müssen die korrekten Content-Type Header angeben.
  • Ihr Aufruf muss per HTTP POST verschickt werden.

Der Aufruf der Schnittstelle erfolgt über folgende URL:

https://www.sofort.com/payment/ideal/banks

Die Antwort ist XML formatiert und könnte wie folgt aussehen:

<?xml version="1.0" encoding="UTF-8" ?>
<ideal>
    <banks>
        <bank>
            <code>ABNANL2A</code>
            <name>ABN Amro</name>
        </bank>
        <bank>
            <code>FRBKNL2L</code>
            <name>Friesland Bank</name>
        </bank>
        ...
    <banks>
</ideal>

3.4. Weiterleitung des Kunden auf das iDEAL Zahlformular (über SOFORT) und Übergabe der Transaktionsparameter (API-Schritt 1)

Für den Aufruf müssen verschiedene Parameter an unsere API übergeben werden. Einige Parameter sind dabei obligatorisch, andere können optional verwendet werden. Damit sichergestellt werden kann, dass diese Daten auf dem Weg zwischen Shopsystem und SOFORT nicht geändert werden, werden Teile der Nachricht zusammen mit dem Projektpasswort gehasht und als Hashwert mit übertragen. Details zur Verwendung der einzelnen Parameter sowie der Hashwert Berechnung finden Sie in der Parameterübersicht.

Der Formular-Aufruf erfolgt an folgende URL:

https://www.sofort.com/payment/ideal

Bitte implementieren Sie den Aufruf nur über diese URL und übergeben Sie die notwendigen Parameter (siehe Abschnitt Parameterübersicht), andernfalls wird Ihnen eine Fehlermeldung angezeigt. Sie haben die Möglichkeit die Parameter mit den Methoden GET oder POST zu übermitteln. Für GET hängen Sie die Variablen an den obigen Link an, für POST werden die Parameter in einem Formular im Body der Anfrage übergeben.

Beispielhafter Schnittstellenaufruf mit Hashwert und user_variable (Methode POST):

<form method="post" action="https://www.sofort.com/payment/ideal">
    <input type="hidden" name="user_id" value="12345" />
    <input type="hidden" name="project_id" value="654321" />
    <input type="hidden" name="amount" value="30.00" />
    <input type="hidden" name="reason_1" value="Bestellnummer 1" />
    <input type="hidden" name="sender_bank_code" value="ABNANL2A" />
    <input type="hidden" name="sender_country_id" value="NL" />
    <input type="hidden" name="user_variable_0" value="Ihr Wert" />
    <input type="hidden" name="hash" value="7aa872ed86b411654478d95c4adfefd09dfaf75a" />
    <input type="submit" value="Mit iDEAL bezahlen" />
</form>

Beispielhafter Schnittstellenaufruf als Link (Methode GET):

https://www.sofort.com/payment/ideal?user_id=12345&project_id=654321&amount=30.00&
     reason_1=Bestellnummer%201&sender_bank_code=ABNANL2A&sender_country_id=NL&
     user_variable_0=Ihr%20Wert&hash=7aa872ed86b411654478d95c4adfefd09dfaf75a

3.5. Einstellung der Überweisung auf iDEAL und Weiterleitung auf Erfolgs-/Abbruchlink (Kundenschritt)

Im nächsten Schritt führt Ihr Kunde die Überweisung in iDEAL aus.

Sofern die iDEAL Überweisung erfolgreich durchgeführt wurde, wird Ihr Kunde auf den im Projekt hinterlegten Erfolgslink weitergeleitet. Idealerweise wird ihm dort in einer abschließenden Zusammenfassung die Bestellung inklusive der erfolgreichen iDEAL Überweisung bestätigt. Im Hintergrund sollte Ihr Shopsystem inzwischen den Warenkorb geleert, die Bestätigung der Transaktion erhalten (siehe API-Schritte 2) und die Bestellung mit entsprechendem Status abgespeichert haben.

Sollte die iDEAL Überweisung nicht erfolgreich beendet worden sein, so wird Ihr Kunde auf den Abbruchlink weitergeleitet. Dieser sollte idealerweise unter Angabe einer Fehlermeldung auf die Auswahl des Zahlungsverfahrens zurückleiten, während der Kunde nach wie vor seinen Warenkorb gefüllt hat.

3.6. Benachrichtigung über eine Änderung des Transaktionsstatus (API-Schritt 2)

Sofern die iDEAL Überweisung erfolgreich durchgeführt wurde, werden Sie parallel zur Weiterleitung des Kunden auf den Erfolgslink, über die durchgeführte Transaktion benachrichtigt. Dies geschieht durch den Aufruf des Benachrichtigungs-URLs, den Sie im Projekt hinterlegt haben (wahlweise als HTTP POST oder als HTTP GET). In dieser Benachrichtigung wird die Transaktions-ID der Transaktion übergeben, deren Status sich geändert hat. Damit sichergestellt werden kann, dass diese Daten auf dem Weg zwischen SOFORT und Shopsystem nicht geändert werden, sind Teile der Nachricht zusammen mit dem Benachrichtigungspasswort gehasht und als Hashwert mit übertragen. Dieser Hashwert ist im Shopsystem zu prüfen, bevor der Status einer Bestellung geändert werden darf. Details zu den einzelnen Parametern sowie der Hashwert Berechnung finden Sie in der Parameterübersicht.

ACHTUNG: Die Hash-Berechnung für die Benachrichtigung unterscheidet sich deutlich von der Hash-Berechnung beim Aufruf unseres Zahlformulars (API-Schritt 1).

Bei der Input-Prüfung wird ein Hashwert aus weniger Parametern mit dem Projekt-Passwort gebildet, da zu diesem Zeitpunkt auch weniger Informationen über den Zahlungsvorgang bekannt sind. Bei der Hash-Berechnung für die Benachrichtigung hingegen sind alle Informationen über die Zahlung bekannt und werden somit auch in die Berechnung des Hashwertes in Verbindung mit dem Benachrichtigungspasswort einbezogen (siehe Abschnitt Parameterübersicht). Zudem übergeben wir Ihnen alle zur Hash-Berechnung notwendigen Parameter automatisch und der Vergleich der Hashwerte erfolgt in Ihrem Skript.

Eine beispielhafte Benachrichtigung der Schnittstelle (Methode POST) könnte so aussehen:

transaction=12345-654321-51E811F3-BA51&user_id=12345&project_id=654321&sender_holder=Max%20Mustermann&
     sender_account_number=&sender_bank_name=ABN+Amro&sender_bank_bic=RABXXXXX&
     sender_iban=NL17RXXXXXXXXXXX12&sender_country_id=NL&recipient_holder=Gert%20Schopper&
     recipient_account_number=99XXXXXX99&recipient_bank_code=700XXXXX&recipient_bank_name=SOFORT+BanX&
     recipient_bank_bic=DEKTXXXXXXX&recipient_iban=DE71700XXXXXXXXXXXXX99&recipient_country_id=DE&
     amount=30.00&currency_id=EUR&reason_1=Bestellnummer+1&reason_2=&user_variable_0=Ihr+Wert&
     user_variable_1=&user_variable_2=&user_variable_3=&user_variable_4=&user_variable_5=&
     created=2013-07-18+18%3A04%3A13&status=received&status_reason=credited&
     status_modified=2013-07-18+18%3A04%3A13&hash=e1f3c94a897025a5d9e6e41c33a32e6056ec981a

Eine solche Benachrichtigung erhalten Sie bei jeder Statusänderung Ihrer Transaktion.

Statusmeldungen

In der Benachrichtigung finden Sie den aktuellen Status einer Transaktion.

Eine Transaktion wird erst dann bei SOFORT angelegt, wenn der Kunde die Zahlung bei iDEAL erfolgreich durchgeführt hat. Da es bei iDEAL unter Umständen dauern kann, bis die Zahlung garantiert bestätigt wird, kann als Status "pending" übermittelt werden. Wenn anschließend die Zahlung durch iDEAL garantiert bestätigt wird, wechselt der Status auf "received". Sofern die Zahlung bei iDEAL nicht garantiert bestätigt werden kann bzw. anderweitig Fehler durch iDEAL berichtet werden, folgt als Status "loss". Im Fall einer (Teil-)Rückbuchung des überwiesenen Betrages kann des Weiteren noch der Status "refunded" auftreten.

Weitere Detailinformationen zu möglichen Status und deren Beschreibung finden Sie in der Parameterübersicht.

3.7. Fehlermeldungen

Wurden User- und Projekt-ID falsch oder gar nicht übergeben, leiten wir den Endkunden auf eine Fehlerseite von uns weiter. In allen anderen Fällen wird der Endkunde bei einer fehlgeschlagenen Validierung zur Abbruchseite des Shops weitergeleitet, an die die jeweiligen Fehlercodes als HTTP GET Parameter übergeben werden.

Die einzelnen Fehlercodes sowie deren Beschreibungen, finden Sie in der Fehlerübersicht in der Parameterübersicht. Ein beispielhafter URL für den Aufruf der Fehlerseite mit Fehlercode könnte folgendermaßen aussehen:

http://www.mein-shop.de/cancel.php?error_codes=7008,7014

4. Testen

Um die korrekte Einbindung zu Testen und auch die Funktionalität der HTTP(S)-Benachrichtigung zu überprüfen, können Sie Ihr Projekt im Anbietermenü in den Testmodus setzen (unter „Meine Projekte -> Ihr Projekt auswählen -> Schnelleinstellungen -> Testmodus).

Sobald der Testmodus aktiviert ist, können Sie mit folgenden Beträgen verschiedene Statusmeldungen bei iDEAL provozieren:

  • 1 EUR => Erfolgreiche Zahlung
  • 2 EUR => Abbruch der Zahlung
  • 3 EUR => Abgelaufene Zahlung (errorCode 6001)
  • 4 EUR => Ausstehende Zahlung
  • 5 EUR => Fehler bei der Bezahlung (errorCode 6000)

Die Beträge mit den zugehörigen Statusmeldungen befinden sich auch im in einer Drop-Down Liste, die Ihnen bei aktiviertem Testmodus im SOFORT Anbietermenü angezeigt wird.

ACHTUNG!

Bei aktivem Testmodus können keine realen Transaktionen durchgeführt werden.

4.1. Funktionstest

Um die Funktionalität Ihrer Einbindung von iDEAL komplett zu testen führen Sie bitte die Testüberweisung direkt über Ihr System aus. Dies sind die einzelnen Schritte:

  1. Aktivieren des Testmodus (siehe oben)
  2. Bestellung in Ihrem System durchführen und iDEAL als Zahlungsart auswählen
  3. Testdaten für die verschiedenen Fälle übergeben
  4. Überprüfen der korrekten Rückleitung
    • Wird nach der Transaktion auf die Bestätigungsseite geleitet?
    • Kommen alle Benachrichtigungen richtig an?
    • Wird der Bestellstatus richtig gesetzt bzw. wird die Bestellung korrekt angelegt?
4.2. Systemtest (Zahlformular)

Eine Testmöglichkeit bietet Ihnen der Karteireiter 'Projekt testen' in Ihrem iDEAL-Projekt im Anbietermenü bei der SOFORT. Hier können Sie verschiedene Parameter vorgeben und sich dann den HTML-Code für den Aufruf der Schnittstelle sowie den String für die Hashgenerierung ausgeben lassen. Außerdem können Sie das Zahlformular aufrufen und die einzelnen Schritte der Überweisung durchgehen.

Diese Art des Testens ist nicht geeignet, um den kompletten Prozess zu simulieren.

5. Parameterübersicht

Falls Sie die Programmier-Bibliothek (SOFORTLib) nicht verwenden, finden Sie hier die Dokumentation der XML-Schnittstelle zum Abruf der Bankinformationen sowie der Name-Value-Pair(NVP)-Schnittstelle.

Erklärung der Tabellenspalten der nachfolgenden Tabellen

  • Parameter: Name des Parameters, der übergeben wird.
  • Pflicht: gibt an, ob ein Parameter übergeben werden muss (Ja) oder nicht (Nein)
  • Typ (Länge): gibt den Datentyp des Parameter-Inhalts an, sofern dies ein String ist, wird die maximal erlaubte Zeichenanzahl angegeben
  • Erklärung: detaillierte Beschreibung der Verwendung des Parameters
5.1. (API-Schritt 0) Abruf der iDEAL Bankeninformation inkl. Antwort der API

Die Abfrage der Bankeninformation über die SOFORT Schnittstelle erfolgt indem folgende URL aufgerufen wird:

https://www.sofort.com/payment/ideal/banks

Dabei wird zur Authentifizierung die Basic-HTTP-Authentication (RFC 2617) verwendet. Als Benutzername verwenden Sie bitte Ihre Kundennummer (bspw. 12345) und als Passwort Ihren API-Key (bspw. a12b34cd567890123e456f7890123456), die Sie durch ":" getrennt aneinander fügen und mit Base64 codieren (base64(12345:a12b34cd567890123e456f7890123456)).

Bei jeder Anfrage muss im HTTP Header sowohl das Feld Content-Type als auch das Feld Accept mit "application/xml" belegt werden.

Ein resultierender Beispiel HTTP-Header sieht dann wie folgt aus:

Authorization: Basic MTIzNDU6YTEyYjM0Y2Q1Njc4OTAxMjNlNDU2Zjc4OTAxMjM0NTY=
Content-Type: application/xml; charset=UTF-8
Accept: application/xml; charset=UTF-8

Sofern die Authentifizierung erfolgreich war, bestätigt der Server Ihren API-Aufruf mit HTTP 200 OK und liefert als Antwort ein XML Dokument mit den gewünschten Informationen zurück:

Parameter Anzahl Typ (Länge) Erklärung
ideal [1] Container Identifiziert die Antwort auf den initialen Aufruf, umschließt die komplette Nachricht
  banks [1] Container Liste mit Banken
    bank [0..n] Container Container für eine Bank
      code [1] String(255) Der BIC einer Bank, der im API-Schritt 1 als "sender_bank_code" übergeben werden muss
      name [1] String(255) Name der Bank, der im Dropdown-Feld in der Zahlartenauswahl erscheinen soll

Tabelle 1: Parameterdefinition des initialen Aufrufs zur Abfrage von Bankinformationen (API-Schritt 0)

Hinweis: Diese Art des API Aufrufs gilt nur für den API-Schritt 0.

5.2. (API-Schritt 1) Weiterleitung des Kunden auf das iDEAL Zahlformular (über SOFORT) und Übergabe der Transaktionsparameter

Die im Weiteren beschriebenen Name-Value-Pair-Parameter (NVP) sind per HTTP POST in der Weiterleitung des Käufers auf das Zahlformular an folgende URL zu übergeben:

https://www.sofort.com/payment/ideal
5.2.1. Parameter
Parameter Pflicht Typ (Länge) Erklärung
user_id Ja Integer Kundennummer des Händlers
project_id Ja Integer Projektnummer des iDEAL Projekts
sender_holder Nein String (27) Kontoinhaber (Kunde)
sender_account_number Nein String (30) Kontonummer des Kontos des Kunden
sender_bank_code Ja String (30) BIC des Kontos des Kunden (vgl. API-Schritt 0)
sender_country_id Ja String (2) Länderkürzel des Kunden (NL)
amount Ja Double (8,2) Der zu überweisende Betrag (Minimum: 0.10 EURO, wichtig für Testbestellungen). Bitte keine Trennzeichen bei Tausender-Beträgen, z.B. 1010,50 Euro
reason_1 Ja String (27)

Der Verwendungszweck in Zeile 1 (max. 27 Zeichen). Dieser sollte bei jeder Bestellung unterschiedliche Zuordnungsmerkmale aufweisen (z.B. Bestellnummer, Datum der Bestellung) und ist damit eindeutig.

Bitte beachten Sie die Hinweise am Ende der Tabelle hinsichtlich der zu verwendenden Zeichen.

reason_2 Nein String (27)

Der Verwendungszweck Zeile 2 (für weitere Zuordnungen zur Bestellung; max. 27 Zeichen)

Bitte beachten Sie die Hinweise am Ende der Tabelle hinsichtlich der zu verwendenden Zeichen.

user_variable_0 Nein String (255) Kundenvariable 0; zur freien Verwendung
user_variable_1 Nein String (255) Kundenvariable 1; zur freien Verwendung
user_variable_2 Nein String (255) Kundenvariable 2; zur freien Verwendung
user_variable_3 Nein String (255) Kundenvariable 3; zur freien Verwendung
user_variable_4 Nein String (255) Kundenvariable 4; zur freien Verwendung
user_variable_5 Nein String (255) Kundenvariable 5; zur freien Verwendung
hash Ja String (>=32) Hashwert für die Input-Prüfung (weitere Details siehe unten)
language_id Nein String (2); * Legen Sie mit diesem Parameter die Sprache der Fehlermeldung fest, mögliche Werte sind: NL, DE, EN, FR, ES, IT, PL
interface_timeout Nein Integer; * Zeitraum in Sekunden, innerhalb der die Transaktion auf dem Zahlformular abgeschlossen werden muss. Mögliche Werte sind von 180 bis 900.
interface_version Nein String (20); * Schnittstellenname, Shopsystemname und Versionsnummer der Schnittstelle in abgekürzter Form (z.B. sofort-ideal_xtc_v4.0); Parameter ist nur für Shopsystemhersteller relevant; bitte halten Sie sich an das Beispiel

Tabelle 2: Parameterdefinition der Weiterleitung des Kunden auf das Zahlformular (API-Schritt 1)

*Achtung: Dieser Parameter wird nicht in die Hashberechnung einbezogen.

Die Inhalte in den Parametern Kundenvariable 0-5 nehmen wir beim Aufruf unserer Schnittstelle entgegen und geben Sie am Ende des Zahlungsprozesses in der Benachrichtigung oder (sofern gewünscht) im Abbruch-, bzw. Erfolgslink an Sie zurück.

ACHTUNG:
In den Parametern reason_1 und reason_2 sind nur folgende Zeichen erlaubt: '0-9', 'a-z', 'A-Z', ' ', '+', ',', '-', '.'. Umlaute werden ersetzt, also z.B. ä -> ae. Andere Zeichen werden für die Darstellung auf unserer Zahlungsseite sowie für Benachrichtigungen entfernt. Bei der Rückleitung (Erfolgs- und Abbruchlink und Benachrichtigungen) kann deshalb ein veränderter String für reason_1 und reason_2 zurückgegeben werden. Bei der Inputprüfung (d.h. bei der Hashberechnung) von API-Schritt 1 bedeutet dies, dass der Prüfhash bei SOFORT noch vor der Umwandlung des Verwendungszwecks berechnet wird, weshalb dies so auch für die Hasherstellung im Shopsystem so durchzuführen ist.

Zudem gilt es zu beachten, dass die Kombination aus beiden Verwendungszweckzeilen nicht länger als 32 Zeichen sein darf und wir nach 32 Zeichen abschneiden. Da die beiden Verwendungszweckzeilen intern bei SOFORT zusammengefügt und durch ein Leerzeichen getrennt werden, bleiben somit netto insgesamt 31 Zeichen übrig. Bitte beachten Sie dies bei der Hashwert-Berechnung (die vollen Verwendungszweckzeilen können Sie lediglich in Ihrem Anbietermenü bei SOFORT einsehen).

5.2.2. Hash-Berechnung für die Weiterleitung zu iDEAL (für API-Schritt 1)

Berechnung des Hashwertes in PHP beim Aufruf der Schnittstelle:

<?php
     $data = array( '12345',         // user_id
                          '54321',         // project_id
                          '',                 // sender_holder
                          '',                 // sender_account_number
                          '21',              // sender_bank_code
                          'NL',              // sender_country_id
                          '30.00',          // amount
                          'Verwendung', // reason_1
                          '',                 // reason_2
                          '',                 // user_variable_0
                          '',                 // user_variable_1
                          '',                 // user_variable_2
                          '',                 // user_variable_3
                          '',                 // user_variable_4
                          '',                 // user_variable_5
                          'geheim'        // project_password
                        );
     $data_implode = implode('|', $data);
     $hash = sha1($data_implode);
     echo $hash;
?>

Berechnung des Hashwertes in Java beim Aufruf der Schnittstelle:

import java.security.MessageDigest;
public class HashCalculation {
     public String user_id = "";
     public String project_id = "";
     public String sender_holder = "";
     public String sender_account_number = "";
     public String sender_bank_code = "";
     public String sender_country_id = "";
     public String amount = "";
     public String reason_1 = "";
     public String reason_2 = "";
     public String user_variable_0 = "";
     public String user_variable_1 = "";
     public String user_variable_2 = "";
     public String user_variable_3 = "";
     public String user_variable_4 = "";
     public String user_variable_5 = "";
     public String project_password = "";
     public String hash() {
          String result = "";
          String input = this.user_id + "|" + this.project_id + "|" + this.sender_holder + "|" + this.sender_account_number +
                             "|" + this.sender_bank_code + "|" + this.sender_country_id + "|" + this.amount + "|" + this.reason_1 +
                             "|" + this.reason_2 + "|" + this.user_variable_0 + "|" + this.user_variable_1 + "|" + this.user_variable_2 +
                             "|" + this.user_variable_3 + "|" + this.user_variable_4 + "|" + this.user_variable_5 + "|" + this.project_password;
          StringBuffer result = new StringBuffer();
          try {
               MessageDigest messageDigest = MessageDigest.getInstance("MD5");
               byte[] md5 = messageDigest.digest(input.getBytes("UTF-8"));
               for(int i = 0; i < md5.length; i++) {
                    result.append( Integer.toHexString((0xF0 & md5[i]) >> 4);
                    result.append( Integer.toHexString((0x0F & md5[i])));
               }
          } catch (Exception e) {
               e.printStackTrace();
          }
          return result.toString();
     }
     public static void main(String[] args) {
          HashCalculation calculation = new HashCalculation();
          calculation.user_id = "12345";
          calculation.project_id = "54321";
          calculation.sender_bank_code = "21";
          calculation.sender_country_id = "NL";
          calculation.amount = "30.00";
          calculation.reason_1 = "Verwendung 1";
          calculation.project_password = "geheim";
          System.out.println(calculation.hash());
     }
}

Hashwert-Berechnung in C# / ASP.NET beim Aufruf der Schnittstelle:

public string calculateHash() {
     string p = userId.ToString() + "|" + projectId.ToString() + "|" + senderHolder + "|" + senderAccountNumber + "|" +
                   senderBankCode + "|" + senderCountryId + "|" + amount.ToString() + "|" + reason1 + "|" + reason2 + "|" +
                   userVariable0 + "|" + userVariable1 + "|" + userVariable2 + "|" + userVariable3 + "|" + userVariable4 + "|" +
                   userVariable5;
     return System.Web.Security.FormsAuthentication.HashPasswordForStoringInConfigFile(p, "sha1");
}

5.3. (API-Schritt 2) Benachrichtigung über Änderung des Transaktionsstatus

Im Folgenden sind die Parameter beschrieben, die bei einer Benachrichtigung über eine Änderung des Transaktionsstatus mitgeschickt werden.

Parameter Datentyp Erklärung
transaction String (27) Transaktions-ID (eindeutig)
user_id Integer Kundennummer des Händlers
project_id Integer Projektnummer des iDEAL Projekts
sender_holder String (255) Absender Kontoinhaber (Kunde) (kann ggf. leer zurückgegeben werden)
sender_account_number String (30) ehem. Kontonummer des Bankkontos des Kunden (hier wird kein Wert mehr übergeben)
sender_bank_name String (255) Bankname des Bankkontos des Kunden
sender_bank_bic String (50) BIC des Bankkontos des Kunden (kann ggf. leer zurückgegeben werden)
sender_iban String (50) IBAN des Bankkontos des Kunden (kann ggf. leer zurückgegeben werden)
sender_country_id String (2) Länderkürzel des Kunden
recipient_holder String (255) Empfänger Kontoinhaber (Händler)
recipient_account_number String (30) Kontonummer des Bankkontos des Händlers
recipient_bank_code String (30) Bankleitzahl des Bankkontos des Händlers
recipient_bank_name String (255) Bankname des Bankkontos des Händlers
recipient_bank_bic String (50) BIC des Bankkontos des Händlers
recipient_iban String (50) IBAN des Bankkontos des Händlers
recipient_country_id String (2) Länderkürzel des Händlers
amount Double (8, 2) Betrag
currency_id String (3) Währung [EUR]
reason_1 String (255) Verwendungszweck 1
reason_2 String (255) Verwendungszweck 2
user_variable_0 String (255) Kundenvariable 0
user_variable_1 String (255) Kundenvariable 1
user_variable_2 String (255) Kundenvariable 2
user_variable_3 String (255) Kundenvariable 3
user_variable_4 String (255) Kundenvariable 4
user_variable_5 String (255) Kundenvariable 5
created Datetime Zeitpunkt der Überweisung im Format 2013-07-19 09:28:02
status String (20) Status der Überweisung (Ausprägungen siehe unten)
status_reason String ()* Details zum Status der Überweisung
status_modified Datetime Zeitpunkt der Statusänderung
hash String (>=32)* Prüfsumme (siehe nächstes Unterkapitel)

Tabelle 3: Parameterdefinition der Benachrichtigung (API-Schritt 2)

*Achtung: Dieser Parameter wird nicht in die Hashberechnung einbezogen.

5.3.1. Status von iDEAL Transaktionen

In einer Benachrichtigung ist auch stets ein Status der Transaktion enthalten. Im Normalfall kann die Transaktion sofort durch iDEAL garantiert bestätigt werden. Dann erhalten Sie den Status 'received' und können Ihre Ware versenden / den Download freigeben. Sollte iDEAL die Transaktion nicht sofort bestätigen, erhalten Sie den Status 'pending'. Hier sollten Sie dann auf die endgültige Statusänderung warten:

  • pending → received (Sie können die Ware nun versenden.)
  • pending → loss (Die Transaktion konnte nicht durchgeführt werden.)

Im Fall einer (Teil-)Rückbuchung des überwiesenen Betrages kann des Weiteren noch der Status "refunded" auftreten.

Sie werden über die Statusänderung per Email bzw. per HTTP-Benachrichtigung informiert (sofern im Projekt hinterlegt).

status status_reason Erklärung
pending not_credited_yet iDEAL hat die Transaktion noch nicht bestätigt. Sie erhalten eine Benachrichtigung, wenn sich der Status ändert.
received credited Die Transaktion konnte erfolgreich abgeschlossen werden.
loss not_credited Die Transaktion konnte doch nicht durchgeführt werden.
refunded compensation Das Geld wurde zurückerstattet (Teilrückbuchung).
refunded refunded Das Geld wurde zurückerstattet (komplette Rückbuchung des Gesamtbetrags).

Tabelle 4: Statusmeldungen für Transaktionen mit iDEAL (API-Schritt 2)

5.3.2. Hash-Berechnung zur Benachrichtigung (für API-Schritt 2)

Hashwert-Berechnung in PHP für Benachrichtigungen:

<?php
     $data = array( 'transaction' => 'TRANSACTION',
                         'user_id' => 'USER_ID',
                         'project_id' => 'PROJECT_ID',
                         'sender_holder' => 'SENDER_HOLDER',
                         'sender_account_number' => 'SENDER_ACCOUNT_NUMBER',
                         'sender_bank_name' => 'SENDER_BANK_NAME',
                         'sender_bank_bic' => 'SENDER_BANK_BIC',
                         'sender_iban' => 'SENDER_IBAN',
                         'sender_country_id' => 'SENDER_COUNTRY_ID',
                         'recipient_holder' => 'RECIPIENT_HOLDER',
                         'recipient_account_number' => 'RECIPIENT_ACCOUNT_NUMBER',
                         'recipient_bank_code' => 'RECIPIENT_BANK_CODE',
                         'recipient_bank_name' => 'RECIPIENT_BANK_NAME',
                         'recipient_bank_bic' => 'RECIPIENT_BANK_BIC',
                         'recipient_iban' => 'RECIPIENT_IBAN',
                         'recipient_country_id' => 'RECIPIENT_COUNTRY_ID',
                         'amount' => 'AMOUNT',
                         'currency_id' => 'CURRENCY_ID',
                         'reason_1' => 'REASON_1',
                         'reason_2' => 'REASON_2',
                         'user_variable_0' => 'USER_VARIABLE_0',
                         'user_variable_1' => 'USER_VARIABLE_1',
                         'user_variable_2' => 'USER_VARIABLE_2',
                         'user_variable_3' => 'USER_VARIABLE_3',
                         'user_variable_4' => 'USER_VARIABLE_4',
                         'user_variable_5' => 'USER_VARIABLE_5',
                         'created' => 'CREATED',
                         'status' => 'STATUS',
                         'status_modified' => 'STATUS_MODIFIED',
                         'notification_password' => 'NOTIFICATION_PASSWORD');
     $data_implode = implode('|', $data);
     $hash = sha1($data_implode);
     echo $hash;
?>

Hashwert-Berechnung in Java für Benachrichtigungen:

import java.security.MessageDigest;
public class HashCalculation {
     public String transaction = "";
     public String user_id = "";
     public String project_id = "";
     public String sender_holder = "";
     public String sender_account_number = "";
     public String sender_bank_name = "";
     public String sender_bank_bic = "";
     public String sender_iban = "";
     public String sender_country_id = "";
     public String recipient_holder = "";
     public String recipient_account_number = "";
     public String recipient_bank_code = "";
     public String recipient_bank_name = "";
     public String recipient_bank_bic = "";
     public String recipient_iban = "";
     public String recipient_country_id = "";
     public String amount = "";
     public String currency_id = "";
     public String reason_1 = "";
     public String reason_2 = "";
     public String user_variable_0 = "";
     public String user_variable_1 = "";
     public String user_variable_2 = "";
     public String user_variable_3 = "";
     public String user_variable_4 = "";
     public String user_variable_5 = "";
     public String created = "";
     public String status = "";
     public String status_modified = "";
     public String notification_password = "";
     public String hash() {
          String result = "";
          String input = this.transaction + "|" + this.user_id + "|" + this.project_id + "|" + this.sender_holder + "|" +
                             this.sender_account_number + "|" + this.sender_bank_name + "|" + this.sender_bank_bic + "|" +
                             this.sender_iban + "|" + this.sender_country_id + "|" + this.recipient_holder + "|" +
                             this.recipient_account_number + "|" + this.recipient_bank_code + "|" + this.recipient_bank_name + "|" +
                             this.recipient_bank_bic + "|" + this.recipient_iban + "|" + this.recipient_country_id + "|" +
                             this.amount + "|" + this.currency_id + "|" + this.reason_1 + "|" + this.reason_2 + "|" +
                             this.user_variable_0 + "|" + this.user_variable_1 + "|" + this.user_variable_2 + "|" +
                             this.user_variable_3 + "|" + this.user_variable_4 + "|" + this.user_variable_5 + "|" + this.created + "|" +
                             this.status + "|" + this.status_modified + "|" + this.notification_password;
          StringBuffer result = new StringBuffer();
          try {
               MessageDigest messageDigest = MessageDigest.getInstance("MD5");
               byte[] md5 = messageDigest.digest(input.getBytes("UTF-8"));
              
               for(int i = 0; i < md5.length; i++) {
                    result.append( Integer.toHexString((0xF0 & md5[i]) >> 4);
                    result.append( Integer.toHexString((0x0F & md5[i])));
               }
          } catch (Exception e) {
               e.printStackTrace();
          }
          return result.toString();
     }
}

5.4. Fehlercodes

Folgende Fehlercodes können im iDEAL Zahlprozess entstehen und werden im Ersetzungsparameter -ERROR_CODES- zurückgegeben (zu Erstetzungsparametern siehe auch nächster Abschnitt):

Code Message
1000 Invalid request.
1001 Technical error.
6000 An unknown error occured.
6001 Session expired.
7007 Amount required.
7008 Invalid amount.
7009 Reason required.
7010 Invalid sender country id.
7011 Invalid recipient country id.
7012 Invalid sender bank code.
7013 Sender account equals recipient account.
7014 Invalid hash.

Tabelle 5: Mögliche Fehlercodes, die mit Weiterleitung auf den Abbruchlink übergeben werden

ACHTUNG!
Falls mehrere Fehler gleichzeitig auftreten, erhalten Sie die Fehlercodes mit "," getrennt (z.B. error_codes=7012,7013,7014).

5.5. Ersetzungsparameter Rückleitung

Die folgenden Variablen können Sie an die URLs (Erfolgs-, Abbruch- und Benachrichtigungs-URL) als Werte von Parametern anhängen. Diese werden dann durch unser System durch die echten Werte ersetzt.

Parameter Bedeutung
-USER_VARIABLE_0- Kundenvariable 0 - 5
-USER_VARIABLE_1-
-USER_VARIABLE_2-
-USER_VARIABLE_3-
-USER_VARIABLE_4-
-USER_VARIABLE_5-
 
-USER_VARIABLE_0_URLENCODE- Kundenvariablen 0 – 5
-USER_VARIABLE_1_URLENCODE-
-USER_VARIABLE_2_URLENCODE-
-USER_VARIABLE_3_URLENCODE-
-USER_VARIABLE_4_URLENCODE-
-USER_VARIABLE_5_URLENCODE-
 
-USER_VARIABLE_0_HASH_PASS-

Kundenvariable 0 – 5 codiert im gewählten Algorithmus; Berechnet sich wie folgt:

„gewählter Algorithmus“ z.B.

SHA1(KundenvariableProjekt-Passwort)

-USER_VARIABLE_1_HASH_PASS-
-USER_VARIABLE_2_HASH_PASS-
-USER_VARIABLE_3_HASH_PASS-
-USER_VARIABLE_4_HASH_PASS-
-USER_VARIABLE_5_HASH_PASS-
 
-USER_ID- Ihre Kundennummer
-PROJECT_ID- Ihre Projektnummer
-TRANSACTION- Transaktions-ID (wird bei jedem Formularaufruf generiert)*
-CURRENCY_ID- Transaktionswährung (EUR)
-SENDER_HOLDER- Name des Überweisenden
-SENDER_ACCOUNT_NUMBER- Kontonummer des Absenderkontos
-SENDER_ACCOUNT_NUMBER_XXX- Kontonummer: Letzte 3 Stellen durch XXX ersetzt
-SENDER_BANK_NAME- Bankname des Absenderkontos
-SENDER_BANK_BIC- BIC des Absenderkontos
-SENDER_IBAN- IBAN des Absenderkontos
-SENDER_COUNTRY_ID- Länder-ID des Absenderkontos (NL)
-SENDER_CITY- Stadt des Kontoinhabers
-SENDER_CITY_URLENCODE- Stadt des Kontoinhabers, URL encodiert
-RECIPIENT_HOLDER- Name des Empfängerkontos
-RECIPIENT_ACCOUNT_NUMBER- Kontonummer des Empfängers
-RECIPIENT_ACCOUNT_NUMBER_XXX- Kontonummer des Empfängers: Letzte 3 Stellen durch XXX ersetzt
-RECIPIENT_BANK_CODE- Bankleitzahl des Empfängerkontos
-RECIPIENT_BANK_NAME- Bankname des Empfängerkontos
-RECIPIENT_BANK_BIC- BIC des Empfängerkontos
-RECIPIENT_IBAN- IBAN des Empfängerkontos
-RECIPIENT_COUNTRY_ID- Länder-ID des Empfängerkontos (DE)
-AMOUNT- Rechnungsbetrag
-AMOUNT_INTEGER- Rechnungsbetrag als Integer Wert (ganzzahlig)
-REASON_1- Verwendungszweck Zeile 1
-REASON_2- Verwendungszweck Zeile 2
-DATE- Datum der Transaktion
-TIME- Uhrzeit der Transaktion
-TIMESTAMP- Timestamp der Transaktion
-SENDER_HOLDER_URLENCODE- Name des Überweisenden, URL encodiert
-SENDER_BANK_NAME_URLENCODE- Bankname des Überweisenden, URL encodiert
-RECIPIENT_HOLDER_URLENCODE- Name des Empfängers, URL encodiert
-RECIPIENT_BANK_NAME_URLENCODE- Bankname des Empfängers, URL encodiert
-REASON_1_URLENCODE- Verwendungszweck (Zeile 1), URL encodiert
-REASON_2_URLENCODE- Verwendungszweck (Zeile 2), URL encodiert
 
-ERROR_CODES- Fehlermeldungen (genaue Tabelle unter Rückgabeparameter -ERROR_CODES-)
-FEES- Kosten der Transaktion
-STATUS- Aktueller Status der Transaktion
-STATUS_MODIFIED- Zeitpunkt der Statusänderung
-STATUS_REASON- Grund der Statusänderung
-AMOUNT_REFUNDED- Zurück gebuchter Betrag**
-AMOUNT_REFUNDED_INTEGER- Zurück gebuchter Betrag im Format Integer**

Tabelle 6: Ersetzungsparameter die für Erfolgs-, Abbruch- und Benachrichtigungslink verwendet werden können

*   Kann nicht für den Abbruchlink verwenden werden.
** Bitte beachten Sie, dass dieser Parameter nur in einer HTTP-Benachrichtigung mit Zahlungsstatus verwendet werden kann und dort auch nur ersetzt wird, wenn Sie eine Benachrichtigung über eine stornierte Transaktion bekommen.

ACHTUNG:

Bitte beachten Sie die Reihenfolge bei den USER_VARIABLEN. Wenn Sie z.B. in -USER_VARIABLE_1- den Erfolgslink übergeben, welcher dann -USER_VARIABLE_0- als Ersetzungsparameter enthält, dann würde die Ersetzung nicht funktionieren.

5.5.1. Beispiel

Erfolgslink mit dynamischer URL (USER_VARIABLEN müssen beim Aufruf übergeben werden):

http://-USER_VARIABLE_0-/index.php?meineSession=-USER_VARIABLE_1-&transID=-TRANSACTION-

Diesen muss ein Händler dann auch in seinen Projekteinstellungen im SOFORT Anbietermenü als Erfolgslink eintragen.

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

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