Händler-Login

API Dokumentation

Sofort

1. Einführung zu Sofort

Für Sofort müssen sich Ihre Kunden (Endkunden) nicht registrieren: Sie bezahlen schnell und einfach mit ihren bekannten Online-Banking Daten. Dank Echtzeitbestätigung des Überweisungsauftrags können Sie als Händler die Ware sofort versenden beziehungsweise Dienstleistungen sofort erbringen.

Eine Transaktion mit Sofort gliedert sich aus Sicht Ihrer Kunden in folgende Schritte:

  • Sobald ein Kunde per Sofort bezahlen möchte, wird er auf eine Seite der Sofort GmbH geleitet.
  • Unter der dortigen Übersicht der Überweisungsdaten (Zahlungsempfänger, Verwendungszweck, Betrag) wird Ihr Kunde aufgefordert, seine Bankleitzahl einzugeben.
  • Anschließend wird Ihr Kunde aufgefordert, sich mit seinen Online-Banking Zugangsdaten anzumelden.
  • Nach erfolgreicher Anmeldung muss Ihr Kunde die Überweisung mit einer gültigen TAN bestätigen und freigeben.
  • Sofern eine gültige TAN eingegeben wurde, wird die Überweisung beauftragt und Ihr Kunde gelangt zu einer Zusammenfassung der durchgeführten Transaktion.
  • Zuletzt gelangt er über einen Klick wieder zurück zu Ihrem Webshop.
Ablauf SÜ User Experience

2. Integrationsschritte

Um Sofort in Ihr System zu integrieren, sind allgemein folgende Schritte notwendig. Eine detaillierte Beschreibung der einzelnen Schritte folgt anschließend:

  1. Registrieren Sie sich als Anbieter auf unserer Seite https://sofort.com/register.
  2. Erstellen Sie ein neues Sofort-Gateway-Projekt.
    1. Wählen Sie dabei die Zahlart Sofort.
    2. Konfigurieren Sie Ihr Sofort-Projekt.
      (sofern Sie über eingegangene Überweisungen auf Ihrem Konto automatisch durch die Sofort GmbH informiert werden wollen, nutzen Sie bitte das Konto bei der Deutschen Handelsbank).
    3. Nach Projektanlage und -konfiguration erhalten Sie einen API-Key.
  3. Integrieren Sie Sofort in Ihren Shop
    1. Im Checkout ist die Zahlart Sofort als Auswahl zu integrieren.
    2. Sobald ein Kunde mit Sofort bezahlen möchte, rufen Sie unsere Schnittstelle mit den jeweiligen Zahlungsdaten auf. Als Antwort erhalten Sie einen Link auf eine Seite der Sofort GmbH, auf den Sie den Kunden zur Zahlung weiterleiten.
    3. Der Kunde wickelt die Zahlung auf unseren Seiten ab und wird anschließend auf die von Ihnen definierte Erfolgs- bzw. Abbruchseite Ihres Shops zurückgeleitet.
    4. Im Fall einer erfolgreichen Transaktion (d.h. die Überweisung wurde von Ihrem Kunden in Auftrag gegeben), werden Sie automatisch von der Sofort GmbH über diese Transaktion benachrichtigt. Anschließend können sie sofort weitere Schritte, wie bspw. Warenversand oder Freischaltung zum Online-Angebot, veranlassen. Die Benachrichtigung der erfolgreichen Transaktion erfolgt dabei sowohl per E-Mail, als auch via XML-HTTP-Benachrichtigung, die Ihr System automatisch
    5. über eine Statusänderung benachrichtigt. Details zu der Transaktion können Sie dann jederzeit (automatisiert) abrufen.
Ablauf SOFORT Überweisung API

Hinweis:

Bitte achten Sie bei der Integration darauf, dass eine Weiterleitung des Zahlenden auf das Zahlformular stattfinden muss, so dass die URL und das SSL-Zertifikat der Sofort GmbH sichtbar sind. D.h. eine eingeframte Lösung bspw. mit <iframe> ist aus rechtlichen Gründen nicht erlaubt.

3. Integration von Sofort

Damit Ihre Kunden Sofort als Zahlungsverfahren auswählen können, müssen Sie in einem ersten Schritt Sofort im Checkout Ihres Shops einbinden. Wählt der Kunde Sofort als Zahlungsverfahren und bestätigt seine Bestellung, beginnt die Kommunikation zwischen Ihrem Shop und unserer Schnittstelle (API). Bevor einzelne Schritte des Prozesses von Sofort inklusive der API-Aufrufe detailliert beschrieben werden, folgen einige Rahmenbedingungen, die für eine erfolgreiche Ausführung von Sofort notwendig sind.

3.1 Einbindung von Sofort im Checkout

Zur Einbindung von Sofort im Checkout, ist es notwendig bei der Auswahl der Zahlungsverfahren eine weitere Option für Sofort hinzuzufügen (bspw. als neuer Radiobutton, Link, ... - Details hierzu finden Sie in der Dokumentation Ihres Shopsystems). Für eine Optimierung der Einbindung von Sofort finden Sie im Integration Center unter Werbemittel Logos, Banner sowie Infotexte und Links zu detaillierten Informationen für Ihre Kunden.

3.2 Kommunikation mit der Schnittstelle für Sofort

Der Aufruf unserer Schnittstelle (API) erfolgt aus Ihrem Shop durch ein HTTP POSThande mit angehängten XML-Parametern. Die Antworten bei Aufrufen unserer Schnittstelle sind ebenfalls XML-formatiert.

Die direkte Kommunikation mit unserer Schnittstelle über XML-HTTP Nachrichten läuft immer nach demselben Prinzip ab:
• (API-Schritt 1) Initialer Aufruf der API und Übergabe der Transaktionsparameter
• (API-Schritt 2) Antwort der API mit Zahlungs-URL, auf welche Sie den Kunden weiterleiten
• (API-Schritt 3) Benachrichtigung über eine Änderung des Transaktionsstatus
• (API-Schritt 4) Abruf der Transaktionsdaten
• (API-Schritt 5) Antwort auf den Abruf der Transaktionsdaten

Wenn Sie für die Integration die Programmiersprachen PHP oder Java verwenden, stellen wir dazu jeweils eine Programmier-Bibliothek (SofortLib) zur Verfügung, welche die Implementierung in Ihr System wesentlich erleichtert. Implementierungsbeispiele und eine kurze Anleitung zur Verwendung der SofortLib finden Sie im Integration Center.

3.3 Initialer Aufruf der API und Übergabe der Transaktionsdaten (API-Schritt 1)
3.3.1 Aufruf der API und Authentifizierung 

