Merchant Login

API Documentation

Direct Bank Transfer

1. Introduction to Direct Bank Transfer

Customers (end customers) do not have to register for Direct Bank Transfer: They make a fast and easy payment using their online banking details. Thanks to real time acknowledgement of the transfer order, you as a merchant can immediately ship the goods or provide services.

From your customer's perspective, an Direct Bank Transfer transaction consists of the following steps:

As soon as payment by Direct Bank Transfer is requested, the customer is redirected to an Direct Bank Transfer page.

Below the overview of the transfer data (recipient, reason, amount), your customer is requested to enter the sort code.

Subsequently, your customer is asked to log on by entering the online banking details.

After successful logon, the customer has to confirm and release the transfer by entering a valid confirmation code.

If a valid confirmation code has been entered, the transfer is authorized and your customer will receive a summary of the executed transaction.

Finally, the customer is redirected to your online shop with one click.

2. Integration steps

The following steps are basically required to integrate Direct Bank Transfer 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. Create a new Direct Bank Transfer Gateway Project.
    1. Choose the payment method of Direct Bank Transfer.
    2. Configure your Direct Bank Transfer Project.
       (In case you would like to be automatically informed by Sofort GmbH on incoming transfers to your account, please use your Deutsche Handelsbank Account).
    3. After you have created and configured a project, you will receive an API key.
  3. Integrate Direct Bank Transfer in your shop
    1. Integrate the payment method of Direct Bank Transfer for selection in the checkout.
    2. As soon as a customer requests to pay by Direct Bank Transfer, call our interface by entering the respective payment data. In response, you will receive a link to a Sofort GmbH page to redirect the customer for payment.
    3. The customer processes the payment on our page and is subsequently redirected to the success or abort page of your shop which you have defined.
    4. In case of a successful transaction (i.e. the transfer was initiated by your customer), you will automatically be notified of this transaction by Sofort GmbH. Subsequently, you can immediately initiate further steps such as shipping of goods or activation of the online offer. You will be notified of the successful transaction by email and via XML HTTP notification, which automatically informs your system of a status change. You may retrieve details on the transaction at any time (through an automated process).
Ablauf_SÜ

Note:

Please ensure during the integration that it is necessary to redirect the buyer directly on the payment form so that the URL and the SSL certificate of the Direct Bank Transfer are visible. That means a framed solution for example with <iframe> is not allowed due to legal reasons.

3. Integration of Direct Bank Transfer

As a first step, you have to integrate Direct Bank Transfer in the checkout of your shop to offer your customer Direct Bank Transfer as a payment method to be selected. If the customer selects Direct Bank Transfer as a payment method and confirms the order, communication between your shop and our interface (API) is initiated. Prior to the description of the individual Direct Bank Transfer process steps and the corresponding API calls, several framework conditions are explained that are required for successful execution of Direct Bank Transfer.

3.1 Integration of Direct Bank Transfer in the checkout

To integrate Direct Bank Transfer in the checkout, it is necessary to add an additional option for Direct Bank Transfer to the selection of the payment methods (for example as a new radio button, link, etc. - Details on this topic can be found in the documentation of your shop system). Logos, banners, information texts and links on detailed information for your customers are provided in the Integration Centre in Advertising Media to ensure optimal integration of Direct Bank Transfer.

3.2 Communication with the Direct Bank Transfer 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 payment URL to redirect the customer to
• (API step 3) Transaction status change notification
• (API step 4) Transaction data request
• (API step 5) Response to transaction data request

If you use PHP or Java as programming language for the integration, we provide code libraries (SofortLib) to considerably facilitate the implementation in your system. Implementation examples and short instructions on how to use the SofortLib can be found on our Integration Center.

3.3 Initial API call and transaction parameter transfer (API step 1)

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

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

Note

The Interface version logic used in all cases is in the following:

<interface_version>shopsystem name_shopsystem version/payment module name_payment module version</interface_version>

An example can be such as the following:
<interface_version>Magento_2.1.4/Sofort_2.3.3</interface_version>

In case  that you have built your own shop system, we recommend to use the same interface version logic.

An example can be:

<interface_version>MyShop/Sofort_0.1</interface_version>

