Händler-Login

API Dokumentation

Sofort Ident

1. Einführung zu SOFORT Ident

Mit SOFORT Ident können Sie das Alter ihrer Kunden verifizieren lassen. Sie leiten Ihren zu prüfenden Kunden auf unser Eingabeformular weiter. Mit Hilfe einer Adressprüfung der übergebenen Adressdaten und einem Login bei der Bank des Kunden, können wir Ihren Kunden identifizieren. Bei erfolgreicher Identifikation stellen wir im Anschluss eine Schufa Anfrage und prüfen damit das Alter des Kunden. Das Ergebnis wird Ihnen durch die Rückleitung Ihres Kunden in Ihr (Shop-)System mitgeteilt.

2. Integrationsschritte

Um SOFORT Ident 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 "SOFORT Ident" (unter "Mein Konto > Produkt-Aktivierung")
    3. Erstellen Sie ein neues SOFORT Ident-Projekt (unter "Projekte > Neues Projekt > SOFORT-Classic-Projekt > [SOFORT Ident] SOFORT-Classic-Projekt anlegen").
    4. Konfigurieren Sie Ihr SOFORT Ident-Projekt (Testprojekt, Rücksprung-URL).
    5. In der Projektanlage und -konfiguration erhalten Sie ein Projekt- und ein Benachrichtigungspasswort. (Nach Projektanlage können Sie unter "Erweiterte Einstellungen > Passwörter und Hashalgorithmus" auch den notwendigen Hashalgorithmus wählen).
  2. Anschließend folgt die Shop Integration:
    1. Integrieren Sie SOFORT Ident in Ihr (Shop-)System.
    2. Sobald das Alter eines Kunden verifiziert werden soll, leiten Sie ihn an unser Eingabeformular mit den notwendigen Adressdaten weiter.
    3. Der Kunde wickelt die Altersverifizierung auf unserer Seite ab und wird anschließend auf die von Ihnen definierte Rücksprung-URL Ihres (Shop-)Systems zurückgeleitet. Dabei informieren wir Sie über Erfolg/Misserfolg der Verifikation.
    4. Ihr (Shop-)System verarbeitet das Ergebnis entsprechend und schaltet bspw. Inhalte bzw. Downloads frei.

3. Konfiguration des SOFORT Ident Projekts

Wenn Sie sich bei SOFORT registriert haben folgt die Anlage eines SOFORT Classic Projekts für SOFORT Ident.

Definieren Sie dort folgende Einstellungen:

Testmodus: aktivieren Sie den Testmodus während der Integration. Mit den unten angegebenen Testdaten können Sie Ihre Integration testen, ohne dass Ihnen Transaktionskosten entstehen (hiermit werden keine Schufa Anfragen durchgeführt).

Adresse: Geben Sie hier Ihre Adresse ein, die mit dem SOFORT Ident Projekt verknüpft sein soll.

Spezielle Einstellungen für SOFORT Ident:

  • Rücksprung-URL: Geben Sie hier eine URL an, auf die wir Ihren Kunden nach der Altersverifizierung oder bei Abbruch durch den Kunden zurückleiten. Hierbei können Sie per HTTP GET weitere Ersetzungsparameter anhängen, die von uns mit den konkreten Ausprägungen einer Transaktion ersetzt werden (siehe Tabelle Ersetzungsparameter). 
  • Automatische Weiterleitung: Sofern angehakt, wird Ihr Kunde ohne Anzeige einer Zusammenfassung nach der Altersverifikation zurück auf die Rücksprung-URL geleitet.
  • Erste Schritte überspringen: Sofern angehakt sowie Bankleitzahl (künftig BIC) und Land der kontoführenden Bank übergeben wurde, wird der Kunde direkt auf die Seite für den Online-Banking Login geleitet.
  • Max. fehlgeschlagene Verifikationen pro Nutzer: Gibt die Anzahl an, wie häufig ein Nutzer pro Tag die Verifizierung durchführen darf.
  • Projekt-Passwort: automatisch generiert; wird benötigt für die Hashwert-Berechnung beim initialen Aufruf und bei der Rückleitung
  • Benachrichtigungspasswort: automatisch generiert; wird benötigt für die Hashwert-Berechnung bei der Benachrichtigung