Um Missbrauch der Schnittstelle zu verhindern, wird für jeden Aufruf der Schnittstelle eine Authentifizierung durchgeführt. Hierzu wird Ihre Kundennummer als Benutzername und der API-Key als Passwort übergeben. Den API-Key können Sie im Anbietermenü unter Weitere Dienste → API-Key einsehen. Um die Schnittstelle verwenden zu können, müssen Sie folgende Dinge beachten, die im Anschluss erklärt werden:

  • Sie müssen die korrekte URL aufrufen und dabei HTTPS als Protokoll verwenden.
  • Sie müssen die korrekten Authentifizierungsinformationen übermitteln. Zur Authentifizierung wird die Basic-HTTP-Authentication (RFC 2617) verwendet.
  • Sie müssen die korrekten Content-Type Header angeben.
  • Ihre Daten müssen korrekt als XML formatiert sein (RFC 3023, siehe Parameterbeschreibung) und per HTTP POST verschickt werden.

Der Aufruf der Schnittstelle erfolgt über folgende URL:

https://api.sofort.com/api/xml
3.3.2 Übergabe der Transaktionsdaten

Für den Aufruf müssen verschiedene Parameter an unsere API übergeben werden. Einige Parameter sind dabei obligatorisch, andere können optional verwendet werden. Details zur Verwendung der einzelnen Parameter finden Sie in der Parameterübersicht.

Hinweis:

Die in allen Fällen verwendete Interface-Versionslogik ist im Folgenden:
<Interface_version>Shopsystem name_shopsystem version/Zahlungsmodul Name_Zahlungsmodul Version </interface_version>

Ein Beispiel kann wie folgt sein:
<Interface_version>Magento_2.1.4/Sofort_2.3.3</interface_version>

Falls Sie Ihr eigenes Shop-System aufgebaut haben, empfehlen wir Ihnen, die gleiche Schnittstellen-Logik zu verwenden.

Ein Beispiel kann wie folgt sein:
<Interface_version>MyShop/Sofort_0.1 </interface_version>
Oder
<Interface_version>OwnShop/Sofort_0.2</interface_version>

Im Folgenden wird nur die für die Schnittstellenversion verwendete Logik angezeigt, um kein Beispiel als Schnittstellenversion zu verwenden, die Sie übertragen müssen.

Ein beispielhafter Aufruf für Sofort könnte in XML formatiert so aussehen:

<?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>
      <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>
Übergabe des Verwendungszweckes für belgische Banken

Einige Banken in Belgien verwenden ein gesondertes Feld für den Verwendungszweck, wenn die ersten 12 Stellen des ersten Reason Parameters nur aus Ziffern bestehen.

Dadurch kann der Verwendungszweck auf dem Kontoauszug verfälscht werden und wertvolle Informationen können gegebenenfalls entfallen.

Deshalb empfehlen wir Ihnen bei Transaktionen in Belgien in den ersten 12 Zeichen des Parameters Reason mindestens einen Buchstaben zu verwenden. Sonderzeichen wie zum Beispiel Bindestriche werden nur als Unterteilung der Ziffern angesehen und verhindert die Verwendung dieses gesonderten Verwendungszweckes nicht.

3.3.3 Übergabe des Begünstigten für die Wire Transfer Regulation 2017

Wenn Sie im Rahmen der Wire Transfer Regulation (ab 26.6.2017) den Begünstigten für die jeweilige Transaktion übergeben müssen, können Sie dies über die <beneficiary> Parameter machen.

Hinweis:

Nachdem Banken aktuell für den Begünstigten in der Überweisung keine eigenen Felder zur Verfügung stellen, hängen wir die Werte direkt an den Verwendungszweck an, so dass der Verwendungszweck aus den Werten <reasons> und <beneficiary> besteht.

Bitte beachten Sie, dass nicht bei allen Banken der Verwendungszweck lang genug ist, um den Begünstigten mit anzuzeigen.

Ein beispielhafter Aufruf für Sofort könnte in XML formatiert so aussehen:

<?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 Antwort der API mit Zahlungs-URL, auf welche Sie den Kunden weiterleiten (API-Schritt 2)

Als Antwort auf diesen Aufruf erhalten Sie eine Transaktions-ID und den URL zur Abwicklung der Zahlung (Zahlformular) durch den Kunden. Leiten Sie Ihren Kunden auf den zurückgegebenen URL des Zahlformulars weiter. Dort wird Ihr Kunde aufgefordert, seine Bankdaten einzugeben und die Überweisung zu beauftragen. Anschließend wird Ihr Kunde direkt auf den übergebenen Erfolgslink (wieder in Ihrem Shop) oder bei Abbruch auf den spezifizierten Abbruchlink weitergeleitet. Die Parameter sowie deren Beschreibungen, die eine Antwort enthalten kann, finden Sie in der Parameterübersicht.

Eine beispielhafte Antwort der Schnittstelle könnte in XML formatiert so aussehen:

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

Sie sollten anschließend Ihren Kunden auf die im Parameter "payment_url" übergebene Seite leiten. Die Transaktions-ID wird im Parameter "transaction" übergeben. Diese Transaktions-ID sollten Sie mit der zugehörigen Bestellung speichern, um beispielsweise Transaktionsdaten später abfragen zu können.

3.5 Weiterleitung Ihres Kunden auf den Erfolgs-/Abbruchlink

Sofern die Überweisung mit Sofort erfolgreich durchgeführt wurde, wird Ihr Kunde auf den im Projekt hinterlegten bzw. im Aufruf (API-Schritt 1) übergebenen Erfolgslink weitergeleitet. Idealerweise wird ihm dabei in einer abschließenden Zusammenfassung die Bestellung inklusive der erfolgreichen Einstellung der Überweisung mit Sofort in seinem Online-Banking bestätigt. Im Hintergrund sollte Ihr Shopsystem inzwischen die Bestätigung der Transaktion erhalten haben (siehe API-Schritte 3, 4 und 5), den Warenkorb geleert und die Bestellung mit entsprechendem Status abgespeichert haben.

Sollte die Überweisung mit Sofort nicht erfolgreich beendet worden sein, so wird Ihr Kunde auf den Abbruchlink weitergeleitet. Dieser sollte idealerweise auf die Auswahl des Zahlungsverfahrens zurück leiten, während der Kunde nach wie vor seinen Warenkorb gefüllt hat.

3.6 Benachrichtigung über eine Änderung des Transaktionsstatus (API-Schritt 3)

Sofern die Überweisung mit Sofort erfolgreich durchgeführt wurde, werden Sie parallel zur Weiterleitung des Kunden auf den Erfolgslink, über die durchgeführte Transaktion benachrichtigt. Dies geschieht durch den Aufruf des Benachrichtigungs-URLs, den Sie entweder im Projekt hinterlegt haben, oder aber bereits im initialen Aufruf der Schnittstelle (API-Schritt 1) übergeben haben. In dieser Benachrichtigung wird die Transaktions-ID der Transaktion übergeben, deren Status sich geändert hat.

