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.

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:

• (API step SR-1) Paycode status call
• (API step SR-2) Response to paycode status call

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

• (API step M-1) API call to change a paycode
• (API step M-2) API response of a changed paycode

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

• (API step DA-1) API call to deactivate a paycode
• (API step DA-2) API response with deactivation confirmation
• (API step RA-1) API call to reactivate a paycode
• (API step RA-2) API response with reactivation confirmation

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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

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.

Table 8: Parameter details for the paycode status call

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

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:

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:

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:

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:

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:

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:

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.

Table 16: Parameter definition of the response to errors

Error codes

General errors upon a call

Table 17: General errors

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

Table 18: Specific errors upon paycode requests

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

Table 19: Special errors/warnings

Errors upon a transaction detail request (API step 4)

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