Merchant Login

API Documentation

Sofort Ident

1. Introduction to SOFORT Ident

SOFORT Ident allows you to verify the age of your customers. You redirect the customer to be verified to our input form. We are able to identify your customer by checking the address of the transferred address data and the login with the customer's bank. After successful identification, we will subsequently perform a Schufa query to verify the age of your customer. You will be informed about the result by the return of your customer to your (shop) system.

2. Integration steps

The following steps are basically required to integrate SOFORT Ident in your system. A detailed description of the individual steps is provided subsequently:

  1. Create a test project at SOFORT:
    1. Register as a merchant on our website https://sofort.com/register.
    2. Activate the product "SOFORT Ident" in the merchant menu (at "My account > Product activation")
    3. Create a new SOFORT Ident project (at "Projects > New Project > SOFORT Classic project > [SOFORT Ident] Create SOFORT Classic project").
    4. Configure your SOFORT Ident project (test project, return URL).
    5. After you have created and configured a project, you will receive a project and a notification password. (You may select the required hash algorithm after you have created the project at "Extended Settings > Passwords and hash algorithms").
  2. The next step is the integration in the shop:
    1. Integrate SOFORT Ident in your (shop) system.
    2. As soon as age verification of a customer is required, redirect the customer to our form for the required address data input.
    3. The customer processes age verification on our page and is subsequently redirected to the return page of your (shop) system which you have defined. You will be informed about the success/failure of the verification.
    4. Your (shop) system processes the result accordingly and releases for example contents or downloads.

3. Configuration of the SOFORT Ident project

After registration with SOFORT, a SOFORT Classic project for SOFORT Ident must be created.

Define the following settings:

Test mode: Activate the test mode during integration. Using the test data specified below, you can test your integration at no transaction costs (no Schufa queries are performed here).

Address: Enter your address here to be connected to the SOFORT Ident project.

Specific settings for SOFORT Ident:

  • Return URL: Enter a return URL here to which your customer is redirected after age verification or in case of abort by the customer. You may attach additional replacement parameters by HTTP GET which we replace by specific characteristics of a transaction (see table of replacement parameters). 
  • Automatic redirection: If box is checked, your customer will be redirected to the return URL after age verification without seeing an overview.
  • Skip first steps: If box is checked and if sort code (future BIC) and country of the account-holding bank is transferred, the customer will directly be redirected to the online banking login page.
  • Maximum number of failed verifications per user: Specifies how often a user can execute the verification per day.
  • Project password: Automatically generated, is required for the hash value calculation for the initial call and return
  • Notification password: Automatically generated, is required for the hash value calculation for the notification

Project check: If you check the box "Check project after creation", an employee will subsequently contact you and check the project settings.

Replacement parameters:

Replacement parameters Description
-USER_VARIABLE_0- Customer variable 0 transferred by you
-USER_VARIABLE_1- Customer variable 1
-USER_VARIABLE_2- Customer variable 2
-USER_VARIABLE_3- Customer variable 3
-USER_VARIABLE_4- Customer variable 4
-USER_VARIABLE_5- Customer variable 5
-USER_VARIABLE_0_URLENCODE- Customer variable 0 with URL-encoded special characters, e.g. "%20" for space
-USER_VARIABLE_1_URLENCODE- Customer variable 1 URL-encoded
-USER_VARIABLE_2_URLENCODE- Customer variable 2 URL-encoded
-USER_VARIABLE_3_URLENCODE- Customer variable 3 URL-encoded
-USER_VARIABLE_4_URLENCODE- Customer variable 4 URL-encoded
-USER_VARIABLE_5_URLENCODE- Customer variable 5 URL-encoded
-USER_VARIABLE_0_HASH_PASS- Hash value of the customer variable 0 concatenated with your project password (based on the hash algorithm you selected, e.g. hash("sha1", "123456" . "4-8-15-16-23-42"); )
-USER_VARIABLE_1_HASH_PASS- Hash of customer variable 1 with project password
-USER_VARIABLE_2_HASH_PASS- Hash of customer variable 2 with project password
-USER_VARIABLE_3_HASH_PASS- Hash of customer variable 3 with project password
-USER_VARIABLE_4_HASH_PASS- Hash of customer variable 4 with project password
-USER_VARIABLE_5_HASH_PASS- Hash of customer variable 5 with project password
-USER_ID- Your customer number at SOFORT
-PROJECT_ID- Your project ID
-TRANSACTION- Our transaction ID
-FIRSTNAME- First name of customer transferred by you
-FIRSTNAME_URLENCODE- First name of customer URL-encoded
-LASTNAME- Last name of customer transferred by you
-LASTNAME_URLENCODE- Last name of customer URL-encoded
-CITY- City of customer transferred by you
-CITY_URLENCODE- City of customer URL-encoded
-STREET- Street of customer transferred by you
-STREET_URLENCODE- Street of customer URL-encoded
-BIRTHDAY- Birth date of customer transferred by you
-ZIPCODE- Postal code of customer transferred by you
-ZIPCODE_URLENCODE- Postal code of customer URL-encoded
-BANK_CODE- Sort code transferred by you
-BANK_BIC- BIC of your customer transferred by you.
-BANK_NAME- Bank name of customer
-BANK_NAME_URLENCODE- Bank name URL-encoded
-ACCOUNT_COUNTRY_ID- Country of bank transferred by you
-LANGUAGE_ID- Language selected by customer

4. Integration of SOFORT Ident