Eine beispielhafte Benachrichtigung der Schnittstelle könnte in XML formatiert so aussehen:

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

Sie erhalten eine Benachrichtigung bei jeder Statusänderung Ihrer Transaktion. Um den Grund für eine Statusänderung zu erfahren, initiieren Sie bitte eine Abfrage der Transaktionsdaten (siehe API-Schritt 4).

Die IP-Adresse von der die Benachrichtigung versendet wird finden Sie unter: https://www.sofort.com/payment/status/ipList.

3.7 Abruf der Transaktionsdaten (API-Schritt 4)

Als Reaktion auf eine Benachrichtigung sollten Sie anschließend die Transaktionsdaten abrufen. Hierzu können Sie entweder Transaktionsdaten zu konkreten Transaktions-IDs abrufen, oder aber alle Transaktionsdaten von Transaktionen eines angegebenen Zeitraums.

Zwei beispielhafte Anfragen von Transaktionsdaten könnten in XML formatiert so aussehen:

<?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 Antwort auf den Abruf der Transaktionsdaten (API-Schritt 5)

Es werden immer alle vorliegenden Daten zu abgerufenen Transaktionen zurückgegeben. Die Parameter sowie deren Beschreibungen, die eine Antwort enthalten kann, finden Sie in der Parameterübersicht. Sofern keine Transaktionen den übergebenen Suchkriterien aus API-Schritt 4 entsprechen, enthält die Antwort einen leeren <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>

Statusmeldungen

In der Antwort der Transaktionsdaten finden Sie die Benachrichtigung über den aktuellen Status der angeforderten Transaktion(en).

Eine Transaktion wird erst dann bei der Sofort GmbH angelegt, wenn die TAN Eingabe erfolgreich war und die Bank des Kunden die Einstellung der Überweisung im Online-Banking bestätigt hat. Sofern dies noch nicht erfolgt ist (bspw. wenn der Zahlvorgang noch andauert oder weil die Zahlung mit Sofort nicht durchgeführt werden konnte), bekommen Sie bei einer Anfrage der Transaktionsdaten zu einer übergebenen Transaktions-ID nur eine Antwort mit leerem <transactions /> Tag zurück. Das endgültige Scheitern einer Transaktion steht somit erst nach Ablauf der Gültigkeitsdauer (<timeout> aus API-Schritt 1) fest.

Sofern die Überweisung mit Sofort erfolgreich durchgeführt wurde, ist zu unterscheiden, ob Sie als Empfängerkonto ein Konto bei der Deutschen Handelsbank eingerichtet haben oder nicht. Im ersten Fall kann die Sofort GmbH den Geldeingang auf Ihrem Konto bestätigen bzw. Sie benachrichtigen, falls das Geld innerhalb einer bestimmten Frist nicht auf Ihrem Konto eingegangen ist. Im zweiten Fall, dass sie kein Konto bei der Deutschen Handelsbank als Empfängerkonto eingerichtet haben, wird ihnen nach erfolgreicher Durchführung der Überweisung mit Sofort immer der Status "untraceable" angezeigt.

Weitere Detailinformationen zu möglichen Status und deren Beschreibung finden Sie im Anhang.

3.9 Fehlermeldungen

HTTP Fehlermeldungen (bspw. 401 (-> keine Berechtigung, HTTP Authentication über Kundennummer, API-Key fehlgeschlagen), 404, ...)

Wenn eine Anfrage an die Schnittstelle fehlerhaft ist, erhalten Sie unterschiedliche Fehler zurück.

3.9.1 HTTP Fehlercodes

Fehlercode 401 Unauthorized erhalten Sie bspw. beim Aufruf mit fehlerhaften Authentifizierungsdaten (Base64-codierte Kombination aus Kundennummer und API-Key)

Fehlercode 404 Not Found erhalten Sie bspw. beim Aufruf der falschen URL

3.9.2 API Fehlercodes

Sofern der HTTP Aufruf inkl. Authentifizierung erfolgreich war (HTTP 200 OK) können Fehler innerhalb der übergebenen XML Daten weitere Fehlermeldungen erzeugen. Die einzelnen XML-Fehlercodes sowie deren Beschreibungen, die eine Antwort enthalten kann, finden Sie in der Fehlerübersicht. Eine beispielhafte Antwort mit Fehlercode und -beschreibung könnte XML-formatiert folgendermaßen aussehen.

<?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 id="h4">4. Testen

Um die Funktionalität Ihrer Integration der installierten Zahlarten komplett zu testen, führen Sie bitte eine Testüberweisung direkt über Ihr (Shop-)System aus. Befolgen Sie dabei folgende Schritte:

  • Testmodus aktivieren
  • Testtransaktion durchführen
  • Weiterleitung zum Shop und Benachrichtigung überprüfen

Beachten Sie, dass keine echte Überweisung veranlasst wird, sofern der Testmodus aktiviert ist und eine der angegebenen Testbankleitzahlen verwendet wird.

Auch im Testmodus sind Überweisungen möglich, sofern eine gültige Bankleitzahl einer Bank angegeben wird.

Für den produktiven Einsatz sollten Sie den Testmodus unbedingt deaktivieren.

4.1 Testmodus aktivieren

Aktivieren des Testmodus in Ihrem Projekt im Händlerbereich auf der Webseite der Sofort GmbH.

4.2 Testtransaktion durchführen
  • Führen Sie eine Bestellung aus Ihrem (Shop-)System heraus durch und wählen Sie die Zahlungsart Sofort.
  • Nachdem Sie auf das Zahlformular der Sofort GmbH geleitet wurden, überprüfen Sie die übergebenen Überweisungsdaten (Zahlungsempfänger inkl. Anschrift, Verwendungszweck, Betrag).
  • Geben Sie anschließend für deutsche Absenderkonten auf dem Zahlformular 88888888 (8x die Ziffer "8") als BLZ ein, für Belgien "Andere" wählen und 999 (3x die Ziffer "9") und für alle anderen Länder entweder 00000 (5x die Ziffer "0") oder "Demo Bank" auswählen. (In Kürze können Sie anstatt der Test-BLZ auch eine länderspezifische Test-BIC im Zahlformular eingeben: "SFRT{ISO-Länderkürzel}20XXX", z.B. für Deutschland "SFRTDE20XXX". Über die API können Sie diese bereits jetzt schon als <sender><bic> übergeben)
  • Die im Folgenden abgefragten Daten können Sie beliebig wählen, beachten Sie dabei eine Mindestlänge von vier Zeichen.
4.3 Weiterleitung/Benachrichtigung überprüfen

Sofern Sie eine Weiterleitung für den Erfolgs-/Abbruchfall oder eine Benachrichtigung eingerichtet haben, überprüfen Sie ob diese korrekt ausgeführt werden und Ihr System in der vorgesehenen Weise reagiert.

  • Wird nach der Transaktion auf die Bestätigungsseite geleitet?
  • Kommen alle Benachrichtigungen richtig an, sofern Sie aktiviert bzw. übergeben wurden?
  • Werden die Bestelldetails richtig abgefragt und eingelesen?
  • Wird der Bestell-/Bezahlstatus richtig gesetzt bzw. wird die Bestellung korrekt angelegt?