Or

<interface_version>OwnShop/Sofort_0.2</interface_version>

In the following, there will be shown only the logic used for the interface version in order not to use any example given as the interface version that you have to transmit.

An example of an Direct Bank Transfer call formatted in XML might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<multipay>      
    <project_id>53245</project_id>
    <interface_version>shopsystem name_shopsystem version/payment module name_payment module version</interface_version>
    <amount>2.20</amount>
    <currency_code>EUR</currency_code>
    <reasons>
        <reason>Testueberweisung</reason>
        <reason>-TRANSACTION-</reason>
    </reasons>
    <user_variables>
        <user_variable>test</user_variable>
    </user_variables>
    <success_url>https://www.example.com/payment/success.php?trx=-TRANSACTION-</success_url>
    <success_link_redirect>1</success_link_redirect>
    <abort_url>https://www.example.com/payment/abort.php</abort_url>
    <notification_urls>
        <notification_url>https://www.example.com/notify.php</notification_url>
        <notification_url notify_on="received,loss">https://www.example.com/erp/payment_notification.php</notification_url>
    </notification_urls>
    <su />
</multipay>

Transfer of the reason for Belgian banks

Some Belgian banks use a separate field for the reason when the first 12 characters of the parameter reason contain only numbers.

Due to this, the reason on the bank statement can be falsified and important information on the bank statement may not be shown anymore.

We recommend to use at least one letter in the first 12 characters of the reason parameter for transactions from Belgium. Special characters like hyphen will only be seen as a subdivision of the numbers and don’t prevent the usage of the separate field.

3.3.3 Transfer of the beneficiary for the Wire Transfer Regulation 2017

When you have to set the beneficiary for each transaction for the Wire Transfer Regulation (since 26.06.2017) you can use the beneficiary parameters for this.

Note:

As banks don’t provide a specific field for the beneficiary we add these values to the usage. The usage is than containing the values <reasons> and <beneficiary>.

The usage field might not be long enough at every bank to show the whole beneficiary informations.

An example of an Direct Bank Transfer call formatted in XML might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<multipay>
      <project_id>53245</project_id>
      <interface_version>pn_test_1</interface_version>
      <amount>2.20</amount>
      <currency_code>EUR</currency_code>
      <beneficiary>
         <identifier>John Doe</identifier>
         <country_code>DE</country_code>
      </beneficiary>
      <reasons>
            <reason>Testueberweisung</reason>
            <reason>-TRANSACTION-</reason>
      </reasons>
      <user_variables>
            <user_variable>test</user_variable>
      </user_variables>
      <success_url>https://www.example.com/payment/success.php?trx=-TRANSACTION-</success_url>
      <success_link_redirect>1</success_link_redirect>
      <abort_url>https://www.example.com/payment/abort.php</abort_url>
      <notification_urls>
            <notification_url>https://www.example.com/notify.php</notification_url>
            <notification_url notify_on="received,loss">https://www.example.com/erp/payment_notification.php</notification_url>
      </notification_urls>
      <su />
</multipay>

3.4 API response with payment URL to redirect the customer to (API step 2)

As a response of this call, you will receive a transaction ID and the URL to process the payment (payment wizard) by the customer. Direct your customer on the returned URL of the payment form. There, your customer will be requested to enter the online banking details and to authorize the transfer. Subsequently, your customer will be directly forwarded to the transferred success page (back in your shop) or specified abort page in case of cancellation. The parameters and their descriptions which might be included in a response 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_transaction>
    <transaction>99999-53245-5483-4891</transaction>
    <payment_url>https://www.sofort.com/payment/go/508712aa8572615d6151de6111349bc5872435987c23c</payment_url>
</new_transaction>

You should then redirect your customer to the page transferred in the parameter "payment_url". The transaction ID is transferred in the parameter "transaction". You should store this transaction ID with the corresponding order to request for example transaction data at a later point of time.

3.5 Redirecting your customer to the success/abort page

After successful execution of Direct Bank Transfer, 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 Direct Bank Transfer 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), emptied the shopping cart, and stored the order with the corresponding status.