Prüfung des Projektes: Wenn Sie den Haken bei "Projekt nach Anlage prüfen" anhaken, wird sich im Nachgang ein Mitarbeiter mit Ihnen in Verbindung setzen und die Projekteinstellung prüfen.

Nach Erstellung des Projekts sollten Sie anschließend noch eine Benachrichtigungs-URL definieren, an die wir eine Benachrichtigung über (Miss-)Erfolg einer Altersverifikation schicken. Dies kann u.a. dann sinnvoll sein, wenn der Kunde eine Altersverifikation durchgeführt hat, aber nicht zurück in Ihr (Shop-)System gelangt. Wählen Sie dazu in Ihrem Projekt unter "Erweiterte Einstellungen > Benachrichtigungen> Neue Benachrichtigung anlegen". Richten Sie unter dem Reiter "HTTP" eine Benachrichtigungs-URL ein, die unsere Schnittstelle nach der Altersverifikation aufrufen kann, um das Ergebnis der Altersverifikation zu übergeben. Dies kann wahlweise per GET oder POST geschehen. Auch hier können Sie Ersetzungsparameter (s.u.) noch mit übergeben.

Ersetzungsparameter:

Ersetzungsparameter Beschreibung
-USER_VARIABLE_0- Von Ihnen übergebene Kundenvariable 0
-USER_VARIABLE_1- Kundenvariable 1
-USER_VARIABLE_2- Kundenvariable 2
-USER_VARIABLE_3- Kundenvariable 3
-USER_VARIABLE_4- Kundenvariable 4
-USER_VARIABLE_5- Kundenvariable 5
-USER_VARIABLE_0_URLENCODE- Kundenvariable 0 mit URL-enkodierten Sonderzeichen, z.B. "%20" für Leerzeichen
-USER_VARIABLE_1_URLENCODE- Kundenvariable 1 URL-enkodiert
-USER_VARIABLE_2_URLENCODE- Kundenvariable 2 URL-enkodiert
-USER_VARIABLE_3_URLENCODE- Kundenvariable 3 URL-enkodiert
-USER_VARIABLE_4_URLENCODE- Kundenvariable 4 URL-enkodiert
-USER_VARIABLE_5_URLENCODE- Kundenvariable 5 URL-enkodiert
-USER_VARIABLE_0_HASH_PASS- Hashwert der mit Ihrem Projektpasswort konkatenierten Kundenvariable 0 (auf Basis des von Ihnen gewählten Hashalgorithmus, z.B. hash("sha1", "123456" . "4-8-15-16-23-42"); )
-USER_VARIABLE_1_HASH_PASS- Hash von Kundenvariable 1 mit Projektpasswort
-USER_VARIABLE_2_HASH_PASS- Hash von Kundenvariable 2 mit Projektpasswort
-USER_VARIABLE_3_HASH_PASS- Hash von Kundenvariable 3 mit Projektpasswort
-USER_VARIABLE_4_HASH_PASS- Hash von Kundenvariable 4 mit Projektpasswort
-USER_VARIABLE_5_HASH_PASS- Hash von Kundenvariable 5 mit Projektpasswort
-USER_ID- Ihre Kundennummer bei SOFORT
-PROJECT_ID- Ihre Projekt-ID
-TRANSACTION- Unsere Transaktions-ID
-FIRSTNAME- Von Ihnen übergebener Kunden Vorname
-FIRSTNAME_URLENCODE- Kunden Vorname URL-enkodiert
-LASTNAME- Von Ihnen übergebener Kunden Nachname
-LASTNAME_URLENCODE- Kunden Nachname URL-enkodiert
-CITY- Von Ihnen übergebene Kunden Wohnort
-CITY_URLENCODE- Kunden Wohnort URL-enkodiert
-STREET- Von Ihnen übergebene Kunden Straße
-STREET_URLENCODE- Kunden Straße URL-enkodiert
-BIRTHDAY- Von Ihnen übergebener Kunden Geburtstag
-ZIPCODE- Von Ihnen übergebene Kunden PLZ
-ZIPCODE_URLENCODE- Kunden PLZ URL-enkodiert
-BANK_CODE- Von Ihnen übergebene Kunden Bankleitzahl
-BANK_BIC- Von Ihnen übergebene Kunden BIC.
-BANK_NAME- Bankname der Bank des Kunden
-BANK_NAME_URLENCODE- Bankname URL-enkodiert
-ACCOUNT_COUNTRY_ID- Von Ihnen übergebene Land der Bankfiliale
-LANGUAGE_ID- Gewählte Sprache des Kunden