4.4 Checkliste für die Integration
  • Produkt aktiviert
  • Projekt angelegt
  • Zahlungsart im Projekt aktiviert
  • Test-Transaktion durchgeführt
  • Benachrichtigung für Test-Transaktion erhalten
  • Transaktionsdaten abgefragt und erhalten
  • evtl. Rückbuchungen implementiert und getestet

5. Parameterübersicht

Falls Sie die Programmier-Bibliothek (sofortLib) nicht verwenden, finden Sie hier die genaue XML-Schnittstellendokumentation.

Erklärung der Tabellenspalten der nachfolgenden Tabellen

  • Parameter: Name des XML-Tags, der übergeben wird (<parameter>parameter-inhalt</parameter>)
    Der logische Aufbau eines XML-Dokuments entspricht einer Baumstruktur und ist damit hierarchisch organisiert. Die Hierarchie wird in den Tabellen durch Einrückung veranschaulicht. Fett markierte Parameter symbolisieren Vaterknoten, welche ein oder mehrere Kindknoten haben.
  • Anzahl: gibt an, wie häufig ein Parameter unter seinem übergeordneten Parameter verwendet werden darf
    • [1] = Pflicht-Parameter
    • [0,1] = optionaler Parameter, es kann max. ein Wert übergeben werden
    • [0..20] = optionaler Parameter, es können bis zu 20 Werte übergeben werden
    • [n] = optionaler Parameter, es können beliebig viele Parameter übergeben werden
    • [1..n] = Pflicht-Parameter, es muss mindestens einer und können beliebig viele Parameter übergeben werden
  • Typ (Länge): gibt den Datentyp des Parameter-Inhalts an, sofern dies ein String ist, wird die maximal erlaubte Zeichenanzahl angegeben
  • Erklärung: detaillierte Beschreibung der Verwendung des Parameters
5.1 (API-Schritt 1) Initialer Aufruf der API und Übergabe der Transaktionsparameter
5.1.1 Aufruf der API und Authentifizierung

Der Aufruf der Schnittstelle erfolgt über folgenden URL:

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

Zur Authentifizierung wird die Basic-HTTP-Authentication (RFC 2617) verwendet. Als Benutzername verwenden Sie bitte Ihre Kundennummer (bspw. 99999) und als Passwort Ihren API-Key (bspw. a12b34cd567890123e456f7890123456), die Sie durch ":" getrennt aneinander fügen und mit Base64 codieren (base64(99999:a12b34cd567890123e456f7890123456)).

Bei jeder Anfrage muss im HTTP Header sowohl das Feld Content-Type als auch das Feld Accept mit "application/xml" belegt werden.

Ein resultierender Beispiel HTTP-Header sieht dann wie folgt aus:

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

Sofern die Authentifizierung erfolgreich war, bestätigt der Server Ihren API-Aufruf mit HTTP 200 OK.

Der Inhalt der Nachrichten muss korrekt als XML formatiert sein. Die möglichen Parameter werden im Folgenden detailliert beschrieben.

Hinweis: Bei jedem der im Folgenden beschriebenen Aufrufe der API müssen Sie den oben angegebenen URL verwenden und sich wie beschrieben authentifizieren.

5.1.2 Zahlungsdatenübergabe

Diese Tabelle enthält alle möglichen Parameter, die Sie in einer Anfrage an unser System übergeben können.

Parameter Anzahl Typ (Länge) Erklärung
multipay [1] Container Identifiziert den Sofort API-Aufruf, umschließt die komplette Nachricht
  project_id [1] Integer Projektnummer
  interface_version [0,1] String (255) Identifiziert die Shop-Systemversion und das Zahlungsmodul, indem sie die Daten in diesem Format anfordert: <interface_version> shopsystem name_shop system version / module name_payment-module version </ interface_version>
  language_code [0,1] String (2) Sprache des Zahlformulars, nach ISO 639-1 z.B. "DE"; steht in Wechselwirkung zu <sender><country_code> und sollte nur verwendet werden, wenn eine bestimmte Sprache erzwungen werden soll. Sonst werden Informationen wie Browsersprache etc. zur Bestimmung der Sprache des Zahlformulars herangezogen.
  timeout [0,1] Integer Gültigkeit der Transaktion in Sekunden von Generierung der Nachricht new_transaction am Sofort Gateway bis zum Einstellen der Überweisung / Lastschrift / etc.; default: unbeschränkt
  email_customer [0,1] String (255) E-Mail-Adresse Ihres Kunden; z.B. für Rechnung, Vorkasse
  phone_customer [0,1] String (255) Telefonnummer Ihres Kunden (beginnt mit "+"; mögliche Zeichen: "0-9 , - / ( )", keine Buchstaben! )
  user_variables [0,1] Container Liste mit Benutzervariablen
    user_variable [0..20] String (255) Benutzervariable
  sender [0,1] Container Daten des Absenders (Bankkonto Ihres Kunden)
    holder [0,1] String (27) Kontoinhaber
    iban [0,1] String (34) IBAN
    bic [0,1] String (11) BIC
    account_number [0,1] String (30) DEPRECATED: Kontonummer, bitte <iban> benutzen
    bank_code [0,1] String (30) DEPRECATED: BLZ, bitte <bic> benutzen
    country_code [0,1] String (2) Länderkürzel nach ISO 3166-1; z.B. "de"
  amount [1] Decimal (8.2) Betrag, Format: keine Tausender-Trennzeichen, zwei Nachkommastellen, mit Punkt "." getrennt. Beispiel "1150.00" (1.150,00 EUR). Beachten Sie bitte, dass bei Übergabe von "HUF" als currency_code bei Angabe von Nachkomma-Stellen auf ganze Zahlen gerundet wird (z.B. 1000.50 > 1001 und 1000.49 > 1000).
  currency_code [1] String (3) Währung nach nach ISO 4217, z. B.: "EUR"
  reasons [1] Container Liste mit Verwendungszwecken
    reason [1..2] String (27)*

Verwendungszweck; bitte übergeben Sie einen eindeutigen Wert (z. B. Bestellnummer und Kundennummer, "BNr018293 KNr00131") nur folgende Zeichen erlaubt: '0-9', 'a-z', 'A-Z', ' ', '+', ',', '-', '.'. Umlaute werden ersetzt, also z.B. ä -> ae. Andere Zeichen werden für die Darstellung auf unserer Zahlungsseite sowie für Benachrichtigungen entfernt. Bei der Rückleitung (Erfolgs- und Abbruchlink und Benachrichtigungen) kann deshalb ein veränderter String für reason zurückgegeben werden. Sofern die Transaktionsnummer der Überweisung mit Sofort im Verwendungszweck genutzt werden soll, kann der Ersetzungsparameter '-TRANSACTION-' verwendet werden.