In case Direct Bank Transfer has not been carried out successfully, your customer will be redirected to the abort link. This link should ideally redirect the customer to the selection of payment methods with the shopping cart still being filled.

3.6 Transaction status change notification (API step 3)

After successful execution of Direct Bank Transfer, 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 either stored with the project or already transferred when initially calling the API (API step 1). This notification includes the transaction ID of the transaction whose status changed.

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>2010-04-14T19:01:08+02: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.

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

oder:

<?xml version="1.0" encoding="UTF-8" ?>
<transaction_request version="2">
    <from_time>2013-01-01</from_time>
    <to_time>2013-03-07</to_time>
    <number>10</number>
    <page>2</page>
    <product>payment</product>
</transaction_request>

3.8 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-06-03T10:48:52+02:00</time>
        <status>untraceable</status>
        <status_reason>sofort_bank_account_needed</status_reason>
        <status_modified>2013-06-03T10:48:52+02:00</status_modified>
        <payment_method>su</payment_method>
        <language_code>de</language_code>
        <amount>2.20</amount>
        <amount_refunded>0.00</amount_refunded>
        <currency_code>EUR</currency_code>
        <reasons>
            <reason>Testueberweisung</reason>
            <reason>99999-53245-5483-4891</reason>
        </reasons>
        <user_variables>
            <user_variable>test</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>
        <recipient>
            <holder>Erika Mustermann</holder>
            <account_number>9999999999</account_number>
            <bank_code>00000</bank_code>
            <bank_name>Demo Bank</bank_name>
            <bic>SFRTDE20XXX</bic>
            <iban>DE98000000009999999999</iban>
            <country_code>DE</country_code>
        </recipient>
        <email_customer />
        <phone_customer />
        <exchange_rate>1.0000</exchange_rate>
        <costs>
            <fees>0.00</fees>
            <currency_code>EUR</currency_code>
            <exchange_rate>1.0000</exchange_rate>
        </costs>
        <su>
            <consumer_protection>0</consumer_protection>
        </su>
        <status_history_items>
            <status_history_item>
                <status>untraceable</status>
                <status_reason>sofort_bank_account_needed</status_reason>
                <time>2013-06-03T10:48:52+02: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 Direct Bank Transfer 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 Direct Bank Transfer), 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 Direct Bank Transfer, 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 GmbH 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 Direct Bank Transfer.

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

Error messages

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

HTTP error codes

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

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" ?>
<errors>
    <error>
        <code>8054</code>
        <message>All products deactivated due to errors, initiation aborted.</message>
    </error>
    <su>
        <errors>
            <error>
                <code>8014</code>
                <message>Invalid amount.</message>
                <field>amount</field>
            </error>
        </errors>
    </su>
</errors>

bzw.

<?xml version="1.0" encoding="UTF-8" ?>
<errors>
    <error>
        <code>7000</code>
        <message>Mismatched tag. line: 24, char: 29, tag: multipay-&gt;su-&gt;reasons</message>
    </error>
</errors>

bzw.

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

4. Testing

In order to fully test the functionality of the integration of the installed payment methods, please carry out a test transfer directly in your (shop-)system. Please note the following steps:

  • Activate test mode
  • 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 however allows real transfers when using a valid sort code.

Make sure to deactivate the test mode for productive use.

4.1 Activate test mode

Activate the test mode in your project in the merchant area on the Sofort GmbH website.