To allow your customers the use of SOFORT Ident for age verification, you have to integrate SOFORT Ident in the process for which age verification of your customer is to be performed (e.g. before allowing access to content classified as not suitable for children under the age of 16 or 18 by the FSK Self-Regulatory Body for the legally regulated protection of minors). For this purpose, you have to redirect the customer to be verified from your website to our input form. Subsequently, we verify the transferred address (by the customer login in the customer's online banking). If successful, we perform a Schufa query for age verification. You will receive the result as a parameter in the next step when the customer is redirected to the return URL defined by you and you can proceed with the next steps in your (shop) system.

4.1. Communication with the interfaces for SOFORT Ident

Your customer is redirected from your (shop) system by a HTTP call (either by GET or POST) with name-value-pair (NVP) parameters. The principle of the responses is the same.

Direct communication with our interface by NVP-HTTP messages always follows the same pattern:

  • (API step 1) Redirection of customer to the Ident input form and transaction parameter transfer
  • (Customer step) If applicable, input/extension of the required data including age verification
  • (API step 2) Redirection of customer to the return URL including result transfer
  • (API step 3) Notification of result

Detailed information on the individual API calls and responses can be found in the section "Overview of parameters".

4.2. Redirection of customer to the Ident input form and transaction parameter transfer (API step 1)

Various parameters must be transferred to our API for the call. Some parameters are mandatory, some are optional. To make sure that this data cannot be changed on its way from your shop system to SOFORT, parts of the message are hashed with the project password and transmitted as a hash value for input verification. Details on the use of the individual parameters and on the hash value calculation are listed in the overview of parameters.

The form is called via the following URL:

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

Please implement the call only via this URL and transfer the required parameters (see section "Overview of parameters"); otherwise an error message will appear. You may transfer the parameters by GET or POST. For GET, add the variables to the link specified above; for POST, the parameters are transferred in a form in the body of the request.

If you do not transfer your customer's data (names, address, date of birth) with the redirection, the customer can fill in those data on the input form. If you block this possibility in the project settings of the merchant area (SOFORT backend) you need to transfer those parameters with the redirection.

Example of an interface call with a hash value and user_variable (POST method):

<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="Age verification" />
</form>

Example of an interface call as a link (GET method):

https://www.sofort.com/payment/agecheck?user_id=12345&project_id=54321&hash=1c110e4eb0f3ba0fce2ecdf37ffb8ea974ad15de

4.3. If applicable, input/extension of the required data including age verification (customer step)

In the next step the customer authentication takes place. In order to do that your customer logs in to the online banking and enters the name, date of birth, and address data.

If authentication has been successful, a Schufa query is performed with the related data. Based on a positive result returned by the Schufa, the age verification result will be determined.

4.4. Redirection of customer to the return URL including result transfer (API step 2)

If the Schufa result is positive, the age verification result is reported to your (shop) system by the redirection to the return URL in the HTTP POST parameter "agecheck_result". To make sure that this data cannot be changed on its way from your shop system to SOFORT, parts of the message will be hashed with the project password and transmitted as a hash value for input verification. The resulting hash value must be verified in your (shop) system before the age verification result is accepted. Details on the individual parameters and on the hash value calculation are listed in the overview of parameters.

NOTE: The hash calculation for the return differs from the hash calculation for our input form call (API step 1).

An example of a parameter transfer in the return might look as follows:

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

The returned customer data (names, address, date of birth) are equivalent to those of the input form that might be changed by your customer. If you have blocked to change those parameters on the input form in the project settings of the merchant area (SOFORT Backend) the returned data are the same as you initially transferred via the redirection to the input form.

Status messages

The return contains the result of the performed age verification in the parameter agecheck_result, which may have the values "valid", "invalid", and "user_abort". Detailed information on possible statuses and their descriptions can be found in the overview of parameters.

4.4.1. Error messages

In case the user and project ID have not been transferred correctly or not at all, the end customer is redirected to a SOFORT error page.

4.5. Notification of result (API step 3)

If you want to receive a notification on the successful completion of the age verification apart from the return (e.g. because the return to your (shop) system fails), you may configure a notification by email or HTTP. You can set up this notification in the SOFORT merchant menu at "My projects > Select project > Extended settings > Notifications". To add a notification, please click "Add new notification". The following notification types are available which are subsequently explained in detail:

  • Email
  • HTTP

4.5.1. Email

Select "Email". Activate this notification by checking the box "Activated". Then enter an email address and select the language in which the email is supposed to be written.

4.5.2. HTTP

The HTTP notification calls a programme in your (shop) system and confirms the successful age verification result. Every attempt to call the programme on your server is saved in your customer menu. Further information is provided there, e.g. the status code or the response (HTML page) of your (shop) system.

A notification will be successful if the status code of your web server is 200. The HTTP notification URL is called after age verification either as HTTP POST or HTTP GET.

An example of a notification URL could be as follows:

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

An example of a notification URL with additional parameters could be as follows:

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

After you have selected the method how our server is supposed to access your server, you can save the notification. Apart from your own parameters, we transfer all important identification information which you can evaluate with your programme. The overview of parameters contains a list of all parameters which have been automatically transferred in the HTTP notification.

To make sure that this data cannot be changed on its way from your (shop) system to SOFORT, a hash value is also calculated. If a notification password has been set in your project settings at SOFORT, this will be used to determine the hash value. Otherwise, the project password will be used. The resulting hash value must be verified in your (shop) system before the age verification result is accepted. Details on the individual parameters and on the hash value calculation are listed in the overview of parameters.

NOTE: The hash calculation for the notification differs from the hash calculation for our input form call (API step 1) as well as from the hash calculation for the return (API step 2).

The IP address which is used to send out the notification can be found under: https://www.sofort.com/payment/status/ipList.

5. Testing

To test the integration, please perform the age verification with one of the following accounts; different results may be returned depending on the account:

"valid" will be returned for:

  • account_country_id: DE
  • bank_code: 00000 (Instead of the test bank code a country specific test BIC will shortly be available: "SFRT{ISO-country code}20XXX", e.g. "SFRTDE20XXX" for Germany)
  • lastname: WARNECKE
  • firstname: HANS-GERD
  • birthday: 01/16/1953
  • street: ALTENBURGER STR. 10
  • zipcode: 38444
  • city: WOLFSBURG
  • address_country_id: DE

"invalid" will be returned for:

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

"user_abort" appears if the customer to be verified clicks the abort link on the input form and is redirected to the return URL.

If the name has not been found in the online banking portal of the customer, the customer will be logged off and requested to select an account the customer is known with.

6. Communication with the API (Application programming interface)

6.1. API call

To initialise age verification by SOFORT Ident, add an HTTP form on your page. This form will call the input form of SOFORT Ident when being submitted. When calling the form, you may transfer additional optional parameters apart from some mandatory fields.

The form is called via the following URL:

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

Mandatory parameters (*) are:

  • Customer number (Parameter: user_id)
  • Project number (Parameter: project_id)
  • Hash value (Parameter: hash; if input verification is active)

6.2. Description of parameters

The following table contains the parameters which can/must be transferred in the API calls and the response parameters of our interface.

6.3. (API step 1) Redirection of customer to the input form and transaction parameter transfer

The following table contains all possible parameters which you can transfer to our system when the customer is redirected to our input form. This may be done by HTTP POST or HTTP GET.

Parameter Type (length) Description
user_id (*) Integer Your customer number at SOFORT, e.g. "12345"
project_id (*) Integer Your project number of the SOFORT Ident project, e.g. "54321"
firstname String (255) First name of customer, e.g. "Max"
lastname String (255) Last name of customer, e.g. "Mustermann"
street String (255) Street and house number of customer, e.g. "Unter den Linden 77"
city String (255) City of customer, e.g. "Berlin"
zipcode String (10) Postal code of customer, e.g. "10117"
birthday Date Birth date of customer in the format YYYY-MM-DD, e.g. "1978-09-24"
address_country_id String (2) Two letter country code in the ISO-3166-1 format, e.g. "DE"
bank_code String (30) BIC (DEPRECATED: or sort code) of the customer's bank
account_country_id String (2) Two letter country code of the customer's bank in the ISO-3166-1 format, e.g. "DE"
user_variable_0 String (255) Customer variable (optional), e.g. "123456"
user_variable_1 String (255) Customer variable (optional)
user_variable_2 String (255) Customer variable (optional)
user_variable_3 String (255) Customer variable (optional)
user_variable_4 String (255) Customer variable (optional)
user_variable_5 String (255) Customer variable (optional)
hash (*) String (>=32) Hash to validate input parameters (input verification, see below)

Table 1: Possible transfer parameters for API step 1

Hashing       

To validate the input parameters, link all parameters in the order specified below and your password separated by a pipe character ("|", without quotation marks). If you do not need the customer variables, replace them by an empty string. The corresponding pipe character is still required.

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

The examples from the table above and the project password "4-8-15-16-23-42" result in the following string:

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

Use this string to create a hash value (e.g. by means of the PHP function hash()). Exemplary result with "SHA256" as a hash algorithm: 303af25fcce2f3ff1cde84b7a05e867450fe8918139cc70892ea60714c058131

NOTE!
The parameters are coded by default in UTF-8 for the hash creation.

Example for the hash calculation in PHP

The following example shows a hash calculation in PHP by means of SHA 256:

<?php
     $data = array( '12345', // user_id (mandatory)
                         '54321', // project_id (mandatory)
                         '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 (mandatory)
                       );
     $data_implode = implode('|', $data);
     $hash = hash('sha256', $data_implode);
?>

6.4. (API step 2) Return of customer including result transfer

The following table contains all parameters which are transferred to SOFORT by HTTP GET when the customer is redirected to the return URL defined by you. When the Schufa query could be performed successfully (parameter"agecheck_result"=valid), the parameter "age" is returned additionally. This parameter has the value of the age.

Parameter Type (length) Description
age Integer Age of customer, will only be returned if "agecheck_result" has the value "valid".
agecheck_result String (255) Result of age verification, may have the values "valid", "invalid", "user_abort".
firstname String (255) First name of customer, e.g. "Max" - contains the firstname that might have been changed by your customer
lastname String (255) Last name of customer, e.g. "Mustermann" - contains the lastname that might have been changed by your customer
city String (255) City of customer, e.g. "Berlin" - contains the city that might have been changed by your customer
street String (255) Street and house number of customer, e.g. "Unter den Linden 77" - contains the street and house number that might have been changed by your customer
zipcode String (10) Postal code of customer, e.g. "10117" - contains the zipcode that might have been changed by your customer
birthday Date Birth date of customer in the format YYYY-MM-DD, e.g. "1978-09-24" - contains the date of birth that might have been changed by your customer
address_country_id String (2) Two letter country code in the ISO-3166-1 format, e.g. "DE" - contains the country that might have been changed by your customer
bank_code String (30) BIC or sort code of the customer's bank, depends on the type of parameter that has also been transferred in API step 1 (BIC or sort code)
account_country_id String (2) Two letter country code of the customer's bank in the ISO-3166-1 format, e.g. "DE"
agecheck_hash String (255) Hash to validate the return parameters

Table 2: Return parameters of API step 2

To verify the return, you have to compare the value of "agecheck_hash" with the hash value which you may calculate according to the principle described above with the following sequence of parameters:

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

.

NOTE

Please be aware that user variables submitted in API step 1 will not be returned automatically via the return URL. If you need them (e.g. for agecheck_hash calculation) you will have to edit the return URL in the project settings and add the required parameters with the help of the available replacement parameters.

6.5. (API step 3) Notification of result

The following table contains all parameters which are transferred by SOFORT either as HTTP GET or HTTP POST in the notification to your (shop) system. SOFORT sends the notification only if the process has not been canceled by the consumer.

Parameter Type (length) Description
user_id Integer Your customer number at SOFORT, e.g. "12345"
project_id Integer Your project number of the SOFORT Ident project, e.g. "54321"
firstname String (255) First name of customer, e.g. "Max" - contains the firstname that might have been changed by your customer
lastname String (255) Last name of customer, e.g. "Mustermann" - contains the lastname that might have been changed by your customer
street String (255) Street and house number of customer, e.g. "Unter den Linden 77" - contains the street and house number that might have been changed by your customer
city String (255) City of customer, e.g. "Berlin" - contains the city that might have been changed by your customer
zipcode String (10) Postal code of customer, e.g. "10117" - contains the zipcode that might have been changed by your customer
birthday Date Birth date of customer in the format YYYY-MM-DD, e.g. "1978-09-24" - contains the date of birth that might have been changed by your customer
address_country_id String (2) Two letter country code in the ISO-3166-1 format, e.g. "DE" - contains the country that might have been changed by your customer
bank_code String (30) BIC or sort code of the customer's bank, depends on the type of parameter that has also been transferred in API step 1 (BIC or sort code)
account_country_id String (2) Two letter country code of the customer's bank in the ISO-3166-1 format, e.g. "DE"
user_variable_0 String (255) Customer variable, e.g. "123456"
user_variable_1 String (255) Customer variable
user_variable_2 String (255) Customer variable
user_variable_3 String (255) Customer variable
user_variable_4 String (255) Customer variable
user_variable_5 String (255) Customer variable
result String (255) Result of age verification, may have the values "valid", "invalid".
created Date Time stamp of age verification in the format "YYYY-MM-DD HH:MM:SS" (e.g. "2013-09-24 14:42:48")
hash String (255) Hash to validate the notification parameters

Table 3: Notification parameters of API step 3

To verify the notification, you have to compare the value of "hash" with the hash value which you may calculate according to the principle described above with the following sequence of parameters:

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

Please bear in mind that the project password (project_password) will be used to create a hash for the hash value of the notification if no notification password (notification_password) has been stored in the SOFORT merchant menu.

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.