Wichtig: Da manche Banken nicht die vollständigen beiden Verwendungszwecke anzeigen, sondern bspw. in Kontoauszügen ggf. schon vorher abschneiden, empfiehlt es sich, die wichtigsten eindeutigen Daten bereits zu Beginn des ersten Verwendungszwecks zu schreiben.

* Da Banken im Vereinigten Königreich (GB) nur 18 Zeichen pro Verwendungszweck verarbeiten, empfiehlt sich bei Integrationen für diesen Markt diese Einschränkung zu berücksichtigen.

  success_url [0,1]* String (255)

Erfolgslink, überschreibt den Defaultwert aus den Projekteinstellungen. Wird aufgerufen, wenn Ihr Kunde die Überweisung mit Sofort erfolgreich abgeschlossen hat und die Überweisung in seinem Online-Banking eingestellt wurde. Sofern die Transaktionsnummer der Überweisung mit Sofort als Teil der URL genutzt werden soll, kann der Ersetzungsparameter '-TRANSACTION-' verwendet werden.

* Sofern kein Erfolgslink in den Projekteinstellungen hinterlegt ist, wird dies zum Pflichtparameter

  success_link_redirect [0,1] Boolean Autom. Weiterleitung auf Erfolgsseite. Sofern nicht aktiviert, wird Ihrem Kunden eine Zusammenfassungsseite der Sofort GmbH angezeigt. Überschreibt Projekteinstellungen.
  abort_url [0,1]* String (255)

Abbruchlink, überschreibt den Defaultwert aus den Projekteinstellungen. Wird aufgerufen, wenn die Überweisung mit Sofort nicht erfolgreich abgeschlossen werden konnte (bspw. durch Abbruch Ihres Kunden, bzw. bei Kontounterdeckung). Sofern die Transaktionsnummer der Überweisung mit Sofort als Teil der URL genutzt werden soll, kann der Ersetzungsparameter '-TRANSACTION-' verwendet werden.

* Sofern kein Abbruchlink in den Projekteinstellungen hinterlegt ist, wird dies zum Pflichtparameter

  timeout_url [0,1] String (255) Timeoutlink, überschreibt den Defaultwert aus den Projekteinstellungen. Wird aufgerufen wenn der in den Projekteinstellungen hinterlegte Timeoutwert auf dem Zahlformular abgelaufen ist. Sofern die Transaktionsnummer der Überweisung mit Sofort als Teil der URL genutzt werden soll, kann der Ersetzungsparameter '-TRANSACTION-' verwendet werden.
  notification_urls [0,1] Container Liste mit Benachrichtigungslinks
    notification_url [0..5] String (255) Benachrichtigungslink. Sofern die Transaktionsnummer der Überweisung mit Sofort als Teil der URL genutzt werden soll, kann der Ersetzungsparameter '-TRANSACTION-' verwendet werden.
    notification_url notify_on=“xyz“ [0..5] String (255) Benachrichtigungslink; Durch Ersetzung des Parts "xyz" durch einen speziellen Status, wird für Benachrichtigungen mit diesem Status nur diese URL verwendet. Es können mehrere kommaseparierte Status angegeben werden. Bspw: <notification_url notify_on="pending, loss">. Mögliche Status sind "received", "loss", "refunded" und "pending" (wobei "pending" für die äquivalenten Status "pending - not_credited_yet" und "untraceable - sofort_bank_account_needed" zutrifft. Details siehe auch im unteren Abschnitt).
  notification_emails [0,1] Container Liste mit Benachrichtigungs-E-Mail-Adressen
    notification_email [0..10] String (255) Benachrichtigungs-E-Mail-Adressen
    notification_email notify_on=“xyz“ [0..10] String (255) Benachrichtigungsmail; Durch Ersetzung des Parts "xyz" durch einen speziellen Status, wird für Benachrichtigungen mit diesem Status nur diese Email-Adresse verwendet. Es können mehrere kommaseparierte Status angegeben werden. Bspw: <notification_url notify_on="pending, loss">. Mögliche Status sind "received", "loss", "refunded" und "pending" (wobei "pending" für die äquivalenten Status "pending - not_credited_yet" und "untraceable - sofort_bank_account_needed" zutrifft. Details siehe auch im unteren Abschnitt).
       
  su [1] Container Container für spezielle Parameter von Sofort. Ist für den Aufruf einer Überweisung mit Sofort immer notwendig und kann auch ohne Inhalt verwendet werden: <su />
  beneficiary [0,1] Container Container für spezielle Parameter von Sofort.
    identifier [0,1] String (27) Begünstigter
    country_code [0,1] String (2) Land des Begünstigten

Tabelle 1: Parameterdefinition des initialen Aufrufs und Übergabe der Transaktionsparameter (API-Schritt 1)

5.2 (API-Schritt 2) Antwort der API mit Zahlungs-URL, auf welche Sie den Kunden weiterleiten

Als Antwort auf den Aufruf unserer Schnittstelle erhalten Sie eine Transaktionsnummer und einen URL, auf den Sie den Kunden weiterleiten. U.U. Enthält die Antwort auch Warnungen.

Parameter Anzahl Typ (Länge) Erklärung
new_transaction [0,1] Container Identifiziert die Antwort auf den initialen Aufruf zur Übergabe der Transaktionsparameter, umschließt die komplette Nachricht
  transaction [1] String (27) Die generierte Transaktionsnummer
  payment_url [1] String (255) Url des Zahlformulars
  su [0,1] Container Sofort
    warnings [0,1] Container Liste mit Warnungen
      warning [1..n] Container Warnung, nicht kritische Fehler
        code [1] Integer Warnungsnummer
        message [1] String(255) Warnungsmeldung
errors [0,1] Container Fehler (Definition siehe unten) - kann alternativ zum Tag <new_transaction> zurückgegeben werden
  ...      

Tabelle 2: Parameterdefinition der Antwort mit Zahlungs-URL (API-Schritt 2)

5.3 (API-Schritt 3) Benachrichtigung über eine Änderung des Transaktionsstatus

Nach Abschluss einer Transaktion oder im Falle einer Statusänderung erhalten Sie eine Nachricht, die folgende Parameter enthält.

Parameter Anzahl Typ (Länge) Erklärung
status_notification [1] Container Identifiziert eine Statusänderung einer Transaktion, umschließt die komplette Nachricht
  transaction [1] String (27) Die Transaktionsnummer
  time [1] String (25) Datum und Uhrzeit (mit Zeitzone) nach ISO 8601 im Format YYYY-MM-DDThh:mm:ss+HH:mm, z. B. 2013-03-14T11:38:00+02:00