4.2 Carry out test transaction

  • Carry out an order from your (shop-)system and select the respective payment method (Direct Bank Transfer).
  • After having been redirected to the Direct Bank Transfer payment, check the transferred data (recipient including address, reason, amount).
  • Then enter 88888888 (8 times the number "8") in the payment wizard as the sort code for German sender accounts, choose "Others" for Belgium and then 999 (3 times the number "9") and for all other countries 00000 (5 times the number "0") or select "Demo Bank". (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.

4.3 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?

4.4 Checklist for the integration

  • Activate product
  • Create project
  • Activate payment method in project
  • Carry out test transaction
  • Receive notification for test transaction
  • Request and receive transaction data
  • Implement and test potential refunds

5. 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 organization. The hierarchy is illustrated by indentation in the tables. Parameters marked in boldface symbolizes 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

5.1 (API step 1) Initial API call and transaction parameter transfer

5.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 an input of  "application/xml".An example of a HTTP header might look as follows:

Authorization: Basic OTk5OTk6YTEyYjM0Y2Q1Njc4OTAxMjNlNDU2Zjc4OTAxMjM0NTYgContent-Type: application/xml; charset=UTF-8Accept: 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.

5.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
multipay [1] Container Identifies the Direct Bank Transfer API call,  encloses the entire message
  project_id [1] Integer Project number
  interface_version [0,1] String (255) Identifies the Shop system version and Payment module by requesting the data in this format: <interface_version>shopsystem name_shop system version/module name_payment-module version</interface_version>
  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 forced. Otherwise, dynamic parameters like the browser language are used to determine the language of the payment wizard.
  timeout [0,1] Integer Transaction validity in seconds from the generation of the message new_transaction in the Direct Bank Transfer Gateway to the listing of the transfer / direct debit / etc.; default: unlimited
  email_customer [0,1] String (255) Email address of your customer, e.g. for invoice, cash in advance
  phone_customer [0,1] String (255) Phone number of your customer (begins with "+"; possible characters: "0-9 , - / ( )", no letters! )
  user_variables [0,1] Container List of user variables
    user_variable [0..20] String (255) User variable
  sender [0,1] Container Data of the sender (bank account of your customer)
    holder [0,1] String (27) Account holder
    iban [0,1] String (34) IBAN
    bic [0,1] String (11) BIC
    account_number [0,1] String (30) DEPRECATED: Account number, please use <iban>
    bank_code [0,1] String (30) DEPRECATED: Sort code, please use <bic>
    country_code [0,1] String (2) Country code according to ISO 3166-1; e.g. "de"
  amount [1] Decimal (8.2) Amount, format: no thousands separators, two digits behind the decimal point, separated by a point ".", e.g. "1150.00" (1.150,00 EUR)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 [1] String (3) Currency according to ISO 4217, e.g. "EUR"
  reasons [1] Container List of reasons
    reason [1..2] String (27) Reason; please transfer a unique value (e.g. order ID and customer ID, "OID018293 CID00131"), 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 may be transmitted for redirections (success and abort link and notifications). If the transaction ID of Direct Bank Transfer should be used as a reason, the parameter '-TRANSACTION-' can be inserted in the reason String.Important: 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.* Banks of Great Britain (GB) only support 18 digits per reason so we encourage to consider this for integrations that are used in this market.
  success_url [0,1]* String (255) Success link, overwrites the default value from the project settings. Is called when your customer successfully executed Direct Bank Transfer and the transfer has been listed in the customer's online banking. If the transaction ID of Direct Bank Transfer should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String.* If no success link is defined in the project settings this parameter becomes mandatory
  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. Overwrites project settings.
  abort_url [0,1]* String (255) Abort link, overwrites the default value from the project settings. Is called when Direct Bank Transfer could not be completed successfully (e.g. upon cancellation by the customer or insufficient funds). If the transaction ID of Direct Bank Transfer should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String.* If no abort link is defined in the project settings this parameter becomes mandatory
  timeout_url [0,1] String (255) Timeout link, overwrites the default value from the project settings. Is called when the timeout value stored in the project settings has been expired on the payment wizard. If the transaction ID of Direct Bank Transfer 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. If the transaction ID of Direct Bank Transfer 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 are "received", "loss", "refunded", and "pending" (whereupon "pending" matches the equivalent status "pending - not_credited_yet" and "untraceable - sofort_bank_account_needed". Details can also be found in the corresponding section.
  notification_emails [0,1] Container List of notification email addresses
    notification_email [0..10] String (255) Notification email addresses
    notification_email notify_on=“xyz“ [0..10] String (255) Notification email; 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_url notify_on="pending, loss">. Possible statuses are "received", "loss", "refunded", and "pending" (whereupon "pending" matches the equivalent status "pending - not_credited_yet" and "untraceable - sofort_bank_account_needed". Details can also be found in the corresponding section.
       
  su [1] Container Container for special parameters regarding Direct Bank Transfer. Is mandatory for each Direct Bank Transfer API call and might be transferred empty: <su />
  beneficiary [0,1] Container Container for special parameters regarding Direct Bank Transfer.
    identifier [0,1] String (27) beneficiary
    country_code [0,1] String (2) country of the beneficiary

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

5.2 (API step 2) API response with payment URL to redirect the customer to

The response to the API call includes a transaction number and a URL to redirect the customer to. The response may also include warnings.

Parameter Number of Type (Length) Description
new_transaction [0,1] Container Identifies the response to the initial call to transfer the transaction parameters, encloses the entire message
  transaction [1] String (27) Generated transaction number
  payment_url [1] String (255) Payment wizard URL
  su [0,1] Container Sofort
    warnings [0,1] Container List of warnings
      warning [1..n] Container Warning, non-critical errors
        code [1] Int Warning number
        message [1] String(255) Warning message
errors [0,1] Container Error (find definition below) - may be alternatively returned instead of the tag <new_transaction>
  ...      

Table 2: Parameter definition of the response with payment URL (API step 2)

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

5.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. Please take care to send also the attribute version="2". Otherwise you will receive different status codes as described in this manual.
  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 hrsFormatted 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 ("payment": Direct Bank Transfer, "paycode": Paycode)
  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: 1e.g. number=10, page=2 → transactions 11-20 are displayed

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

5.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_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 ("su" for Direct Bank Transfer - others: paycode)
    language_code [1] String (2) Language according to ISO 639-1
    amount [1] Decimal (8.2) Transfer amountPlease 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
    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) Account number
      bank_code [1] String (30) 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) Kontonummer
      bank_code [1] String (30) 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
    su [0,1] Container Direct Bank Transfer
    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"
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 and a status reason. Provided that a Deutsche Handelsbank account is defined as recipient account for the Direct Bank Transfer transactions the following status can occur:

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 Direct Bank Transfer and Deutsche Handelsbank accountIn case the recipient account of the Direct Bank Transfer account is not a Deutsche Handelsbank account the following status can occur:

Parameter <status> Parameter <status_reason> Description
untraceable sofort_bank_account_needed The Direct Bank Transfer 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 Direct Bank Transfer without Deutsche Handelsbank account

Please keep in mind that if a Direct Bank Transfer transaction has been successfully finished and Sofort GmbH has received the confirmation from the buyer's bank, Sofort GmbH reports the status "untraceable - sofort_bank_account_needed" (without Deutsche Handelsbank account) or "pending - not_credited_yet" (with Deutsche Handelsbank account). Both status messages have the equivalent meaning and represent the real-time transaction confirmation that should be processed by the merchant's online shop system.

5.6 Error messages/Warning

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

Parameter Number of Type (Length) Meaning
errors [0,1] Container List of errors
  error [1..n] Container Individual error
    code [1] Integer Error number
    message [1] String (255) Error message
    field [0,1] String (255) Field the errors refers to
  su [0,1] Container List of Direct Bank Transfer specific errors
    errors [1] Container List of errors
      error [1..n] Container Individual error
        code [1] Integer Error number
        message [1] String (255) Error message
        field [0,1] String (255) Field the errors refers to
warnings [0,1] Container List of warnings
  warning [1..n] Container Individual warning
    code [1] Integer Warning number
    message [1] String (255) Warning message
    field [0,1] String (255) Field the warning refers to

Table 8: Response to errorsError codesGeneral errors upon a call

Code Message Meaning
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 9: General errors Specific errors/warnings upon a call

Code Message Meaning
8000 No project ID provided No project ID transferred
8001 Unknown project Unknown project
8002 Validation Error An assigned parameter causes an error during validation
8003 Request could not be processed Response to the transaction request not possible due to an error
8004 No product is selected No product element (<su/>) was submitted 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
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>).
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 10: Special errors/warnings Errors upon a transaction detail request

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 (interval covers 30 days at max.)

Table 11: Error for the transaction detail request Direct Bank Transfer GatewayPossible HTTP status codes of the interface200 OK: message accepted401 Unauthorized: no permission, e.g. wrong API key404 Not Found: called URL does not exist or wrong URL was called

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

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