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:
- Create a test project at SOFORT:
- Register as a merchant on our website https://sofort.com/register.
- Activate the product "SOFORT Ident" in the merchant menu (at "My account > Product activation")
- Create a new SOFORT Ident project (at "Projects > New Project > SOFORT Classic project > [SOFORT Ident] Create SOFORT Classic project").
- Configure your SOFORT Ident project (test project, return URL).
- 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").
- The next step is the integration in the shop:
- Integrate SOFORT Ident in your (shop) system.
- As soon as age verification of a customer is required, redirect the customer to our form for the required address data input.
- 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.
- 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:
- 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.