Tabelle 3: Parameterdefinition der Benachrichtigung über eine Änderung des Transaktionsstatus (API-Schritt 3)

5.4 (API-Schritt 4) Abruf der Transaktionsdaten

Wenn Sie weitergehende Details zu der Statusänderung erfahren möchten, stellen Sie eine Transaktionsdetailanfrage, die folgende Parameter beinhalten kann. Sie können entweder Details zu konkreten Transaktionsnummern anfragen (<transaction>), oder aber zu einem bestimmten Zeitraum und weiteren Filterkriterien, in dem die Transaktionen erstellt wurden.

Hinweis zum Datenabruf für einen bestimmten Zeitraum:

Sie können je Abfrage höchstens 100 Transaktionsdatensätze abrufen, auch wenn Sie den Parameter <number> nicht übergeben (dann gilt der Default-Wert 100).

Zeiträume, die mehr als 100 Transaktionen umfassen, erfordern iterative Abfragen mit <page>1</page>, <page>2</page> etc.

Parameter Anzahl Typ (Länge) Erklärung
transaction_request (mit Attribut version="2") [1] Container Identifiziert den Abruf von Transaktionsdaten, umschließt die komplette Nachricht. Bitte achten Sie darauf das Attribut version="2" zu übergeben, andernfalls erhalten Sie abweichende Statusmeldungen als in diesem Handbuch beschrieben.
  transaction [0..100] String (27) Transaktionsnummer; es können mehrere gleichzeitig abgefragt werden
  from_time [0,1] String (25)

Start eines Zeitintervalls, falls keine Transaktionsnummer übergeben wurde. Default: [Aufruftag] 00:00 Uhr

Format nach ISO 8601 YYYY-MM-DD bzw. YYYY-MM-DDThh:mm:ss+HH:mm

  to_time [0,1] String (25)

Ende eines Zeitintervalls, falls keine Transaktionsnummer übergeben wurde. Default: [Aufrufzeitpunkt]

Format nach ISO 8601 YYYY-MM-DD bzw. YYYY-MM-DDThh:mm:ss+HH:mm

  from_status_modified_time [0,1] String (25)

Start eines Zeitbereiches, falls keine Transaktionsnummer übergeben wurde. Die Zeitraumangabe bezieht sich auf Transaktionen die
innerhalb dieses Zeitraumes die letzte Statusänderung erfahren haben.

Default: Aufruftag 0:00 Uhr.
Format nach ISO 8601: YYYY-MM-DD bzw. YYYY-MM-DDThh:mm:ss+HH:mm

  to_status_modified_time [0,1] String (25)

Ende eines Zeitbereiches, falls keine Transaktionsnummer übergeben wurde. Die Zeitraumangabe bezieht sich auf Transaktionen die
innerhalb dieses Zeitraumes die letzte Statusänderung erfahren haben.

Default: Aufruftag 0:00 Uhr.
Format nach ISO 8601: YYYY-MM-DD bzw. YYYY-MM-DDThh:mm:ss+HH:mm

  status [0,1] String Status, auf den die ausgegebenen Transaktionen eingeschränkt werden sollen.
  status_reason [0,1] String Status Reason, auf den die ausgegebenen Transaktionen eingeschränkt werden sollen.
  product [0,1] String Produkt, auf das die ausgegebenen Transaktionen eingeschränkt werden soll ("payment": Sofort, "paycode": Paycode)
  number [0,1] Integer Anzahl an Transaktionen die zurückgegeben werden sollen (bei Abfrage nach Zeitraum). Default/Max: 100
  page [0,1] Integer

Falls number benutzt wird, können mit diesem Parameter die folgenden Transaktionen abgefragt werden. Default: 1

Bsp.: number=10, page=2 → Transaktionen 11-20 werden ausgegeben

Tabelle 4: Parameterdefinition des Abrufs der Transaktionsdaten (API-Schritt 4)

5.5 (API-Schritt 5) Antwort auf den Abruf der Transaktionsdaten

Die Tabelle gibt einen Überblick über alle Parameter, die in einer Transaktionsdetailnachricht enthalten sein kann.

Parameter Anzahl Typ (Länge) Erklärung
transactions [0,1] Container Identifiziert die Antwort auf einen Abruf von Transaktionsdaten, umschließt die komplette Nachricht
  transaction_details [0..n] Container Details einer Transaktion
    project_id [1] Integer Projektnummer
    transaction [1] String (27) Transaktionsnummer
    test [1] Boolean Test-Transaktion ("0" für false, "1" für true)
    time [1] String (25) Datum und Uhrzeit der Transaktionserstellung (mit Zeitzone) nach ISO 8601 im Format YYYY-MM-DDThh:mm:ss+HH:mm z.B. "2013-03-14T13:02:10+01:00"
    status [1] String (20) Statuscode der Transaktion (siehe Statuscodes)
    status_reason [1] String (255) Grund des Status
    status_modified [1] String (25) Datum und Uhrzeit der letzten Statusänderung (mit Zeitzone) nach ISO 8601 im Format YYYY-MM-DDThh:mm:ss+HH:mm, z.B. "2013-03-14T13:17:10+01:00"
    payment_method [1] String (7) Zahlmethode die benutzt wurde ("su" für Sofort - weitere: paycode)
    language_code [1] String (2) Sprache, nach ISO 639-1
    amount [1] Decimal (8.2)

Überweisungsbetrag

Beachten Sie, dass wenn als currency_code "HUF" gesetzt ist und im API-Schritt 1 ein Dezimal-Wert als Betrag übergeben wurde, dieser auf die nächstliegende Ganzzahl gerundet wird (z.B. 1000.50 > 1001 und 1000.49 > 1000).

    amount_refunded [0,1] Decimal (8.2) Zurück überwiesener Betrag
    currency_code [1] String (3) Währung nach ISO 4217, z. B. "EUR"
    reasons [1] Container Liste mit Verwendungszwecken
      reason [0..2] String (255) Verwendungszweck
    user_variables [1] Container Liste mit Benutzervariablen
      user_variable [0..20] String (255) Benutzervariable
    sender [1] Container Daten des Überweisungs-Absenders (Bankkonto Ihres Kunden) - Diese Werte können aus den Angaben des Kunden ergänzt bzw. berechnet werden, daher kann für die Korrektheit nicht garantiert werden.
      holder [1] String (255) Kontoinhaber
      account_number [1] String (30) Kontonummer
      bank_code [1] String (30) BLZ
      bank_name [1] String (255) Name der Bank
      bic [1] String (11) BIC
      iban [1] String (34) IBAN
      country_code [1] String (2) Länderkürzel nach ISO 3166-1
    recipient [1] Container Daten des Überweisungs-Empfängers (Bankkonto des Anbieters)
      holder [1] String (27) Kontoinhaber
      account_number [1] String (30) Kontonummer
      bank_code [1] String (30) BLZ
      bank_name [1] String (255) Name der Bank
      bic [1] String (11) BIC
      iban [1] String (34) IBAN
      country_code [1] String (2) Länderkürzel nach ISO 3166-1
    email_customer [1] String (255) Endkundenmailadresse, z. B. für Rechnung
    phone_customer [1] String (255) Endkundentelefonnummer (Beginnt mit "+"; mögliche Zeichen: "0-9 , - / ( )" - keine Buchstaben! )
    exchange_rate [1] Decimal (8.4) Umrechnungskurs
    costs [1] Container Daten für Gebühren
      fees [1] Decimal (8.2) Gebühren, die bei der angefragten Transaktion anfallen
      currency_code [1] String (3) Währung nach ISO 4217, z.B. "EUR"
      exchange_rate [1] Decimal (8.4) Umrechnungskurs
    su [0,1] Container Sofort
    status_history_items [1] Container Container für Einträge der Statushistorie
      status_history_item [0...n] Container Unterkategorie für einzelne, vergangene Statuseinträge
        status [1] String (20) Statuscode der Transaktion (siehe Statuscodes)
        status_reason [1] String (255) Grund des Status
        time [1] String (25) Zeitpunkt des gesetzten Status nach ISO 8601 im Format YYYY-MM-DDThh:mm:ss+HH:mm, z.B. "2013-03-14T13:02:10+01:00"