4. Integration von SOFORT Ident

Damit Ihre Kunden SOFORT Ident zur Altersverifikation nutzen können, müssen Sie SOFORT Ident in den Prozess integrieren, bei dem eine Überprüfung des Alters Ihres Kunden durchgeführt werden soll (bspw. bevor FSK 16 bzw. FSK 18 klassifizierte Inhalte zugegriffen werden können). Dabei müssen Sie den Kunden, dessen Alter geprüft werden soll, von Ihrer Webseite auf unser Eingabeformular weiterleiten. Wir prüfen anschließend die dabei übergebene Adresse (entweder über einen Login des Kunden in seinem Online-Banking. Sofern die Adresse erfolgreich geprüft wurde, führen wir zur Altersprüfung eine Schufa Anfrage durch. Das Ergebnis erhalten Sie im nächsten Schritt mit der Rückleitung des Kunden auf die von Ihnen definierte Rücksprung-URL als Parameter zurück und können weitere Schritte in Ihrem (Shop-)System vornehmen.

4.1. Kommunikation mit den Schnittstellen für SOFORT Ident

Die Weiterleitung Ihres Kunden aus Ihrem (Shop-)System heraus erfolgt 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 SOFORT Ident Eingabeformular und Übergabe der Parameter
  • (Kundenschritt) ggf. Eingabe/Erweiterung der benötigten Daten inkl. der Verifikation des Alters.
  • (API-Schritt 2) Rückleitung des Kunden auf die Rückleitung-URL inkl. Übergabe des Ergebnisses.
  • (API-Schritt 3) Benachrichtigung über Ergebnis

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

4.2. Weiterleitung des Kunden auf das SOFORT Ident Eingabeformular und Übergabe der Parameter (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 Ihrem (Shop-)system und SOFORT nicht geändert werden, werden Teile der Nachricht zusammen mit dem Projektpasswort gehasht und als Hashwert zur Inputprüfung 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/agecheck

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.

Falls Sie die Daten Ihres Kunden (Namen, Adresse, Geburtsdatum) nicht mit der Weiterleitung übergeben, können diese auch auf dem Eingabeformular durch Ihren Kunden eingegeben werden. Sofern Sie diese Möglichkeit in den Projekteinstellungen im Anbietermenü (SOFORT Backend) sperren, müssen Sie die Daten Ihres Kunden im ersten Aufruf übergeben.

Beispielhafter Schnittstellenaufruf mit Hashwert und user_variable (Methode POST):

<form method="post" action="https://www.sofort.com/payment/agecheck">
    <input type="hidden" name="user_id" value="12345" />
    <input type="hidden" name="project_id" value="54321" />
    <input type="hidden" name="hash" value="1c110e4eb0f3ba0fce2ecdf37ffb8ea974ad15de" />
    <input type="submit" value="Altersverifizierung" />
</form>

Beispielhafter Schnittstellenaufruf als Link (Methode GET):

<a href="https://www.sofort.com/payment/agecheck?user_id=12345&project_id=54321&hash=1c110e4eb0f3ba0fce2ecdf37ffb8ea974ad15de">https://www.sofort.com/payment/agecheck?user_id=12345&project_id=54321&hash=1c110e4eb0f3ba0fce2ecdf37ffb8ea974ad15de</a>

4.3. ggf. Eingabe/Erweiterung der benötigten Daten inkl. der Verifikation des Alters (Kundenschritt)

Im nächsten Schritt erfolgt die Authentifizierung des Kunden.

Dazu logt sich Ihr Kunde in seinem Online-Banking ein und ergänzt Namen, Geburtsdatum und seine Adressdaten bzw. gibt diese ein.

Ist die Authentifizierung erfolgreich, wird eine Anfrage mit den erhobenen Daten an die Schufa gestellt. Auf Basis der von der Schufa zurückgemeldeten Übereinstimmung ermitteln wir das Ergebnis der Altersverifikation.

4.4. Rückleitung des Kunden auf die Rückleitung-URL inkl. Übergabe des Ergebnisses (API-Schritt 2)

Sofern das Ergebnis der Rückmeldung der Schufa positiv ausfällt wird mit der Rückleitung auf die Rücksprung-URL im HTTP Post Parameter "agecheck_result" das Ergebnis der Verifizierung Ihrem (Shop-)System mitgeteilt. Damit sichergestellt werden kann, dass diese Daten auf dem Weg zwischen SOFORT und Ihrem (Shop-)System nicht geändert werden, sind Teile der Nachricht zusammen mit dem Projekt-Passwort gehasht und als Hashwert mit übertragen. Dieser Hashwert ist in Ihrem (Shop-)System zu prüfen, bevor das Ergebnis der Altersverifizierung übernommen werden darf. Details zu den einzelnen Parametern sowie der Hashwert Berechnung finden Sie in der Parameterübersicht.

ACHTUNG: Die Hash-Berechnung für die Rückleitung unterscheidet sich von der Hash-Berechnung beim Aufruf unseres Eingabeformulars (API-Schritt 1).

Eine beispielhafte Parameterübergabe bei Rückleitung könnte so aussehen:

user_id=12345&bank_code=00000&age=60&agecheck_result=valid&firstname=Hans-
Gerd&lastname=Warnecke&city=Wolfsburg&street=Altenburger%20Str.%2010&
zipcode=38444&birthday=1953-01-16&address_country_id=DE&bank_code=00000&
account_country_id=DE&agecheck_hash=b8a2b0029e4616fe242bd050f626e3c6878d2971

Die dabei zurückgegebenen Kundendaten (Namen, Adresse, Geburtsdatum) entsprechen den auf dem Eingabeformular evtl. durch Ihren Kunden korrigierten Daten. Sollten Sie die Änderung dieser Parameter auf dem Eingabeformular in den Projekteinstellungen im SOFORT Anbietermenü (SOFORT Backend) gesperrt haben, entsprechen die zurückgegebenen Daten denen der Weiterleitung auf das Eingabeformular.

Statusmeldungen

In der Rückleitung finden Sie das Ergebnis der durchgeführten Altersverifizierung im Parameter agecheck_result, der die Werte "valid", "invalid" und "user_abort" annehmen kann. Weitere Detailinformationen zu möglichen Status und deren Beschreibung finden Sie in der Parameterübersicht.

4.4.1. Fehlermeldungen

Wurden User- und Projekt-ID falsch oder gar nicht übergeben, leiten wir den Endkunden auf eine Fehlerseite von uns weiter.

4.5. Benachrichtigung über Ergebnis (API-Schritt 3)

Sofern Sie über die Rückleitung hinaus über den erfolgreichen Abschluss der Altersverifizierung benachrichtigt werden wollen (bspw. weil eine Rückleitung in Ihr (Shop-)System fehlschlägt), können Sie eine Benachrichtigung per E-Mail oder HTTP konfigurieren. Im SOFORT Anbietermenü können Sie dies unter "Meine Projekte > Projekt auswählen > Erweiterte Einstellungen > Benachrichtigungen" einrichten. Um eine Benachrichtigung anzulegen, klicken Sie bitte auf "Neue Benachrichtigung anlegen". Es stehen Ihnen folgende Benachrichtigungs-Arten zur Verfügung, die im Anschluss detailliert erklärt werden:

  • E-Mail
  • HTTP
4.5.1. E-Mail

Wählen Sie "Email" aus. Aktivieren Sie diese Benachrichtigung, in dem Sie die Checkbox "Aktiviert" durch einen Haken setzen. Geben Sie dann die E-Mail Adresse ein und wählen Sie die Sprache, in der die E-Mail erstellt werden soll.

4.5.2. HTTP

Die HTTP-Benachrichtigung ruft ein Programm auf Ihrem (Shop-)System auf und bestätigt die erfolgreiche Altersverifizierung. Jeder Versuch das Programm auf Ihrem Server aufzurufen, wird in Ihrem Kundenmenü gespeichert. Sie finden dort weitere Informationen, zum Beispiel den Status-Code oder die Antwort (HTML-Seite) Ihres (Shop-)Systems.

Eine Benachrichtigung ist dann erfolgreich, wenn der Status-Code Ihres Webservers 200 beträgt. Die HTTP-Benachrichtigungs-URL wird nach der Altersverifikation entweder als HTTP POST oder HTTP GET aufgerufen.

Eine Beispiel Benachrichtigungs-URL könnte wie folgt aussehen:

https://www.mein-shop.de/agecheck_notification.php

Eine Beispiel Benachrichtigungs-URL mit zusätzlichen Parametern könnte wie folgt aussehen:

https://www.meinshop.de/agecheck_notification.php?module=myshop25&action=agecheck

Nachdem Sie die Methode gewählt haben, wie unser Server auf Ihren Server zugreifen soll, können Sie die Benachrichtigung abspeichern. Neben Ihren eigenen Parametern übergeben wir alle wichtigen Informationen zur Identifikation, die Sie mit Ihrem Programm auswerten können. In der Parameterübersicht finden Sie eine Liste der automatisch übergebenen Parameter in der HTTP-Benachrichtigung.

Damit sichergestellt werden kann, dass diese Daten auf dem Weg zwischen SOFORT und Ihrem (Shop-)System nicht geändert werden, findet auch hier eine Hashwert Berechnung statt. Sofern in Ihren Projekteinstellungen bei SOFORT ein Benachrichtigungspasswort gesetzt ist, wird dieses für die Hashwert Ermittlung verwendet. Andernfalls verwenden wir das Projektpasswort. Der resultierende Hashwert ist in Ihrem (Shop-)System zu prüfen, bevor das Ergebnis der Altersverifizierung übernommen 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 von der Hash-Berechnung beim Aufruf unseres Eingabeformulars (API-Schritt 1) sowie von der Berechnung bei Rückleitung (API-Schritt 2).

Die IP-Adresse von der die Benachrichtigung versendet wird finden Sie unter: https://www.sofort.com/payment/status/ipList.

5. Testen

Um Ihre Integration zu testen, führen Sie bitte eine Altersverifizierung mit einem der folgenden Konten durch, wobei abhängig vom Konto verschiedene Ergebnisse zurückgegeben werden:

"valid" wird zurückgegeben bei:

  • account_country_id: DE
  • bank_code: 00000 (In Kürze können Sie anstatt der Test-BLZ auch eine länderspezifische Test-BIC übergeben: "SFRT{ISO-Länderkürzel}20XXX", z.B. für Deutschland "SFRTDE20XXX")
  • lastname: WARNECKE
  • firstname: HANS-GERD
  • birthday: 16.01.1953
  • street: ALTENBURGER STR. 10
  • zipcode: 38444
  • city: WOLFSBURG
  • address_country_id: DE

"invalid" wird zurückgegeben bei:

  • lastname: Mustermann
  • firstname: Petra
  • lastname: Mustermann
  • firstname: Max

"user_abort" tritt auf, wenn der zu Überprüfende den Vorgang auf dem Eingabeformular den Abbruchlink klickt und auf die Rücksprung-URL zurückgeleitet wird.

Falls der Name bei dem Online-Banking-Portal des Kunden nicht gefunden wurde, wird dieser abgemeldet und gebeten ein Konto zu wählen mit dem der Kunde bekannt ist.

6. Kommunikation mit der API (Application programming interface)

6.1. Aufruf der Schnittstelle

Um eine Altersverifizierung über SOFORT Ident zu starten, fügen Sie auf Ihrer Seite ein HTML-Formular ein. Dieses Formular ruft beim Abschicken das Eingabeformular von SOFORT Ident auf. Beim Aufruf des Formulars können Sie neben einigen Pflichtfeldern auch weitere optionale Parameter an uns übergeben.

Der Formular-Aufruf erfolgt an folgende URL:

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

Pflicht-Parameter (*) sind:

  • Kundennummer (Parameter: user_id)
  • Projektnummer (Parameter: project_id)
  • Hashwert (Parameter: hash; falls Input-Prüfung aktiviert)
6.2. Parameterbeschreibung

Im Folgenden finden Sie die Parameter, die Sie in den API Aufrufen übergeben können/müssen und mit denen unsere Schnittstelle Antwortet.

6.3. (API-Schritt 1) Weiterleitung des Kunden auf das Eingabeformular und Übergabe der Parameter

Die folgende Tabelle enthält alle möglichen Parameter, die Sie in der Weiterleitung des Kunden auf unser Eingabeformular an unser System übergeben können. Dies geschieht wahlweise per HTTP POST oder HTTP GET.

Parameter Typ (Länge) Beschreibung
user_id (*) Integer Ihre Kundennummer bei SOFORT, z.B. "12345"
project_id (*) Integer Ihre Projektnummer des SOFORT Ident Projekts, z.B. "54321"
firstname String (255) Vorname des Kunden, z.B. "Max"
lastname String (255) Nachname des Kunden, z.B. "Mustermann"
street String (255) Straße und Hausnummer des Kunden, z.B. "Unter den Linden 77"
city String (255) Wohnort des Kunden, z.B. "Berlin"
zipcode String (10) PLZ des Kunden, z.B. "10117"
birthday Date Geburtsdatum des Kunden im Format YYYY-MM-DD, z.B. "1978-09-24"
address_country_id String (2) 2-stellige Abkürzung des Landes des Kunden im ISO-3166-1 Format, z.B. "DE"
bank_code String (30) BIC (DEPRECATED: oder Bankleitzahl) der Bankfiliale des Kunden
account_country_id String (2) 2-stellige Abkürzung des Landes der Bankfiliale des Kunden im ISO-3166-1 Format, z.B. "DE"
user_variable_0 String (255) Kundenvariable (optional), z.B. "123456"
user_variable_1 String (255) Kundenvariable (optional)
user_variable_2 String (255) Kundenvariable (optional)
user_variable_3 String (255) Kundenvariable (optional)
user_variable_4 String (255) Kundenvariable (optional)
user_variable_5 String (255) Kundenvariable (optional)
hash (*) String (>=32) Hash zur Validierung der Eingabeparameter (Inputprüfung, s.u.)

Tabelle 1: mögliche Übergabeparameter für API-Schritt 1

Hashbildung

Zur Validierung der Eingabeparameter hängen Sie alle Parameter in der u.g. Reihenfolge und Ihr Passwort getrennt durch ein Pipe-Zeichen ("|", ohne Anführungsstriche) aneinander. Wenn Sie die
Kundenvariablen nicht benötigen, ersetzen Sie sie durch einen Leerstring. Das korrespondierende Pipe-Zeichen wird trotzdem benötigt.

user_id|project_id|firstname|lastname|street|city|zipcode|birthday|
address_country_id|bank_code|account_country_id|user_variable_0|
user_variable_1|user_variable_2|user_variable_3|user_variable_4|
user_variable_5|project_password

Mit den Beispielen aus der obigen Tabelle und dem Projekt-Passwort "4-8-15-16-23-42" ergibt sich folgende Zeichenkette:

12345|54321|Max|Mustermann|Unter den Linden 77|Berlin|10117|
1978-09-24|DE||DE|123456||||||4-8-15-16-23-42

Bilden Sie aus dieser Zeichenkette dann den Hashwert (z.B. mittels der PHP-Funktion hash()). Beispiel-Ergebnis mit "SHA256" als Hashalgorithmus: 303af25fcce2f3ff1cde84b7a05e867450fe8918139cc70892ea60714c058131

ACHTUNG!
Die Parameter werden von uns standardmäßig für die Hashberechnung in UTF-8 kodiert.

Beispiel für die Hashberechnung in PHP

Das folgende Beispiel zeigt eine Hashberechnung in PHP mittels SHA256:

<?php
     $data = array( '12345', // user_id (Pflicht)
                         '54321', // project_id (Pflicht)
                         'Max', // firstname
                         'Mustermann', // lastname
                         'Unter den Linden 77', // street
                         'Berlin', // city
                         '10117', // zipcode
                         '1978-09-24', // birthday (Format: 1970-06-28)
                         'DE', // address_country_id
                         '', // bank_code
                         'DE', // account_country_id
                         '123456', // user_variable_0
                         '', // user_variable_1
                         '', // user_variable_2
                         '', // user_variable_3
                         '', // user_variable_4
                         '', // user_variable_5
                         '4-8-15-16-23-42' // project_password (Pflicht)
                       );
     $data_implode = implode('|', $data);
     $hash = hash('sha256', $data_implode);
?>

6.4. (API-Schritt 2) Rückleitung des Kunden inkl. Übergabe des Ergebnisses

Die folgende Tabelle enthält alle Parameter, die SOFORT in der Rückleitung des Kunden auf die von Ihnen festgelegte Rücksprung-URL per HTTP GET übergeben werden. Wenn die Schufa Anfrage erfolgreich durchgeführt werden konnte (Parameter
"agecheck_result"=valid), wird zusätzlich der Parameter "age" zurückgegeben. Dieser nimmt den Wert des Alters an. Weitere Parameter können Sie im Anbietermenü bei der Definition der Rücksprung-URL als Ersetzungsparameter definieren.

Parameter Typ (Länge) Beschreibung
age Integer Alter des Kunden (wird nur zurückgegeben, falls "agecheck_result" den Wert "valid" annimmt.
agecheck_result String (255) Ergebnis der Altersverifizierung, kann die Werte "valid", "invalid", "user_abort" annehmen.
firstname String (255) Vorname des Kunden, z.B. "Max" - beinhaltet den Vornamen, der durch den Kunden ggf. korrigiert wurde
lastname String (255) Nachname des Kunden, z.B. "Mustermann" - beinhaltet den Nachnamen, der durch den Kunden ggf. korrigiert wurde
city String (255) Wohnort des Kunden, z.B. "Berlin" - beinhaltet den Ort, der durch den Kunden ggf. korrigiert wurde
street String (255) Straße und Hausnummer des Kunden, z.B. "Unter den Linden 77" - beinhaltet die Straße und Hausnummer, die durch den Kunden ggf. korrigiert wurden
zipcode String (10) PLZ des Kunden, z.B. "10117" - beinhaltet die PLZ, die durch den Kunden ggf. korrigiert wurde
birthday Date Geburtsdatum des Kunden im Format YYYY-MM-DD, z.B. "1978-09-24" - beinhaltet das Geburtsdatum, das durch den Kunden ggf. korrigiert wurde
address_country_id String (2) 2-stellige Abkürzung des Landes des Kunden im ISO-3166-1 Format, z.B. "DE" - beinhaltet das Land, das durch den Kunden ggf. korrigiert wurde
bank_code String (30) BIC oder Bankleitzahl der Bankfiliale des Kunden, je nach dem, welcher Typ auch im API-Schritt 1 übergeben wurde (BIC oder BLZ)
account_country_id String (2) 2-stellige Abkürzung des Landes der Bankfiliale des Kunden im ISO-3166-1 Format, z.B. "DE"
agecheck_hash String (255) Hash zur Validierung der Rückgabeparameter

Tabelle 2: Rückgabeparameter des API-Schritt 2

Zur Überprüfung der Rückgabe müssen Sie den Wert von "agecheck_hash" mit dem Hashwert vergleichen, den Sie nach dem oben beschriebenen Prinzip mit folgender Parameterreihenfolge berechnen können:

user_id|project_id|firstname|lastname|street|city|zipcode|birthday|
address_country_id|bank_code|account_country_id|user_variable_0|
user_variable_1|user_variable_2|user_variable_3|user_variable_4|
user_variable_5|agecheck_result|project_password

-

ACHTUNG!

Sollten Sie im API-Schritt 1 Kundenvariablen übergeben haben, werden diese nicht automatisch an die im Projekt festgelegte Rücksprung-URL angehängt. Passen sie die Rücksprung-URL in den Projekteinstellungen mit Hilfe der zur Verfügung stehenden Ersetzungsvariablen an, wenn Sie die übergebenen Kundenvariablen an dieser Stelle zurückerhalten möchten

6.5. (API-Schritt 3) Benachrichtigung über Ergebnis

Die folgende Tabelle enthält alle Parameter, die SOFORT in der Benachrichtigung an Ihr (Shop-)System wahlweise als HTTP GET oder HTTP POST übergibt. Die Benachrichtigung wird nur verschickt, wenn der Überprüfungsprozess bei der SOFORT nicht vorzeitig abgebrochen wurde.

Parameter Typ (Länge) Beschreibung
user_id Integer Ihre Kundennummer bei SOFORT, z.B. "12345"
project_id Integer Ihre Projektnummer des SOFORT Ident Projekts, z.B. "54321"
firstname String (255) Vorname des Kunden, z.B. "Max" - beinhaltet den Vornamen, der durch den Kunden ggf. korrigiert wurde
lastname String (255) Nachname des Kunden, z.B. "Mustermann" - beinhaltet den Nachnamen, der durch den Kunden ggf. korrigiert wurde
street String (255) Straße und Hausnummer des Kunden, z.B. "Unter den Linden 77" - beinhaltet die Straße und Hausnummer, die durch den Kunden ggf. korrigiert wurden
city String (255) Wohnort des Kunden, z.B. "Berlin" - beinhaltet den Ort, der durch den Kunden ggf. korrigiert wurde
zipcode String (10) PLZ des Kunden, z.B. "10117" - beinhaltet die PLZ, die durch den Kunden ggf. korrigiert wurde
birthday Date Geburtsdatum des Kunden im Format YYYY-MM-DD, z.B. "1978-09-24" - beinhaltet das Geburtsdatum, das durch den Kunden ggf. korrigiert wurde
address_country_id String (2) 2-stellige Abkürzung des Landes des Kunden im ISO-3166-1 Format, z.B. "DE" - beinhaltet das Land, das durch den Kunden ggf. korrigiert wurde
bank_code String (30) BIC oder Bankleitzahl der Bankfiliale des Kunden, je nach dem, welcher Typ auch im API-Schritt 1 übergeben wurde (BIC oder BLZ)
account_country_id String (2) 2-stellige Abkürzung des Landes der Bankfiliale des Kunden im ISO-3166-1 Format, z.B. "DE"
user_variable_0 String (255) Kundenvariable, z.B. "123456"
user_variable_1 String (255) Kundenvariable
user_variable_2 String (255) Kundenvariable
user_variable_3 String (255) Kundenvariable
user_variable_4 String (255) Kundenvariable
user_variable_5 String (255) Kundenvariable
result String (255) Ergebnis der Altersverifizierung, kann die Werte "valid", "invalid" annehmen.
created Date Zeitstempel der Altersverifizierung im Format "YYYY-MM-DD HH:MM:SS" (z.B. "2013-09-24 14:42:48")
hash String (255) Hash zur Validierung der Benachrichtigungsparameter

Tabelle 3: Benachrichtigungsparameter des API-Schritt 3

Zur Überprüfung der Benachrichtigung müssen Sie den Wert von "hash" mit dem Hashwert vergleichen, den Sie nach dem oben beschriebenen Prinzip mit folgender Parameterreihenfolge berechnen können:

user_id|project_id|firstname|lastname|street|city|zipcode|birthday|
address_country_id|bank_code|account_country_id|user_variable_0|
user_variable_1|user_variable_2|user_variable_3|user_variable_4|
user_variable_5|result|notification_password

Bitte beachten Sie, dass sofern kein Benachrichtigungspasswort (notification_password) im SOFORT Anbietermenü hinterlegt ist das Projektpasswort (project_password) zur Hashgenerierung für den Hashwert der Benachrichtigung herangezogen wird.

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

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