API Dokumentation

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.

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.

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.

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.

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

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>

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

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.

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.

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.

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.

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.

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:

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:

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

Fehlermeldungen/Warnung

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

Tabelle 8: Antwort bei Fehler

Fehlercodes

Allgemeine Fehler bei Aufruf

Tabelle 9: Allgemeine Fehler

Spezielle Fehler/Warnungen bei Aufruf

Tabelle 10: Spezielle Fehler/Warnungen

Fehler bei der Abfrage der Transaktionsdetails

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.