errors [0,1] Container Fehler (Definition siehe unten) - kann alternativ zum Tag <transactions> zurückgegeben werden
  ...      

Tabelle 5: Parameterdefinition der Antwort auf den Abruf der Transaktionsdaten (API-Schritt 5)

Status messages

In einer Transaktionsdetailnachricht ist stets der Status und der Status Grund (status_reason) der Transaktion enthalten. Sofern ein Konto bei der der Deutschen Handelsbank als Empfängerkonto für die Sofort Überweisungstransaktionen verwendet wird, können folgende Status auftreten:

<transactions><transaction_details><status> <transactions><transaction_details><status_reason> Bedeutung
loss not_credited Das Geld ist nicht eingegangen.
pending not_credited_yet Das Geld ist noch nicht eingegangen.
received credited Das Geld ist eingegangen.
refunded compensation Das Geld wurde zurückerstattet (Teilrückbuchung).
refunded refunded Das Geld wurde zurückerstattet (komplette Rückbuchung des Gesamtbetrags).

Tabelle 6: Statusmeldungen für Transaktionen mit Sofort und Deutschem Handelsbank-Konto

Im Fall, dass das Empfängerkonto kein Deutsches Handelsbank-Konto ist können folgende Status auftreten:

<transactions><transaction_details><status> <transactions><transaction_details><status_reason> Bedeutung
untraceable sofort_bank_account_needed Die Transaktion mit Sofort wurde erfolgreich abgeschlossen. Weitere Statusmeldungen über Erhalt des Betrages auf dem Konto o.ä. sind nur mit Konto bei der Deutschen Handelsbank möglich.
Hinweis: sofern noch der überholte (deprecated) Aufruf <transaction_request> ohne Angabe des Versionsattributs mit Wert "2" an die API gesendet wird, wird als <status> statt "untraceable" der Wert "pending" mit <status_reason> "not_credited_yet" zurückgegeben.
refunded compensation Das Geld wurde zurückerstattet (Teilrückbuchung).
refunded refunded Das Geld wurde zurückerstattet (komplette Rückbuchung des Gesamtbetrags).

Tabelle 7: Statusmeldungen für Transaktionen mit Sofort ohne Konto bei der Deutschen Handelsbank

Es ist zu beachten, dass wenn eine Sofort Überweisungstransaktion erfolgreich abgeschlossen wurde und die Sofort GmbH die Bestätigung der Bank des Käufers erhalten hat, dies durch den Status "untraceable - sofort_bank_account_needed" (ohne Konto bei der Deutschen Handelsbank) oder "pending - not_credited_yet" (mit Konto bei der Deutschen Handelsbank) berichtet wird. Beide Status haben die äquivalente Bedeutung und stellen somit die Echtzeit-Transaktionsbestätigung dar, die durch das Shopsystem des Händlers weiterverarbeitet werden muss.

Fehlermeldungen/Warnung

Falls es zu einem Fehler oder Warnung kommt, erhalten Sie einen entsprechenden Fehlercode in der Meldung.

