Merchant Login

API Documentation

SOFORT Paycode

1. Introduction to SOFORT Paycode

The SOFORT Paycode function allows you to generate a 10 digit code which the customer can use to make a payment by SOFORT at a later point of time within the period of validity.

A SOFORT transaction with a paycode consists of the following steps:

  1. Generate a paycode. You can either generate a paycode in your merchant menu of SOFORT or via the HTTP-XML interface. (See Section 2: Item Paycode in the merchant menu of SOFORT or Section 3: Paycode generation via HTTP-XML interface)
  2. Share paycode with your customer.
  3. Your customer can enter the paycode at https://www.sofort.com/paycode/ to carry out the payment.
  4. Depending on the project configuration, you will either receive a notification or you can see in the merchant menu that the transfer has been listed in your customer's online banking.

2. Integration steps

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

  1. Register as a merchant on our website https://sofort.com/register.
  2. Activate the product "SOFORT Banking Paycode“ (at "My account" → "Product activation")
  3. Create a new SOFORT Gateway Project.
  4. Configure your SOFORT Banking Paycode project; select "SOFORT Banking Paycode" as a payment method.
  5. After you have created and configured the new project, you will receive an API key (which can be found in the left menu at "Additional services" → "API key".
  6. If you want to automatically generate paycode via the SOFORT interface and to automatically process the notifications on a successful transaction in your shop, the next step is the integration in your shop:
    1. Integrate the generation of paycodes in your shop
    2. Define or create a success/abort page to which your customer will be redirected after a successful/failed SOFORT Banking transaction.
    3. Configure your shop to receive notifications and initiate status detail requests.
Ablauf SÜ Paycode Kommunikation

Important general information

  • The used standard coding for all parameters is UTF-8.
  • The reasons for "SOFORT Banking" are adjusted by SOFORT in certain cases. Adjustments refer to the parameters <reason> that are subelements of the container <reasons>. Text containing "sofortbanking", "sofort-banking", "Payment Network AG", "directebanking" and combinations thereof e.g. hyphenated "direct-ebanking" (upper and lower case is not significant) will be deleted from the field reason. The domains sofortüberweisung.de, sofortueberweisung.de, sofort-überweisung.de, sofort-ueberweisung.de, directebanking.com and direct-ebanking.com will also be removed.
  • In case line 1 of the field reason is empty after deleting, it will be filled with the contents of line 2. In case both lines are empty, the recipient's name will be written in line 1.

 

3. Menu item Paycode in the SOFORT merchant menu

3.1. Paycode generation

Paycodes can be easily generated in the SOFORT merchant menu.

  1. To generate a paycode in your merchant menu, log in with your user data at https://www.sofort.com/payment/users/login.
  2. Go to "My projects" (left navigation) and select a project to generate paycodes for. Then open the "Paycodes" tab.
  3. You can determine the desired criteria for your paycode here. The following settings are possible:
    Project
    Choose the project which you want to use for this paycode.
    Validity
    Expiration date - Enter the start and expiration date of your paycode here. If the paycode used by the customer has expired, an error message will appear.
    Number of uses (needs to be activated by SOFORT)
    Enter the number of times a paycode can be used
    Payment data
    Amount - Enter the desired amount.
    Currency - Select the desired currency.
    Reason - Enter the desired reason. Please pay attention to the details given in the Section "Integration steps: Important general information".
    Settings
    Success link - This link redirects your customer back to your shop after a successful transaction.
    Abort link - This link redirects your customer back to your shop after a failed transaction (cancelled by customer or SOFORT not possible).
    Customer variables
    You can transfer own variables to be used e.g. for internal allocation. Detailed information on customer variables can be found in our SOFORT manual.
    Generate paycode
    Finally, you press the button "Generate paycode" at the bottom of the page. The code will be displayed at the top of the page including the URL to enter the paycode.
  4. Send the paycode to your customer together with the URL https://www.sofort.com/paycode/. Additionally, you can send the paycode by email or sms via the SOFORT merchant menu (additional costs apply for text messages).
  5. Depending on the project configuration, you will either receive a notification (see tab "Extended settings" → "Notifications") or you can see in the merchant menu that the payment has been made by the customer.

3.2. Additional functions in the paycode menu

In the merchant menu, you can also get an overview of the paycodes generated to date.

Go to "Transactions for" in the menu and click "SOFORT Paycode". You will receive a list of paycodes that have been generated so far and the corresponding (SOFORT) transactions initiated by a paycode. This list can be further filtered by the search function.

Furthermore, you have the possibility to display details on a specific paycode.

4. Paycode generation via the HTTP-XML interface (API)

Apart from generating paycodes in the merchant menu, you can also generate paycodes via the HTTP-XML interface (API) to integrate the transmitted value (paycode) directly in your system.

4.1. Communication with the SOFORT Paycode interface

Our interface (API) can be called from your shop by a HTTP POST with attached XML parameters. The responses for calls of our interface are formatted in XML as well.

Direct communication with our interface via XML-HTTP messages always follows the same pattern:

  • (API step 1) Initial API call and transaction parameter transfer
  • (API step 2) API response with generated paycode and payment URL
  • (Customer action) Redirection of received paycode and listing of transfer
  • (API step 3) Transaction status change notification (if configured)
  • (API step 4) Transaction data request
  • (API step 5) Response to transaction data request

In addition, the API provides another possibility to request the status of a previously generated paycode:

To change an already existing Paycode we provide the following API:

In order to deactivate paycodes and reactivate them later on, the followin API is provided:

4.2. Initial API call and transaction parameter transfer (API step 1)

4.2.1. API call and authentication 

To prevent abuse of the interface, authentication must be performed for every interface call, using your customer number as user name and the API key as password. The API key is provided in the merchant menu at Additional services → API key. Please note the following before using the interface:

  • You have to call the correct URL using HTTPS as a protocol.
  • You have to transfer the correct authentication information. For authentication, the basic HTTP authentication (RFC 2617) is used.
  • You have to enter the correct content type headers.
  • Your data must be correctly formatted in XML (RFC 3023, see parameter description) and sent by HTTP POST.

The interface is called via the following URL:

https://api.sofort.com/api/xml

4.2.2. Transfer of transaction data

Various parameters must be transferred to our API for the call. Some parameters are mandatory, some are optional. Details on the use of the individual parameters are listed in the overview of parameters. An example of a call for the generation of a SOFORT paycode formatted in XML might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<paycode>
     <project_id>53245</project_id>
     <interface_version>pn_test_1</interface_version>
     <start_date>2014-01-01T00:00:00+01:00</start_date>
     <end_date>2015-05-01T01:12:59+02:00</end_date>
     <amount>2.20</amount>
     <currency_code>EUR</currency_code>
     <max_usage>2</max_usage>
     <sender>
          <bank_code>00000</bank_code>
          <bic>SFRTDE20XXX</bic>
          <country_code>DE</country_code>
     </sender>
     <reasons>
          <reason>Reason Line 1 üäöß</reason>
          <reason>Reason Line 2</reason>
     </reasons>
     <success_url>https://www.example.com/success.php?trx=-TRANSACTION-</success_url>
     <success_link_redirect>0</success_link_redirect>
     <abort_url>https://www.example.com/abort.php</abort_url>
     <notification_urls>
          <notification_url>https://www.example.com/notify.php</notification_url>
     </notification_urls>
     <notification_emails>
          <notification_email>notify@example.com</notification_email>
     </notification_emails>
     <user_variables>
          <user_variable>Test123</user_variable>
     </user_variables>
     <intervals>
          <interval>
               <from_date>2014-10-01</from_date>
               <amount>3.30</amount>
               <reasons>
                    <reason>Reason Line 1üöäß</reason>
                    <reason>Reason Line 2 - interval2</reason>
               </reasons>
          </interval>
          <interval>
               <from_date>2014-02-01</from_date>
               <amount>4.40</amount>
               <reasons>
                    <reason>Reason Line 1üöäß</reason>
                    <reason>Reason Line 2 - interval3</reason>
               </reasons>
          </interval>
     </intervals>
</paycode>

With the transfer of several validity intervals within <intervals> you can define timeframes in which specified amounts and reasons hold. Therefore, the <interval> sections define the date when an interval begins (<from_date>) and which values hold for that interval. Thus, it is possible to handle e.g. early bird discounts or discounts on invoices with the paycode. For the paycode that results from the above mentioned request the following validity intervals would hold:

Paycode start - 2014-01-01 00:00:00

Amount: 2.20
Reason: Customer ID 100256
  Paycode Int 0

Interval 1 - 2014-10-01 00:01:00

Amount: 3.30
Reason: Customer ID 100256
  Paycode Int 1

Interval 2 - 2015-02-01 00:01:00

Amount: 4.40
Reason: Customer ID 100256
  Paycode Int 2

Paycode end - 2015-05-01 01:12:59

Note: In contrast to the start and end date of a paycode the validity interval begins with a new day at 00:01:00. Either the time zone MEZ (UTC+1) or MESZ (UTC+2) are assumed (depending of the season).

4.3. API response with generated paycode and payment URL (API step 2)

If the API call was correct, the API response will include the generated paycode and the URL to directly open the paycode wizard at SOFORT. Details on the use of the individual parameters are listed in the overview of parameters.

An example of the interface response formatted in XML might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<new_paycode>
     <paycode>6c9d197ddb</paycode>
     <paycode_url>https://www.sofort.com/paycode/6c9d197ddb</paycode_url>
</new_paycode>

4.4. Redirection of received paycode and listing of transfer (customer action)

Send the generated paycode (tag content <paycode>) and the URL https://www.sofort.com/paycode/ to your customer. When calling the URL, your customer will be requested to enter the paycode. Then, your customer will be guided through SOFORT. Alternatively, you can redirect your customer to the generated direct link to the payment wizard (tag content <paycode_url>), e.g. in an email on the payment request.

After successful execution of SOFORT paycode, your customer will be redirected to the success link stored with the project or transferred with the call (API step 1). Ideally, the order will be confirmed in a final summary including the successful execution of SOFORT in the customer's online banking. In the background, your shop system should meanwhile have received a confirmation of the transaction (see API steps 3, 4, and 5) and stored the order with the corresponding status. If no success link has been stored with the project and no success link was transferred in the initial API call (API step 7), your customer will only see a summary of the listed transfer.

In case SOFORT has not been carried out successfully, your customer will be redirected to the abort link.

4.5. Transaction status change notification (if configured) (API step 3)

After successful execution of SOFORT, you will be notified of the executed transaction while the customer is redirected to the success page. This is done by calling the notification URL or by sending an email. You can store the URL with the project or already transfer it when initially calling the API (API step 1). This notification includes the transaction ID of the transaction whose status changed. If no URL/email address has been stored with the project or transferred with the API call, no notification will be given.

An example of an interface notification formatted in XML might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<status_notification>
     <transaction>99999-53245-5483-4891</transaction>
     <time>2013-04-02T14:19:08+01:00</time>
</status_notification>

You will receive a notification of every transaction status change. Please initiate a transaction data request (see API step 4) to learn the reason for the status change (see API step 4).

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

4.6. Transaction data request (API step 4)

You should respond to a notification by requesting transaction data. You may either request transaction data on specified transaction IDs or all transaction data of transactions carried out in a specified time.

Two examples of transaction data requests formatted in XML might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<transaction_request version="2">
     <transaction>99999-53245-5483-4891</transaction>
     <transaction>99999-53245-5741-1896</transaction>
</transaction_request>

or:

<?xml version="1.0" encoding="UTF-8" ?>
<transaction_request version="2">
     <from_time>2013-04-01</from_time>
     <to_time>2013-04-30</to_time>
     <product>paycode</product>
     <number>10</number>
     <page>2</page>
</transaction_request>

4.7. Response to transaction data request (API step 5)

Any data available on requested transactions will be transmitted. The parameters and their descriptions which might be included in a response are listed in the overview of parameters. If no transactions match the assigned search parameters of API-step 4 the response contains only an empty <transactions/> tag.

<?xml version="1.0" encoding="UTF-8" ?>
<transactions>
     <transaction_details>
          <project_id>53245</project_id>
          <transaction>99999-53245-5483-4891</transaction>
          <test>1</test>
          <time>2013-04-02T14:19:08+01:00</time>
          <status>pending</status>
          <status_reason>not_credited_yet</status_reason>
          <status_modified>2013-04-02T14:19:08+01:00</status_modified>
          <payment_method>paycode</payment_method>
          <language_code>de</language_code>
          <amount>2.20</amount>
          <amount_refunded>0.00</amount_refunded>
          <currency_code>EUR</currency_code>
          <reasons>
               <reason>Reason Line 1 ueaeoess</reason>
               <reason>Reason Line 2</reason>
          </reasons>
          <user_variables>
               <user_variable>Test123</user_variable>
          </user_variables>
          <sender>
               <holder>Max Mustermann</holder>
               <account_number>23456789</account_number>
               <bank_code>00000</bank_code>
               <bank_name>Demo Bank</bank_name>
               <bic>SFRTDE20XXX</bic>
               <iban>DE06000000000023456789</iban>
               <country_code>DE</country_code>
          </sender>
          <email_customer/>
          <phone_customer/>
          <exchange_rate>1.0000</exchange_rate>
          <recipient>
               <holder>Max Mustermann</holder>
               <account_number>123456789</account_number>
               <bank_code>70011110</bank_code>
               <bank_name>Deutsche Handelsbank</bank_name>
               <bic>DEKTDE7GXXX</bic>
               <iban>DE0370011110123456789</iban>
               <country_code>DE</country_code>
          </recipient>
          <costs>
               <fees>0.00</fees>
               <currency_code>EUR</currency_code>
               <exchange_rate>1.0000</exchange_rate>
          </costs>
          <paycode>
               <code>6c9d197ddb</code>
          </paycode>
          <status_history_items>
               <status_history_item>
                    <status>pending</status>
                    <status_reason>not_credited_yet</status_reason>
                    <time>2013-04-02T14:19:08+01:00</time>
               </status_history_item>
          </status_history_items>
     </transaction_details>
</transactions>

Status messages

The response of the transaction data includes the notification of the current status of the requested transaction(s).

A transaction will not be created with SOFORT until the online banking details have been successfully entered and the customer's bank has confirmed and listed the transfer in the customer's online banking. If this has not yet taken place (for example when the payment process is still on-going or the payment could not be made by SOFORT), you will receive a response with an empty <transactions /> tag when requesting transaction data on a transferred transaction ID. The final failure of a transaction cannot be established before the period of validity has expired (<timeout> from API step 1).

After successful execution of SOFORT, a distinction must be made whether you have set up an account with Deutsche Handelsbank as a recipient account or not. In the first case, SOFORT can immediately confirm the receipt of the money on your account and notify you if the money has not been received within a certain period of time. In the second case, if you have not set up an account with Deutsche Handelsbank as a recipient account, the status "untraceable" will be displayed after successful execution of SOFORT.

Detailed information on possible statuses and their descriptions can be found in the Appendix.

4.8. Error messages

HTTP error messages (for example 401 (-> unauthorised, HTTP authentication via customer number, API key failed), 404, ...)

When a call of the interface is made incorrectly, you will receive different error messages.

HTTP error codes

  • Error code 401 Unauthorized is displayed when you entered incorrect authentication data (Base64-coded combination of customer number and API key)
  • Error code 404 Not Found is displayed when you call an incorrect URL

API error codes

If the HTTP call including authentication was successful (HTTP 200 OK), errors within the transferred XML data may generate additional error messages. The individual XML error codes and their descriptions which might be included in a response are listed in the overview of errors. An example of a response including an error code and description formatted in XML might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<new_paycode>
 ...
     <warnings>
          <warning>
               <code>8049</code>
               <message>Unsupported language.</message>
               <field>language_code</field>
          </warning>
     </warnings>
</new_paycode>

bzw.

<?xml version="1.0" encoding="UTF-8" ?>
<errors>
     <error>
          <code>6100</code>
          <message>Paycode request could not be processed.</message>
     </error>
</errors>

bzw.

<?xml version="1.0" encoding="UTF-8" ?>
<errors>
     <error>
          <code>8014</code>
          <message>Invalid amount.</message>
          <field>amount</field>
     </error>
</errors>

4.9. Paycode status call (API step SR-1)

If you generated a paycode previously, you can request its status with the following call. This call only expects the generated paycode to be passed:

<?xml version="1.0" encoding="UTF-8" ?>
<paycode_request>
     <paycode>6c9d197ddb</paycode>
</paycode_request>

4.10. Response to paycode status call (API step SR-2)

The response to a specific paycode status call includes all information on the paycode. The parameters and their descriptions which might be included in a response are listed in the overview of parameters.

<?xml version="1.0" encoding="UTF-8" ?>
<paycode_details>
  <status>open</status>
  <paycode>6c9d197ddb</paycode>
  <project_id>53245</project_id>
  <amount>2.2</amount> 
  <reasons> 
    <reason>Rasenmäher</reason> 
    <reason>Bleistift</reason> 
  </reasons> 
  <time_created>2015-04-10T10:01:07+02:00</time_created> 
  <time_used>2015-04-10T10:55:43+02:00</time_used> 
  <start_date>2015-01-01T00:00:00+01:00</start_date> 
  <end_date>2015-12-12T23:59:59+01:00</end_date> 
  <max_usage>5</max_usage>
  <currency_code>EUR</currency_code> 
  <language_code>DE</language_code> 
  <sender> 
    <bank_code>00000</bank_code> 
    <bic>SKGIDE5FXXX</bic> 
    <country_code>DE</country_code> 
  </sender> 
  <user_variables> 
    <variable>Variable 1</variable> 
    <variable>Variable 2</variable> 
  </user_variables> 
  <transactions> 
    <transaction>99999-53245-5527834B-437A</transaction> 
    <transaction>99999-53245-55278802-16BB</transaction> 
    <transaction>99999-53245-5527900F-5F33</transaction> 
  </transactions>
</paycode_details>

The fields transaction and time_used are only filled with a value if the paycode has been activated.

4.11. API call to change a paycode (API step M-1)

If you have already created a paycode you can change it later on. Here, you can transfer all parameters with adapted values that are possible in the initial API call (API step 1) except <project_id> and <interface_version>. Only those parameters need to be transferred that should be changed. All other parameters remain valid with their previous transferred values.

Note: If you want to change the validity intervals (<intervals>) you need to transfer a new set of intervals with the changed values. If you want to delete the validity intervals please transfer <intervals />.

An example of an API call to change the paycode might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<edit_paycode>
   <paycode>6c9d197ddb</paycode>
   <amount>5.50</amount>
   <minimal_amount>4.00</minimal_amount>
   <start_date>2014-12-01T00:00:00+01:00</start_date>
   <max_usage>100</max_usage>
   <reasons>
      <reason>Reason Line 1 changed</reason>
   </reasons>
   <intervals>
      <interval>
         <from_date>2014-12-15</from_date>
         <amount>6.60</amount>
         <minimal_amount>5.00</minimal_amount>
         <reasons>
            <reason>Reason Line 1 new</reason>
            <reason>Reason Line 2 new</reason>
         </reasons>
      </interval>
      <interval>
         <from_date>2014-12-20</from_date>
         <amount>7.70</amount>
         <minimal_amount>6.00</minimal_amount>
         <reasons>
            <reason>Reason Line 1 newer</reason>
         </reasons>
      </interval>
   </intervals>
</edit_paycode>

4.12. API response of a changed paycode (API step M-2)

As a response to the call for changing a paycode you receive the paycode and the status message "edited":

<?xml version="1.0" encoding="UTF-8" ?>
<edit_paycode>
     <paycode>6c9d197ddb</paycode>
     <paycode_url>https://www.sofort.com/paycode/6c9d197ddb</paycode_url>
     <status>edited</status>
</edit_paycode>

4.13. API call to deactivate a paycode (API step DA-1)

To deactivate an already existing paycode you can use the following API call. Afterwards the deactivated paycode cannot be used.

<?xml version="1.0" encoding="UTF-8" ?>
<deactivate_paycode>
     <paycode>6c9d197ddb</paycode>
</deactivate_paycode>

4.14. API response with deactivation confirmation (API step DA-2)

As a response to the call for deactivating a paycode you receive the paycode and the status message "deactivated":

<?xml version="1.0" encoding="UTF-8" ?><deactivate_paycode>     <paycode>6c9d197ddb</paycode>     <status>deactivated</status></deactivate_paycode>

4.15. API call to reactivate a paycode (API step RA-1)

To activate a previously deactivated paycode you can use the following API call. Afterwards the paycode can be used again with the previously defined parameter values.

<?xml version="1.0" encoding="UTF-8" ?>
<activate_paycode>
     <paycode>6c9d197ddb</paycode>
</activate_paycode>

4.16. API response with reactivation confirmation (API step RA-2)

As a response to the call for reactivating a paycode you receive the paycode and the status message "activated":

<?xml version="1.0" encoding="UTF-8" ?>
<activate_paycode>
     <paycode>6c9d197ddb</paycode>
     <status>activated</status>
</activate_paycode>

5. Testing

In order to fully test the functionality of the integration of the SOFORT paycode, please carry out a test generation including a test transfer directly in your system. Please note the following steps:

  • Activate test mode
  • Generate test paycode
  • Carry out test transaction
  • Check redirection to shop and notification

Please note that no real transfers will be made if you activate the test mode and use one of the specified test sort codes.

The test mode also allows real transfers when using a valid sort code.

Make sure to deactivate the test mode for productive use.

5.1. Activate test mode

Activate the test mode in your paycode project in the merchant area on the SOFORT website.

5.2. Generate test paycode

Generate a paycode in your system and by calling the XML interface.

5.3. Carry out test transaction

  • Open the URL https://www.sofort.com/paycode and enter the test paycode generated before.
  • Check the transferred data (recipient including address, reason, amount) in the SOFORT payment wizard.
  • Then enter "88888888" (8 times the number "8") in the payment wizard as the sort code for German sender accounts, choose "Others" and "999" (3 times the number "9") for Belgium and "00000" (5 times the number "0") or "Demo Bank" for all other countries. (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. Via the API you can already transfer the test BIC as <sender><bic>)
  • You can freely enter the other data requested, but make sure you observe a minimum length of 4 characters.

5.4. Check redirection/notification

If you set up a redirection to a success/abort page or a notification, check whether they are performed correctly and whether your system responds properly.

  • Is the customer redirected to the confirmation page after the transaction?
  • Do you get all notifications correctly provided that they have been activated and transferred?
  • Are the order details recorded and loaded correctly?
  • Is the order/payment status set correctly and is the order created correctly?

6. Overview of parameters

If you do not use the code library (SofortLib), you will find the detailed XML interface documentation here.

Description of the table columns of the subsequent tables

  • Parameter: XML tag name which is transferred (<parameter>parameter-content</parameter>)
     The logical structure of an XML document is a tree structure, thus featuring a hierarchical organisation. The hierarchy is illustrated by indentation in the tables. Parameters marked in boldface symbolises parent nodes with one or more child nodes.
  • Number: specifies how frequently a parameter may be used under its higher-level parameter
    • [1] = mandatory parameter
    • [0,1] = optional parameter, a maximum of one value can be transferred
    • [0..20] = optional parameter, up to 20 values can be transferred
    • [n] = optional parameter, any number of parameters can be transferred
    • [1..n] = mandatory parameter, a minimum of one parameter must and any number of parameters can be transferred
  • Type (length): specifies the data type of the parameter content; if this is a string, the maximum permissible number of characters is stated
  • Description: detailed description of the use of the parameter

6.1. (API step 1) Initial API call and transaction parameter transfer

6.1.1. API call and authentication 

The interface is called via the following URL:

https://api.sofort.com/api/xml

The basic http authentication (RFC 2617) is used for authentication. Please enter your customer number as user name (for example 99999) and your API key as password (for example a12b34cd567890123e456f7890123456), separated by ":" and coded by Base64 (base64(99999:a12b34cd567890123e456f7890123456)).

For every call, the field Content Type and the field Accept in the HTTP header requires input of  "application/xml".

An example of a HTTP header might look as follows:

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

After successful authentication, the server will confirm your API call with HTTP 200 OK.

The content of the messages must be correctly formatted in XML. The possible parameters are described in detail in the following.

Note: You have to use the URL specified above for every API call described in the following and authenticate yourself as described.

6.1.2. Payment data transfer

This table contains all possible parameters which you can transfer to our system in a call.

Parameter Number of Type (Length) Description
paycode [1] Container Identifies the paycode API call, encloses the entire message
  project_id [1] Integer Project number
  interface_version [0,1] String (255) Version of shop interface, e.g. „xt:commerce_v4.1.0“
  language_code [0,1] String (2) Language of payment wizard, according to ISO 639-1 e.g. "DE"; is interdependent with <sender><country_code> and should only be used if a certain language should be fored. Otherwise, dynamic parameters like the browser language are used to determine the language of the payment wizard.
  start_date [0,1] String (19) Validity begin of a paycode in the format "YYYY-MM-DDThh:mm:ss+HH:mm" (alternatively "YYYY-MM-DD hh:mm:ss" can be used, while UTC+1/UTC+2 are assumed) - must be before the end date. If the start is not defined, the paycode is valid from its creation.
  end_date [0,1] String (19) Validity end of a paycode in the format "YYYY-MM-DDThh:mm:ss+HH:mm" (alternatively "YYYY-MM-DD hh:mm:ss" can be used, while UTC+1/UTC+2 are assumed) - must be in the future (max. 900 days later than the start_date). If the end is not defined, the expiration date of the "max. validity in days" (at 23:59:59) stored in the project is automatically stated here.
  amount [1]* Decimal (8.2)

Amount, format: no thousands separators, two digits behind the decimal point, separated by a point ".", e.g. "150.00" (150 Euro)

Please note that if the currency_code is "HUF" and a float value is assigned the amount will be rounded to the nearest integer value. (e.g. 1000.50 > 1001 and 1000.49 > 1000).

*With activated option "Customer may change amount" in the SOFORT merchant area, this parameter is not mandatory.

  minimal_amount [0,1] Decimal (8.2)

The amount that has to be transferred at least by the payer (this parameter has only an effect if the feature "Customer may change amount" is activated in the SOFORT merchant area).

Please note that if the currency_code is "HUF" and a float value is assigned the amount will be rounded to the nearest integer value. (e.g. 1000.50 > 1001 and 1000.49 > 1000).

  currency_code [0,1] String (3) Currency according to ISO 4217, e.g. "EUR", if no value has been transferred, "EUR" will be stated as default value.
  max_usage [0,1] Integer Sets the maximum amount the paycode can be used.Allowed values: 1-999999 (needs to be activated by SOFORT)
  sender [0,1] Container Sender account of your customer
    bank_code [0,1] String (30) DEPRECATED: Sort code of your customer, please use <bic> instead
    bic [0,1] String (11) BIC of your customer's account
    country_code [0,1] String (2) Country code of the country in which the account has been established according to ISO 3166-1; e.g. "de"
  reasons [1] Container List of reasons
    reason [1..2] String (27)

Reason; please transfer a unique value (e.g. order number), only the following characters are allowed:  '0-9', 'a-z','A-Z', ' ', '+', ',', '-', '.'. Umlauts are replaced, e.g. ä -> ae. Other characters will be removed for the display on our payment page and for notifications. Therefore, a modified string for reason_1 and reason_2 may be transmitted for redirections (success and abort link and notifications).

Some banks do not display the entire characters of both reasons, e.g. on the account statements the last characters are cut off. Therefore, the important data should be inserted at the beginning of the first reason field.

  intervals [0,1] Container Container that contains a list of validity intervals. For each validity interval certain parameters can have specified values that are only valid during this interval.
    interval [0,n] Container Container that contains the details for a validity interval.
      from_date [1] String (19) Start date of a validity interval foramtted "YYYY-MM-DD". The interval lasts until the startdate of the next validity interval or if no further interval is transferred until the end of the validity time of the paycode. The date has to be previous to the <end_date> of the paycode (i.e. the <end_date> needs to lie more ahead than the start date of the interval).
      amount [0,1]* Decimal (8.2)

Amount that holds during the validity interval; format: no thousands separators, two digits behind the decimal point, separated by a point ".", e.g. "150.00" (150 Euro)

Please note that if the currency_code is "HUF" and a float value is assigned the amount will be rounded to the nearest integer value. (e.g. 1000.50 > 1001 and 1000.49 > 1000).

* at least one of the parameters <amount>, <minimal_amount> or <reasons> need to be transferred.

      minimal_amount [0,1]* Decimal (8.2)

The amount that has to be transferred at least by the payer (this parameter has only an effect if the feature "Customer may change amount" is activated in the SOFORT merchant area).

Please note that if the currency_code is "HUF" and a float value is assigned the amount will be rounded to the nearest integer value. (e.g. 1000.50 > 1001 and 1000.49 > 1000).

* at least one of the parameters <amount>, <minimal_amount> or <reasons> need to be transferred.

      reasons [0,1]* Container

List of reasons that hold during the validity interval.

* at least one of the parameters <amount>, <minimal_amount> or <reasons> need to be transferred.

        reason [1..2] String (27)

Reason of the validity interval; please transfer a unique value (e.g. order number), only the following characters are allowed:  '0-9', 'a-z','A-Z', ' ', '+', ',', '-', '.'. Umlauts are replaced, e.g. ä -> ae. Other characters will be removed for the display on our payment page and for notifications. Therefore, a modified string for reason_1 and reason_2 may be transmitted for redirections (success and abort link and notifications).

Some banks do not display the entire characters of both reasons, e.g. on the account statements the last characters are cut off. Therefore, the important data should be inserted at the beginning of the first reason field.

  success_url [0,1] String (255) Success link, overwrites the default value from the project settings. If the transaction ID of SOFORT should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String.
  success_link_redirect [0,1] Boolean Automatic redirection to success page. If this has not been activated, a summary page of SOFORT GmbH will be displayed to the customer.
  abort_url [0,1] String (255) Abort link, overwrites the default value from the project settings. If the transaction ID of SOFORT should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String.
  notification_urls [0,1] Container List of notification links
    notification_url [0..5] String (255) Notification link; an example of a transfer can be found in the example of an XML call. If the transaction ID of SOFORT should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String.
    notification_url notify_on=“xyz“ [0..5] String (255) Notification link; by replacing the part “xyz“ by a special status, only this URL is used for notifications with this status. It is possible to enter several statuses separated by commas, e.g.  <notification_url notify_on=“pending, loss“> Possible statuses: "pending", "received", "loss", "refunded".
  notification_emails [0,1] Container List of notification email addresses
    notification_email [0..10] String (255) Notification email address
    notification_email notify_on=“xyz“ [0..10] String (255) Notification link; by replacing the part “xyz“ by a special status, only this email is used for notifications with this status. It is possible to enter several statuses separated by commas, e.g.  <notification_email notify_on=“pending, loss“> Possible statuses: "pending", "received", "loss", "refunded".
  user_variables [0,1] Container List of variables to be freely assigned
    user_variable [0..20] String (255) Variable to be freely assigned

Table 1: Parameter definition of the initial call and transaction parameter transfer (API step 1)

6.2. (API step 2) API response with generated paycode and payment URL

The response to the API call includes a paycode and the payment wizard URL to redirect the customer to. The response may also include warnings.

Parameter Number of Type (Length) Description
new_paycode [0,1] Container Identifies the response to a paycode API call, encloses the entire message
  paycode [1] String (10) The generated paycode to be forwarded to your customer
  paycode_url [1] String (255) The link to the payment wizard with the attached paycode. Immediately redirects your customer to the correct payment wizard
  warnings [0,1] Container List of warnings
    warning [1..n] Container List of warnings
      code [1] Integer Warning number
      message [1] String (255) Warning message
      field [1] String (255) Field the warning refers to
errors [0,1] Container Error (find definition below) - may be alternatively returned instead of the tag <new_paycode>
  ...      

Table 2: Parameter definition of the response to the initial call with generated paycode (API step 2)

6.3. (API step 3) Transaction status change notification

Upon completion of a transaction or in case of a status change, you will receive a message containing the following parameters.

Parameter Number of Type (Length) Description
status_notification [1] Container Identifies a transaction status change, encloses the entire message
  transaction [1] String (27) Transaction number
  time [1] String (25) Date and time (with time zone) according to ISO 8601 in the format YYYY-MM-DDThh:mm:ss+HH:mm, e.g. 2013-03-14T11:38:00+02:00

Table 3: Parameter definition of the transaction status change notification (API step 3)

6.4. (API step 4) Transaction data request

If you want to learn more about status changes, submit a transaction detail request containing the following parameters. You may either request details on specific transaction numbers (<transaction>) or on a specific period of time and more filter criteria, in which the transactions were generated.

Note on data requests on a specific period of time:
You cannot request more than 100 transaction data records at a time, even if you omit the <number> parameter (in this case the default value 100 takes effect).
Periods comprising more than 100 transactions require iterative requests with <page>1</page>, <page>2</page> etc.

Parameter Number of Type (Length) Description
transaction_request (with attribute version="2") [1] Container Identifies the transaction data request, encloses the entire message
  transaction [0..100] String (27) Transaction number; it is possible to request several transaction numbers at a time
  from_time [0,1] String (25)

Start of a time interval if no transaction number was transferred. Default: [date of call] 0:00 hrs

Formatted according to ISO 8601 YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm

  to_time [0,1] String (25)

End of a time interval if no transaction number was transferred. Default: [time of call]

Formatted according to ISO 8601 YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm

  from_status_modified_time [0,1] String (25)

Start of a time interval if no transaction number was transferred. This interval refers to transactions which have undergone the latest status change within this period of time.

Default: date of call 0:00 hrs.
Formatted according to ISO 8601: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm

  to_status_modified_time [0,1] String (25)

End of a time interval if no transaction number was transferred. This interval refers to transactions which have undergone the latest status change within this period of time.

Default: date of call 0:00 hrs.
Formatted according to ISO 8601: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm

  status [0,1] String Statuses to which the returned transactions are to be limited
  status_reason [0,1] String Status reasons to which the returned transactions are to be limited
  product [0,1] String Product to which the returned transactions are to be limited ("paycode": SOFORT Paycode, "payment": SOFORT)
  number [0,1] Integer Number of transactions to be transmitted (for request of time period). Default/Max: 100
  page [0,1] Integer

If number is used, the following transactions can be requested with this parameter. Default: 1

e.g. number=10, page=2 → transactions 11-20 are displayed

Table 4: Parameter definition of transaction data request (API step 4)

6.5. (API step 5) Response to transaction data request

The table provides an overview of all parameters which a transaction detail request may contain.

Parameter Number of Type (Length) Description
transactions [0,1] Container Identifies the response to a transaction data request, encloses the entire message
  transaction_details [0..n] Container Details of a transaction
    project_id [1] Integer Project number
    transaction [1] String (27) Transaction number
    test [1] Boolean Test transaction ("0" for false, "1" for true)
    time [1] String (25) Date and time of transaction generation (with time zone) according to ISO 8601 in the format YYYY-MM-DDThh:mm:ss+HH:mm , e.g. "2013-03-14T13:02:10+01:00"
    status [1] String (20) Status code of the transaction (see status codes)
    status_reason [1] String (255) Status reason
    status_history_items [1] Container Container for status history items
      status_history_item [0...n] Container Sub-category for individual, previous status items
        status [1] String (20) Status code of the transaction (see status codes)
        status_reason [1] String (255) Status reason
        time [1] String (25) Time of the set status according to ISO 8601 in the format YYYY-MM-DDThh:mm:ss+HH:mm, e.g. "2013-03-14T13:02:10+01:00"
    status_modified [1] String (25) Date and time of the latest status change (with time zone) according to ISO 8601 in the format YYYY-MM-DDThh:mm:ss+HH:mm, e.g. "2013-03-14T13:17:10+01:00"
    payment_method [1] String (7) Payment method used ("paycode" for SOFORT Paycode - others: su)
    language_code [1] String (2) Language according to ISO 639-1
    amount [1] Decimal (8.2)

Transfer amount

Please note that if the currency_code is "HUF" and a float value has been assigned in API-step 1 the returned amount is rounded to the nearest integer value (e.g. 1000.50 > 1001 and 1000.49 > 1000).

    amount_refunded [0,1] Decimal (8.2) Refund amount (this also includes partial amounts)
    currency_code [1] String (3) Currency according to ISO 4217, e.g. "EUR"
    reasons [1] Container List of reasons
      reason [0..2] String (255) Reason
    user_variables [1] Container List of user variables
      user_variable [0..20] String (255) User variable
    sender [1] Container Sender data (bank account of your customer) - These values might be completed or calculated from the customer's data, therefore we can not guarantee for their correctness.
      holder [1] String (255) Account holder
      account_number [1] String (30) DEPRECATED: Account number
      bank_code [1] String (30) DEPRECATED: Sort code
      bank_name [1] String (255) Name of bank
      bic [1] String (11) BIC
      iban [1] String (34) IBAN
      country_code [1] String (2) Country code according to ISO 3166-1
    recipient [1] Container Recipient data (bank account of merchant)
      holder [1] String (27) Account holder
      account_number [1] String (30) DEPRECATED: Account number
      bank_code [1] String (30) DEPRECATED: Sort code
      bank_name [1] String (255) Name of bank
      bic [1] String (11) BIC
      iban [1] String (34) IBAN
      country_code [1] String (2) Country code according to ISO 3166-1
    email_customer [1] String (255) End customer email address, e.g. for invoice
    phone_customer [1] String (255) End customer phone number (starts with "+"; possible characters: "0-9 , - / ( )" – no letters! )
    exchange_rate [1] Decimal (8.4) Exchange rate
    costs [1] Container Data on fees
      fees [1] Decimal (8.2) Fees associated with the requested transaction
      currency_code [1] String (3) Currency according to ISO 4217, e.g. "EUR"
      exchange_rate [1] Decimal (8.4) Exchange rate
    paycode [1] Container Container for data regarding the Paycode
      code [1] String (10) The paycode that is assigned to the transaction
errors [0,1] Container Error (find definition below) - may be alternatively returned instead of the tag <transactions>
  ...      

Table 5: Parameter definition of response to transaction data request (API step 5)

Status messages

A transaction detail message always includes a transaction status provided that a Deutsche Handelsbank account exists.

Parameter <status> Parameter <status_reason> Description
loss not_credited The money has not been received.
pending not_credited_yet The money has not yet been received.
received credited The money has been received.
refunded compensation The money has been refunded (partial refund).
refunded refunded The money has been refunded (complete refund of total amount).

Table 6: Status messages for transactions with SOFORT Paycode and a Deutsche Handelsbank account

Parameter <status> Parameter <status_reason> Description
untraceable sofort_bank_account_needed The Paycode transaction was successfully completed. Additional status messages on the receipt of the amount on the account are only possible if a Deutsche Handelsbank account exists.
Note: if the API call <transaction_request> is transmitted without the version attribute with value "2", the <status> value "untraceable" is replaced by "pending" with <status_reason> "not_credited_yet". This version 1 transaction request is deprecated.
refunded compensation The money has been refunded (partial refund).
refunded refunded The money has been refunded (complete refund of total amount).

Table 7: Status messages for transactions with SOFORT Paycode without a Deutsche Handelsbank account

6.6. (API step SR-1) Paycode status call

In addition, the API provides another possibility to request the status of a previously generated paycode.

Parameter Number of Type (Length) Description
paycode_request version="2" [1] Container Identifies the status request of a transferred paycode, encloses the entire message
  paycode [1] String (10) Paycode whose status is to be requested

Table 8: Parameter details for the paycode status call

6.7. (API step SR-2) Response to paycode status call

Parameter Number of Type (Length) Description
paycode_details [0,1] Container Identifies the paycode API call, encloses the entire message
  status [1] String (20) Paycode status (open, used, expired, deactivate)
  paycode [1] String (10) Paycode whose status has been requested
  project_id [1] Integer Project number the paycode is assigned to
  transactions [1] Container List of transaction numbers; can be empty if no transaction with the paycode has been carried out yet.
    transaction [0..n] String (27) Transaction number
  amount [1] Decimal (8.2) Amount stated upon paycode generation
  reasons [1] Container List of reasons
    reason [1..2] String (27) Reason
  time_created [1] String (25) Time when the paycode was generated (with timezone) according to ISO 8601 in the format "YYYY-MM-DDThh:mm:ss+HH:mm", e.g. 2013-03-13T08:59:00+01:00
  time_used [0,1] String (25) Time when paycode was activated; is only set when the paycode was activated, otherwise, the day is empty (with timezone) according to ISO 8601 in the format "YYYY-MM-DDThh:mm:ss+HH:mm", e.g. 2013-03-13T08:59:00+01:00
  start_date [0,1] String (25) Time when the paycode validity will begin (with timezone) according to ISO 8601 in the format "YYYY-MM-DDThh:mm:ss+HH:mm", e.g. 2013-03-13T08:59:00+01:00
  end_date [0,1] String (25) Time when the paycode validity will expire (with timezone) according to ISO 8601 in the format "YYYY-MM-DDThh:mm:ss+HH:mm", e.g. 2013-03-13T08:59:00+01:00
  max_usage [1] Integer Sets the maximum amount the paycode can be used (needs to be activated by SOFORT)
  currency_code [1] String (3) Currency according to ISO 4217, e.g. "EUR"
  language_code [0,1] String (2) Language according to ISO 639-1
  sender [0,1] Container Sender data (bank account of your customer)
    bank_code [1] String (30) DEPRECATED: Sort code
    bic [1] String (11) BIC
    country_code [1] String (2) Country code according to ISO 3166-1
  user_variables [0,1] Container List of user variables
    variable [0..20] String (255) User variable
errors [0,1] Container Error (find definition below) - may be alternatively returned instead of the tag <paycode_details>
  ...      

Table 9: Parameter details for the response to a paycode status call

As regards the tags "sender" and "user_variables", it must be ensured that the data always correspond with the data transferred when the paycode was generated. For example, the sender data may differ between paycode and transaction.

6.8. (API step M-1) API call to change a paycode

Already existing paycodes can be edited with the following parameters:

Parameter Number of Type (Length) Description
edit_paycode [1] Container Identifies the call to change the transferred paycode which encloses the entire message.
  paycode [1] String (10) Paycode that should be changed
  ... ... ... [each tag of API step 1 is possible, except the tags <project_id> and <interface_version>]

Table 10: Parameter details for the call to change a paycode

6.9. (API step M-2) API response of a changed paycode

The response to the call for changing a paycode contains the following parameters:

Parameter Number of Type (Length) Description
edit_paycode [0,1] Container Identifies the response of a call to change a paycode which encloses the entire message.
  paycode [1] String (10) The paycode that has been changed.
  paycode_url [1] String (255) The URL to the payment form with attached paycode. This redirects the customer directly to the payment form.
  status [1] String (6) Status "edited"
  warnings [0,1] Container List of warnings
    warning [1..n] Container Warning
      code [1] Integer Warning id
      message [1] String (255) Warning message
      field [0,1] String (255) Parameter that causes the warning
errors [0,1] Container Error (see the definition below) - can be returned alternatively to the tag <edit_paycode>.
  ... ... ...  

Table 11: Parameter details for the response of a call to change a paycode

6.10. (API step DA-1) API call to deactivate a paycode

To deactivate existing paycodes so that they cannot be used anymore, use the following parameters:

Parameter Number of Type (Length) Description
deactivate_paycode [1] Container Identifies the call to deactivate a paycode which encloses the entire message.
  paycode [1] String (10) Paycode that should be deactivated.

Table 12: Parameter details for the call to deactivate a paycode

6.11. (API step DA-2) API response with deactivation confirmation

The response to the call for deactivating a paycode contains the following parameters:

Parameter Number of Type (Length) Description
deactivate_paycode [0,1] Container Identifies the response of a call to deactivate a paycode which encloses the entire message.
  paycode [1] String (10) The paycode that has been deactivated
  status [1] String (6) Status "deactivated"
  warnings [0,1] Container List of warnings
    warning [1..n] Container Warning
      code [1] Integer Warning id
      message [1] String (255) Warning message
      field [0,1] String (255) Parameter that causes the warning
errors [0,1] Container Error (see the definition below) - can be returned alternatively to the tag <deactivate_paycode>.
  ... ... ...  

Table 13: Parameter details for the response of a call to deactivate a paycode

6.12. (API step RA-1) API call to reactivate a paycode

To reactivate paycodes that have been deactivated earlier so that they can be used again with the previously defined parameter values, the following parameters can be used:

Parameter Number of Type (Length) Description
activate_paycode [1] Container Identifies the call to reactivate a paycode which encloses the entire message.
  paycode [1] String (10) Paycode that should be reactivated.

Table 14: Parameter details for the call to reactivate a paycode

6.13. (API step RA-2) API response with reactivation confirmation

The response to a call for reactivating a paycode contains the following parameters:

Parameter Anzahl Typ (Länge) Erklärung
activate_paycode [0,1] Container Identifies the response for the paycode reactivation and encloses the entire message.
  paycode [1] String (10) The paycode that has been reactivated
  status [1] String (6) Status "activated"
  warnings [0,1] Container List of warnings
    warning [1..n] Container Warning
      code [1] Integer Warning id
      message [1] String (255) Warning message
      field [0,1] String (255) Parameter that causes the warning
errors [0,1] Container Error (see the definition below) - can be returned alternatively to the tag <activate_paycode>.
  ... ... ...  

Table 15: Parameter details for the response of a call to reactivate a paycode

6.14. Error messages/Warning

In case of an error/warning, you will receive the corresponding error code in the message.

Parameter Number of Type (Length) Description
errors [0..1] Container Fehlerliste
  error [1..n] Container Einzelner Fehler
    code [1] Integer Fehlernummer
    message [1] String (255) Fehlermeldung
    field [0..1] String (255) Feld, auf das sich der Fehler bezieht
warnings [0..1] Container Warnungsliste
  warning [1..n] Container Einzelne Warnung
    code [1] Integer Warnungsnummer
    message [1] String (255) Warnungsmeldung
    field [0..1] String (255) Feld, auf das sich die Warnung bezieht

Table 16: Parameter definition of the response to errors

Error codes

General errors upon a call

Code Message Beschreibung
1000 Invalid request. Invalid request
1001 Technical error. Technical error
7000 Invalid XML Invalid XML
7004 XML parameter not provided in request Empty POST data
7005 Project has no Deutsche Handelsbank account. No Deutsche Handelsbank account stored with the project.
7006 Service temporarily unavailable due to maintenance The service of SOFORT GmbH/Deutsche Handelsbank is temporarily unavailable due to maintenance.

Table 17: General errors

Error code for paycode request (API step 1&6)

Code Message Beschreibung
6100 Paycode request could not be processed Paycode interface must not be used because for example the project has not been released for paycode, the test mode does not run, or the project does not belong to the merchant
6101 Provide valid future datetime The date is in the past.
6102 Invalid date format. Incorrect date format transferred for the field 'start_date' or 'end_date'. Correct format: YYYY-MM-DD HH-MM-SS. Field may also remain empty, then the date will be calculated based on the project setting.
6103 Start date has to be earlier than end date. The start date has to be before the end date.
6104 A paycode can only be used for maximal 900 days. The interval between start date and end date is too large and has to be lower or equal to 900 days.
6105 Interval start date has to be in the validity period of the paycode. The start date of a validity intercal has to be between the start date and the end date of the paycode..
6106 Provide a valid start date for the interval. Either no or a faulty start date of a validty interval has been transferred.
6107 Invalid parameter in interval provided. Within the tag <interval> a parameter has been transferred that is not allowed.
6108 Provide at least one parameter for an interval. Within the tag <interval> neither <amount> nor <reasons> has been transferred.
6109 This paycode has already been used and cannot be changed anymore. The paycode has already been used and therefore no change is possible.
6110 This paycode has already been deactivated. The paycode has already been deactivated.
6111 This paycode is already active. The paycode is already active.
6112 End date was updated automatically based on project settings. Provide end_date in the API request to change it manually. The end date has been delayed to a future date based on the project settings. This is due to a change of the paycode while only a start date and no end date has been transferred.
6113 The code has already been used and cannot be changed anymore. The paycode has already been used and therefore no change is possible.
6114 End date has to be after the start date. The end date has to be chronologically after the start date.
6115 Changing start_date or end_date of the Paycode may affect the validity of intervals. By the change of the start date or the end date of the paycode further validity intervals may become invalid.
6116 The paycode is in use and therefore locked for 30 minutes. Please try again later. The paycode is being used and therefore locked for 30 minutes. If the paycode will not be redeemed it can be used after the 30 minutes again.
6117 The minimal amount is higher than the paycode amount. The minimal amount that needs to be payed by the customer is greater than the current amount of the paycode.
6118 The minimum amount is only relevant, if the consumer is allowed to change the amount. The minimal amount should only be transferred if the feature to edit the amount by the customer is activated in the project settings.
6119 The amount of the interval may not be smaller than the minimal amount of the paycode The amount of a transferred vailidity interval must not be less than the minimal amount that needs to be paid by the customer.
6120 No paycode provided. A mandatory paycode is missing. Please repeat the request and transfer a specific paycode.
6122 Value for maximal usage of the paycode is out of range. The number of times a paycode can be used must be between 1 and 999999

Table 18: Specific errors upon paycode requests

Specific errors/warnings upon a call (API step 1)

Code Message Meaning
8000 No project ID provided No project ID transferred
8001 Unknown project Unknown project
8002 Validation Error Data cannot be validated
8003 Request could not be processed Response to the transaction request not possible due to an error
8004 No product is selected No date was transferred for a payment method in the call.
8006 Logic error. e.g. the project has not been activated and is neither in the test mode, the requested product has not been activated or the data in the call contradict the project settings
8010 must not be empty The field listed must not be empty.
8011 not in list of valid values The transferred value is not included in the list of possible values.
8012 must be a positive number The transferred value is not a positive number, e.g. the number of items of a shopping cart position.
8013 unsupported currency The transferred currency is not supported by the system. At this time, only EUR, GBP, CHF, PLN, HUF, and CZK are accepted.
8014 invalid amount The transferred amount must be positive and must only have two decimal numbers at the most. A "." or "," is accepted as a decimal separator.
8015 amount is out of range The transferred amount is too large or too small.
8016 must be a valid url The transferred URL is invalid.
8017 invalid chars The transferred value contains characters which are not accepted, e.g. only certain characters are permitted in the field reason.
8018 maximum length of 27 chars exceeded Permitted number of characters exceeded, excess characters will be removed where required (e.g. in the field reason)
8019 invalid email address Invalid email
8021 invalid country code Value must be transferred according to ISO 3166.
8022 unsupported country code Transferred country code is not supported by our system.
8023 invalid BIC Invalid BIC
8024 only German addresses (DE) are supported An address abroad was specified as an invoice or shipping address.
8025 must be 2 or 3 // salutation Mr. = 2, Mrs. = 3.
8026 must be a boolean, either 0 or 1 0 or 1 must be entered as a value.
8027 product not activated and not in testmode The requested payment method is not available as the test mode has been deactivated and the payment method has not yet been released.
8028 locked_sender_country_id is activated in project settings, but not provided The settings of the payment method determine that the sender country must not be changed by the end customer during the payment process. When initiating the payment, the sender country must then be stated.
8040 No amount with comma allowed for HU. The amount has been transferred with decimal places which has been rounded down/up to the next integer (see also <amount>).
8042 consumer protection is only available for sender accounts from DE, AT and CH Buyer protection is only possible for sender accounts from Germany, Austria, and Switzerland.
8045 product in testmode and given bank_code is not a test bank code Account number, sort code, and account holder were transferred. Since the payment method runs in the test mode, one of the test sort codes must be entered (e.g. 00000).
8046 validation of given bank account and bank code failed The settings of the payment method determine that the sender data must not be changed by the end customer during the payment process. The transferred account data could not be validated however.
8047 Maximum length of 255 characters exceeded. Maximum number of characters (255) exceeded.
8049 unsupported language The transferred language is not supported by the system.
8050 value too small. setting timeout to minimum value. The transferred value for the duration of the payment process was too small and will be set to the minimum permissible value (120 seconds)
8051 invalid items found The request contained invalid shopping cart items
8054 all products deactivated due to errors. Initiation aborted All requested payment methods contained validation errors. The payment session could not be initiated.
8057 activate this product in your project settings The requested payment method has not been activated for the project. The merchant must activated the payment method in the merchant menu to be able to use the payment method.
8058 payment not possible with this service The payment cannot be used for this service
8059 sender country not supported for this currency Payments in the desired currency cannot be made for the specified sender country
8060 Blacklisted The payment cannot be executed as either the transferred banking details or the country has been blocked by the merchant.
8063 No success_url provided in request and in project settings The success link was neither set in the request nor in the settings.
8064 No abort_url provided in request and in project settings The abort link was neither set in the request nor in the settings.
8072 maximum number of notification exceeded Too many notification urls or notification email addresses have been assigned.
8073 Maximum number of user variables exceeded Too many user variables have been assigned.

Table 19: Special errors/warnings

Errors upon a transaction detail request (API step 4)

Code Message Meaning
7999 Out of range (Too many entries or invalid values for the site) Too many entries per page or invalid value for the page
8005 Too many transactions requested Too many transactions requested
8007 Invalid date format. Format is YYYY-MM-DD [HH:MM:SS] Invalid date format
8008 from_time equals to_time The from/to data must be different
8009 max date range exceeded Search interval too big

Table 20: Error for the transaction detail request SOFORT Gateway

Possible HTTP status codes of the interface

200 OK: message accepted

401 Unauthorized: no permission, e.g. wrong API key

404 Not Found: called URL does not exist or wrong URL was called

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
Knut Frängsmyr

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.