Parameter Anzahl Typ (Länge) Erklärung
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
  su [0,1] Container Fehlerliste für spezifische Fehlerbeschreibung der Überweisung mit Sofort
    errors [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

Tabelle 8: Antwort bei Fehler

Fehlercodes

Allgemeine Fehler bei Aufruf

Code Message Beschreibung
1000 Invalid request. Ungültige Anfrage
1001 Technical error. Technischer Fehler
7000 Invalid XML Ungültiges XML
7004 XML parameter not provided in request POST Daten wurden leer übergeben.
7005 Project has no Deutsche Handelsbank account. Kein Deutsches Handelsbank Konto für das Projekt hinterlegt.
7006 Service temporarily unavailable due to maintenance Der Service der Sofort GmbH/Deutschen Handelsbank ist aufgrund von Wartungsarbeiten vorübergehend nicht verfügbar.

Tabelle 9: Allgemeine Fehler

Spezielle Fehler/Warnungen bei Aufruf

Code Message Kommentar
8000 No project ID provided Es wurde keine Projekt-ID übergeben
8001 Unknown project Unbekanntes Projekt
8002 Validation Error Ein übergebener Parameter konnte nicht validiert werden.
8003 Request could not be processed Auf Grund eines Fehlers konnte auf die Transaktionsanfrage nicht geantwortet werden.
8004 No product is selected Im Aufruf wurde kein Produktelement (<su/>) übergeben.
8006 Logic error. z.B. ist das Projekt nicht aktiviert und nicht im Testmodus, das angefragte Produkt ist nicht aktiviert oder die Daten im Aufruf widersprechen den Projekteinstellungen
8010 must not be empty Das aufgeführte Feld darf nicht leer sein.
8011 not in list of valid values Der übergebene Wert ist nicht in der Liste der erlaubten Werte.
8012 must be a positive number Der übergebene Wert ist keine positive Zahl. Beispielsweise die Anzahl Items einer Warenkorbposition.
8013 unsupported currency Die übergebene Währung wird vom System nicht unterstützt. Derzeit werden nur EUR, GBP, CHF, PLN, HUF und CZK akzeptiert.
8014 invalid amount Der übergebene Betrag muss positiv sein und darf höchstens 2 stellen hinter dem Komma aufweisen. Als Dezimaltrennzeichen wird ein ".", sowie "," akzeptiert.
8015 amount is out of range Der übergebene Betrag ist zu groß oder zu klein.
8016 must be a valid url Die übergebene URL ist ungültig.
8017 invalid chars Der übergebene Wert enthält Zeichen, die nicht akzeptiert werden. Bspw. sind nur bestimmte Zeichen im Verwendungszweck zulässig.
8018 maximum length of 27 chars exceeded Zulässige Anzahl an Zeichen überschritten. Ggf. werden überzählige Zeichen entfernt (bspw. Verwendungszweck)
8019 invalid email address Ungültige Email
8021 invalid country code Wert muss gemäß ISO-3166 übergeben werden.
8022 unsupported country code Übergebener Ländercode wird von unserem System nicht unterstützt.
8023 invalid BIC Ungültiger BIC
8025 must be 2 or 3 // salutation Herr = 2, Frau = 3.
8026 must be a boolean, either 0 or 1 Als Wert muss 0 oder 1 angegeben werden.
8027 product not activated and not in testmode Die angefragte Zahlart steht nicht zur Verfügung, da der Testmodus deaktiviert ist und die Zahlart noch nicht freigeschaltet wurde.
8028 locked_sender_country_id is activated in project settings, but not provided

In den Einstellungen der Zahlart wurde festgelegt, dass das Absenderland während

des Zahlvorgangs vom Endkunden nicht mehr geändert werden darf. Bei der

Zahlungsinitiierung muss das Absenderland dann aber angegeben werden.

8040 No amount with comma allowed for HU. Es wurde ein Betrag mit Nachkommastellen übergeben, der auf eine ganze Zahl kaufmännisch ab-/aufgerundet wurde (siehe <amount>).
8045 product in testmode and given bank_code is not a test bank code Kontonummer, Bankleitzahl und Kontoinhaber übergeben. Da die Zahlart im Testmodus läuft, muss eine der Testbankleitzahlen angegeben werden (bspw. 00000).
8046 validation of given bank account and bank code failed In den Einstellungen der Zahlart wurde festgelegt, daß die Absenderdaten während des Zahlvorgangs vom Endkunden nicht mehr geändert werden dürfen. Die übergebenen Kontodaten konnten aber nicht validiert werden.
8047 Maximum length of 255 characters exceeded. Maximale Zeichenzahl von 255 Zeichen überschritten.
8049 unsupported language Die übergebene Sprache wird vom System nicht unterstützt.
8050 value too small. setting timeout to minimum value. Der übergebene Wert für die Dauer des Zahlvorgangs war zu klein und wird auf den kleinsten erlaubten Wert gesetzt (120 sekunden)
8051 invalid items found Die Anfrage enthielt ungültige Warenkorbpositionen
8054 all products deactivated due to errors. Initiation aborted Alle angefragten Zahlarten wiesen Validierungsfehler auf. Die Zahlsession konnte nicht initiiert werden.
8057 activate this product in your project settings Die angefragte Zahlart ist für das Projekt nicht aktiviert. Der Händler muss die Zahlart im Anbietermenü aktivieren, um die Zahlart nutzen zu können.
8058 payment not possible with this service Die Zahlung kann für diesen Dienst nicht verwendet werden.
8059 sender country not supported for this currency Für das angegebene Absenderland sind keine Zahlungen in der gewünschten Währung möglich.
8060 Blacklisted Die Zahlung kann nicht ausgeführt werden, da das Land durch den Händler gesperrt wurde.
8063 No success_url provided in request and in project settings Erfolgslink ist weder im request noch in den Einstellungen gesetzt.
8064 No abort_url provided in request and in project settings Abbruchlink ist weder im request noch in den Einstellungen gesetzt.
8072 maximum number of notification exceeded Es wurden zu viele Benachrichtigungs-URLs bzw. Benachrichtigungs-E-Mail-Adressen übergeben.
8073 Maximum number of user variables exceeded Es wurden zu viele User Variablen übergeben.

Tabelle 10: Spezielle Fehler/Warnungen

Fehler bei der Abfrage der Transaktionsdetails

Code Message Beschreibung
7999 Out of range (Too many entries or invalid values for the site) Zu viele Einträge pro Seite oder invalider Wert für die Seite
8005 Too many transactions requested Zu viele Transaktionen angefragt
8007 Invalid date format. Format is YYYY-MM-DD [HH:MM:SS] Ungültiges Datumsformat
8008 from_time equals to_time Die Daten from/to müssen sich unterscheiden
8009 max date range exceeded Suchzeitraum zu groß (möglicher Zeitraum umfasst max. 30 Tage)

Tabelle 11: Fehler bei der Abfrage der Transaktionsdetails Sofort Gateway

Mögliche HTTP-Statuscodes der Schnittelle

200 OK: Nachricht akzeptiert

401 Unauthorized: keine Berechtigung, z.b. falscher API-Key

404 Not Found: aufgerufener URL nicht vorhanden, bspw. beim Aufruf des falschen URLs

6. Support & Kontakt

Das Team der Sofort GmbH steht Ihnen zur Verfügung, sollten Sie Hilfe benötigen.

Sie können uns eine E-Mail an service@sofort.com schreiben.

Auch bei technischen Fragen helfen wir Ihnen gerne weiter:

Technische Beratung:
Telefon: +49 (0)89 24 88 37 691
E-Mail: integration@sofort.com

Geschäftszeiten:
Montag-Donnerstag: 08:30-18:00 Uhr
Freitag: 08:30-17:00 Uhr

7. Impressum

Sofort GmbH
Theresienhöhe 12
80339 München
Deutschland

Informationen für Käufer und Online-Shopper:
Telefon: +49 (0)89 24 88 37 690

Informationen für Verkäufer und Händler:
Telefon: +49 (0)89 24 88 37 692

info@sofort.com
www.sofort.com

Geschäftsführung

Felix Würtenberger
Wilhelmus Geerling Klaassen

Externer Datenschutzbeauftragter

Hr. Michael Schramm, LL.M. 
Für Fragen zum Datenschutz wenden Sie sich bitte an: datenschutz@sofort.com

Eingetragen beim Amtsgericht München
HRB 218675
USt-ID: DE248376956

© Sofort GmbH. Alle Rechte, einschließlich der Übersetzung, vorbehalten.

Die Dokumentation einschließlich aller veröffentlichten Inhalte ist urheberrechtlich geschützt. Nachdruck oder Reproduktion jeglicher Art sowie die Verarbeitung, Vervielfältigung und Verbreitung unter Verwendung elektronischer Systeme in irgendeiner Form bedarf der vorherigen schriftlichen Genehmigung der Sofort GmbH.

Die Verwendung dieser Dokumentation und die Umsetzung der darin enthaltenen Angaben erfolgt ausdrücklich auf eigenes Risiko. Die Sofort GmbH übernimmt keine Gewähr für die Funktion einzelner Programme oder von Teilen derselben. Insbesondere übernimmt die Sofort GmbH keine Haftung für etwaige, aus dem Gebrauch resultierende Folgeschäden.