Händler-Login

API Dokumentation

Rückbuchungen

1. Allgemeines

Rückbuchungen sind für folgende Produkte möglich:

  • SOFORT Überweisung
  • SOFORT Überweisung Paycode
  • iDEAL

Es werden zwei verschiedene Rückbuchungsverfahren angeboten:

  • Rückbuchungen über das Anbietermenü
  • Rückbuchungen über die XML-API (= XML-Schnittstelle)

Sie können entweder vollständige Rückbuchungen oder Teilrückbuchungen im SOFORT System einstellen.

1.1. Voraussetzungen für Rückbuchungen

Rückbuchungen können nur ausgeführt werden, wenn folgende Voraussetzungen erfüllt sind:

  • Zur Nutzung ist für den Anbieter/Händler ein Konto aus einem der folgenden Länder erforderlich: DE, AT, CH, NL, PL, BE, IT, ES ≈(GB wird derzeit noch nicht unterstützt)
  • Die Währung der urspr. Transaktionen ist EUR, CHF, PLN oder und das Absenderkonto (Käufer) befindet sich in einer der folgenden Länder: DE, AT, CH, NL, PL, BE, IT, ES (GB wird derzeit noch nicht unterstützt)
  • Die urspr. Transaktion ist nicht älter als 3 Monate
  • Vorhandensein folgender Daten des Absenderkontos (Käufer):
    • Kontoinhaber
      Hinweis: Der Kontoinhaber wird nur aus dem Online-Banking ermittelt. Der übergebene Kontoinhaber wird bei der Rückgabe an den Händler/Anbieter ignoriert
    • BIC
    • IBAN

Hinweis:

Liegen die in oben genannten Daten für eine Rückbuchung nicht vor, so führen Sie die Rückbuchung bitte direkt bei Ihrer Bank aus.

Besonderheit bei Zahlungseingang auf ein Konto bei der Deutschen Handelsbank:

Wird der Zahlungseingang einer Transaktion auf einem Konto bei der Deutschen Handelsbank erwartet, welches im Projekt hinterlegt ist, werden fehlende Informationen, die jedoch für eine Rückbuchung vorausgesetzten werden (s.o.), ergänzt. Sie können Rückbuchungen für Transaktionen nur durchführen, wenn das Geld auf Ihrem Konto bei der Deutschen Handelsbank bereits eingegangen ist (gekennzeichnet durch grünen Punkt vor der Transaktion).

1.2. Phasen einer Rückbuchung

Im Folgenden wird der Ablauf einer Rückbuchung in den einzelnen Phasen dargestellt.

Phasen_Rückbuchung_DHB

Die einzelnen Schritte einer Phase unterscheiden sich z.T. in Abhängigkeit folgender Faktoren und werden im weiteren Verlauf des Dokuments näher erläutert:

  • Rückbuchungsverfahren
    • über Anbietermenü
    • über XML-API
  • Bankkonto des Anbieters
    • Kein Konto bei der Deutschen Handelsbank vorhanden
    • Mit Konto bei der Deutschen Handelsbank

Da der Anbieter grundsätzlich eine Rückbuchung über das Anbietermenü oder über die XML-API ausführen kann, werden die einzelnen Phasen für diese beiden Szenarien beschrieben.

2. Rückbuchungen über das Anbietermenü

Im Folgenden werden die einzelnen Phasen einer Rückbuchung über das Anbietermenü beschrieben.

2.1. Rückbuchungen vormerken

Bevor Sie eine einzelne oder mehrere Transaktionen für eine Rückbuchung vormerken, sollte die zugehörige Zahlung auf dem entsprechenden Konto (Deutsche Handelsbank Konto oder Konto Ihrer Hausbank) eingegangen sein. Im Falle eines Kontos bei der Deutschen Handelsbank ist diese Bedingung verpflichtend! Das Vormerken einer oder mehrerer Transaktionen für eine Rückbuchung über das Anbietermenü nehmen Sie wie folgt vor:

Schritt 1: Wählen Sie im Anbietermenü "Transaktionen für SOFORT Überweisung" aus

Schritt 2a (vollständige Rückbuchung): Suchen Sie die betroffene Transaktion und klicken Sie das Icon "Zur Rückbuchung vormerken" (blauer Pfeil) – Bei Verwendung eines Kontos bei der Deutschen Handelsbank nur sichtbar, wenn Zahlungseingang erfolgt ist.

R_vormerken

Schritt 2b (Teilrückbuchung): Suchen Sie die betroffene Transaktion und klicken Sie auf den Link der Transaktionsnummer. In der Detailansicht einer Transaktion können Sie unter "Rückbuchungen" im Feld "Betrag" den Teilbetrag (<= Gesamtbetrag) eintragen, der zur Rückbuchung vorgemerkt werden soll. Anschließend klicken Sie auf "Rückbuchen".

Hinweis:

Generell kann eine Transaktion so oft zur (Teil-)Rückbuchung vorgemerkt werden, bis der Gesamtbetrag der Transaktion erreicht ist.

2.2. Rückbuchungen zusammenfassen

Beim Zusammenfassen der vorgemerkten Rückbuchungen wird eine sog. SEPA PAIN-Datei erstellt. Dies ist ein standardisiertes Dateiformat zur elektronischen Verarbeitung des Zahlungsverkehrs bei Banken des SEPA-Raums. Die Erstellung der Datei nehmen Sie wie folgt vor:

  • Schritt 1: Wählen Sie im Anbietermenü "Weitere Dienste -> Rückbuchungen" aus.
  • Schritt 2: Überprüfen Sie die auf der Folgeseite aufgelisteten, vorgemerkten Rückbuchungen.
  • Schritt 3: Sie können einzelne Rückbuchungen bearbeiten (Betrag, Verwendungszweck, etc.) oder diese aus der Liste wieder entfernen.
  • Schritt 4: Wählen Sie ein Konto als Absender-Konto aus, vergeben Sie einen Dateinamen und "Speichern" Sie die Rückbuchungen.
R_zusammenfassen

Hinweis:

Es dürfen nur Rückbbuchungen einer identischen Währung zusammengefasst werden.

2.3. Rückbuchungen ausführen

Bevor Sie vorgemerkte und zusammengefasste Rückbuchungen per Sammelüberweisung im Online-Banking ausführen können, müssen Sie die relevante PAIN-Datei an Ihre Bank (Deutsche Handelsbank oder Ihre Hausbank) übertragen. Das Ausführen einer Rückbuchung nehmen Sie wie folgt vor:

  • Schritt 1: Wählen Sie im Anbietermenü "Weitere Dienste -> Rückbuchungen" aus.
  • Schritt 2: Die von Ihnen erstellten Rückbuchungs-Dateien werden am Ende der Seite aufgelistet.
2.3.1. a) Kunden mit Konto bei der Deutschen Handelsbank
  • Schritt 3: Starten Sie die automatische Übermittlung an die Deutsche Handelsbank ("Computer-Icon" klicken).

    r_ausführen1
  • Schritt 4: Loggen Sie sich mit Ihren Kontodaten bei der Deutschen Handelsbank ein.
  • Schritt 5: Tragen Sie die erforderliche TAN ein, um die Rückbuchungen zu bestätigen.
2.3.2. b) Kunden ohne Konto bei der Deutschen Handelsbank
  • Schritt 3: Speichern Sie die SEPA PAIN-Datei lokal ab (via Link).

    r_ausführen2
  • Schritt 4: Laden Sie die SEPA PAIN-Datei im Online-Banking Ihrer Hausbank hoch (bei Rückfragen wenden Sie sich bitte an Ihre Bank).
  • Schritt 5: Führen Sie die Sammelüberweisung in Ihrem Online-Banking aus und bestätigen Sie die Rückbuchungen mit der erforderlichen TAN.

3. Integration der Rückbuchung über die XML Schnittstelle

Im Folgenden werden die einzelnen Phasen einer Rückbuchung über die XML-API beschrieben, womit Sie Rückbuchungen automatisiert aus Ihrem (Shop-)System bei SOFORT einstellen können.

3.1. Kommunikation mit der Schnittstelle für Rückbuchungen

Der Aufruf unserer Schnittstelle (API) erfolgt aus Ihrem (Shop-)System durch ein HTTP POST 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) Rückbuchungen vormerken
  • (API-Schritt 2) Antwort der API mit Rückbuchungsdaten inkl. Status

Sofern nicht bereits durch API-Schritt 1 initiiert, können Sie in einem manuellen Schritt noch die Rückbuchungen zusammenfassen (vgl. vorherigen Abschnitt), bevor Sie diese letztlich ausführen.

3.2. Rückbuchungen vormerken (API-Schritt 1)
3.2.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.2.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. Die Unterscheidung zwischen Teilrückbuchung und vollständiger Rückbuchung wird auf Basis des übergebenen Betrags getroffen (Teilrückbuchung: <amount> < Gesamtbetrag der Transaktion).

Ein beispielhafter Aufruf für eine Rückbuchung könnte in XML formatiert so aussehen:

<?xml version="1.0" encoding="UTF-8" ?>
<refunds version="3">
      <sender>
            <holder>Max Samplemerchant</holder>
            <bic>SFRTDE20XXX</bic>
            <iban>DE11888888889999999999</iban>
      </sender>
      <title>Test Refund December 5, 2013</title>
      <refund>
            <transaction>00000-00000-00000000-0000</transaction>
            <amount>1.11</amount>
            <comment>Order cancelled by user.</comment>
            <reason_1>OrderID 123456</reason_1>
            <reason_2>Refund</reason_2>
      </refund>
      <refund>
            <transaction>00000-00000-00000000-0001</transaction>
            <amount>13.90</amount>
            <reason_1>OrderID 654321</reason_1>
            <reason_2>Refund</reason_2>
            <partial_refund_id>1</partial_refund_id>
      </refund>
</refunds>
3.3. Antwort der API mit Rückbuchungsdaten inkl. Status (API-Schritt 2)

Zusätzlich zu den Parametern des Aufrufs wird ein Status sowie im Fehlerfall eine genaue Fehlerbeschreibung zurückgegeben. Eine Übersicht der möglichen Fehlermeldungen finden Sie im Anhang.

<?xml version="1.0" encoding="UTF-8" ?>
<refunds version="3">
      <sender>
            <holder>Max Samplemerchant</holder>
            <bank_name>Demo Bank</bank_name>
            <iban>DE11888888889999999999</iban>
            <bic>SFRTDE20XXX</bic>
      </sender>
      <title>Test Refund December 5, 2013</title>
      <pain>[Base-64 encoded content for PAIN-file]</pain>
      <refund>
            <recipient>
                  <holder>Max Mustermann</holder>
                  <bank_name>Demo Bank</bank_name>
                  <iban>DE06000000000023456789</iban>
                  <bic>SFRTDE20XXX</bic> 
            </recipient>
            <transaction>00000-00000-00000000-0000</transaction>
            <amount>1.11</amount>
            <comment>Order cancelled by user.</comment>
            <reason_1>OrderID 123456</reason_1>
            <reason_2>Refund</reason_2>
            <time>2013-12-05T16:31:59+01:00</time>
            <partial_refund_id>fb1244caad</partial_refund_id>
            <status>accepted</status>
      </refund>
      <refund>
            <transaction>00000-00000-00000000-0001</transaction>
            <amount>13.90</amount>
            <reason_1>OrderID 654321</reason_1>
            <reason_2>Refund</reason_2>
            <partial_refund_id>1</partial_refund_id>
            <status>error</status>
            <errors>
                  <error>
                        <code>5002</code>
                        <message>Transaction could not be found.</message>
                  </error>
            </errors>
      </refund>
</refunds>

Sofern Sie den "sender"-Block beim Aufruf der XML-API übergeben haben, erhalten sie den Parameter <pain> zurück (im Beispiel ist hier nur ein Platzhalter angegeben), der die Base-64 codierten Überweisungsinformationen im PAIN XML Format enthält (je nachdem aus welchem Land das Absenderkonto stammt, werden unterschiedliche PAIN Formate verwendet. Für DE: pain.001.003.03; für AT, CH, NL, BE, FR, IT, ES, SK, CZ, HU: pain.001.001.03). Diese müssen in einem nächsten Schritt als .pain Datei abgespeichert werden, bevor sie an die Bank übergeben werden können.

Tritt ein schwerwiegenderer Fehler auf, so erhalten Sie eine Fehlermeldung ohne die Parameter der vorher geschickten Rückbuchungen:

<?xml version="1.0" encoding="UTF-8" ?>
<errors>
      <error>
            <code>7000</code>
            <message>Invalid XML</message>
      </error>
</errors>
3.4. Rückbuchungen zusammenfassen

Unabhängig davon, ob Sie ein Konto bei der Deutschen Handelsbank besitzen oder nicht, können die vorgemerkten Rückbuchungen entweder manuell oder automatisch zusammengefasst werden.

Hinweis:

Es dürfen nur Rückbbuchungen einer identischen Währung zusammengefasst werden.

3.4.1. Automatisch

Sobald der "sender"-Block beim Aufruf der XML-API übergeben wird (siehe Beispiel API-Aufruf oben), werden die Rückbuchungen automatisch zusammengefasst. Die zusammengefassten Rückbuchungen sind als SEPA PAIN-Dateien im Anbietermenü gespeichert und werden ihnen zusätzlich in der Antwort der API im XML-Parameter "pain" zurückgegeben.

3.4.2. Manuell

Wenn der "sender"-Block beim Aufruf der XML-API nicht übergeben wird, werden die Rückbuchungen vorgemerkt, aber nicht zusammengefasst. Die Rückbuchungen können Sie in diesem Fall manuell im Anbietermenü zusammenfassen.

Informationen dazu erhalten Sie im Kapitel "Rückbuchungen über das Anbietermenü" (vgl. Abschnitt oben).

3.5. Rückbuchungen ausführen

Das Ausführen einer Rückbuchung nehmen Sie wie folgt vor:

3.5.1. Mit Konto bei der Deutschen Handelsbank

Diese Möglichkeit steht nur für Rückbuchungen bereit, die als Absenderkonto ein Konto bei der Deutschen Handelsbank hinterlegt haben.

  • Schritt 1: Wählen Sie im Anbietermenü "Weitere Dienste > Rückbuchungen > Zusammengefasste Rückbuchungen" aus
  • Schritt 2: Starten Sie die automatische Übermittlung an die Deutsche Handelsbank ("Computer-Icon" hinter der zusammengefassten Rückbuchung klicken)
  • Schritt 3: Loggen Sie sich mit Ihren Kontodaten bei der Deutschen Handelsbank ein
  • Schritt 4: Tragen Sie die erforderliche TAN ein, um die Rückbuchungen zu bestätigen
3.5.2. Ohne Konto bei der Deutschen Handelsbank mit Hilfe einer SEPA PAIN-Datei
  • Schritt 1: Decodieren Sie den Inhalt des XML Parameters "pain" (Base 64) und speichern Sie das Ergebnis in einer SEPA PAIN-Datei (.pain) ab. Diesen Vorgang können Sie Ihrerseits automatisieren.
  • Schritt 2: Loggen Sie sich mit Ihren Daten im Online-Banking Ihrer Hausbank ein.
  • Schritt 3: Spielen Sie die Datei ins Online-Banking ein (bei Rückfragen wenden Sie sich bitte an Ihre Bank)
  • Schritt 4: Führen Sie die Sammelüberweisung in Ihrem Online-Banking aus und bestätigen Sie die Rückbuchungen mit der erforderlichen TAN

4. Testen

Damit Sie die Rückbuchung testen können, führen Sie zunächst eine SOFORT Überweisung, SOFORT Überweisung Paycode oder iDEAL Testtransaktion durch (mit Absender-BLZ "88888888" bzw. Absender-BIC "SFRTDE20XXX"). Anschließend können Sie die Vormerkung und Zusammenfassung von Rückbuchungen über die API testen. Im Anbietermenü finden Sie die vorgemerkten und zusammengefassten Testrückbuchungen unter "Weitere Dienste > Rückbuchungen > Test-Transaktionen".

Verwenden Sie beim Testen des Zusammenfassens über die XML-Schnittstelle im Absender-Block folgende Kontodaten:

Sender Account Country Refund Bank Details
DE <sender>
<holder>Max Samplemerchant</holder>
<iban>DE11888888889999999999</iban>
</sender>
 
Optional BIC:
<bic>SFRTDE20XXX</bic>
AT <sender>
<holder>Max Samplemerchant</holder>
<iban>AT850000000023456789</iban>
</sender>
 
Optional BIC:
<bic>SFRTAT20XXX</bic>
CH <sender>
<holder>Max Samplemerchant</holder>
<iban>CH0600000000023456789</iban>
</sender>
 
Optional BIC:
<bic>SFRTCH20XXX</bic>
PL <sender>
<holder>Max Samplemerchant</holder>
<iban>PL71000000000000000023456789</iban>
</sender>
 
Optional BIC:
<bic>SFRTPL20XXX</bic>
BE <sender>
<holder>Max Samplemerchant</holder>
<iban>BE87999234567894</iban>
</sender>
 
Optional BIC:
<bic>SFRTBE20XXX</bic>
ES <sender>
<holder>Max Samplemerchant</holder>
<iban>ES9799990000161234567890</iban>
</sender>
 
Optional BIC:
<bic>SFRTES20XXX</bic>
IT <sender>
<holder>Max Samplemerchant</holder>
<iban>IT8600000000000001234567890</iban>
</sender>
 
Optional BIC:
<bic>SFRTIT20XXX</bic>
NL <sender>
<holder>Max Samplemerchant</holder>
<iban>NL71SFRT0002345678</iban>
</sender>
 
Optional BIC:
<bic>SFRTNL20XXX</bic>
FR <sender>
<holder>Max Samplemerchant</holder>
<iban>FR7600000000000123456789091</iban>
</sender>
 
Optional BIC:
<bic>SFRTFR20XXX</bic>

Die entsprechenden Testtransaktionen werden zur Rückbuchung vorgemerkt und zusammengefasst. Bitte beachten Sie, dass eine Vermischung von realen und Testtransaktionen nicht möglich ist.

5. Anhang

5.1. Parameterübersicht

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

Erklärung der Tabellenspalten der Tabellen in den folgenden Abschnitten:

  • 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.2. 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.3. (API-Schritt 1) Rückbuchungen vormerken

Die notwendigen Parameter, um eine Transaktion über unsere Schnittstelle vorzumerken bzw. zusammenzufassen sind in den beiden nachfolgenden Tabellen festgehalten.

Parameter Anzahl Typ (Länge) Beschreibung
refunds  (mit Attribut version="3") [1] Container Container für beliebig viele Einzelrückbuchungen (version="3" als Attribut notwendig)
  sender [0,1] Container Das Konto des Händlers, von dem die Rückbuchung ausgeführt werden soll. Ist nur notwendig, sofern eine Rückbuchung zusammengefasst werden soll. Andernfalls werden die Rückbuchungen nur vorgemerkt.
    holder [1] String (27) Name des Kontoinhabers
    iban [1] String (34) IBAN des Absenderkontos
    bic [1] String (11) BIC des Absenderkontos
  title [0,1] String (255) Dateiname der Rückbuchungsdatei
  refund [1..n] Container Container für Daten zu einer Einzelrückbuchung
    transaction [1] String (27) Transaktionsnummer der ursprünglichen Transaktion
    amount [1] Double (8.2) Betrag der zurückgebucht werden soll. Sofern dieser kleiner als der Gesamtbetrag der Transaktion ist, wird eine Teilrückbuchung durchgeführt. Kein Tausender-Trennzeichen, zwei Nachkommastellen, Punkt als Trennzeichen z.B.: 12.24
    comment [0,1] String (255) Optionaler Kommentar der anschließend im Anbietermenü zur Rückbuchung angezeigt wird
    reason_1 [0,1] String (27)

Verwendungszweck Zeile 1

Übergeben Sie einen eindeutigen Wert (z. B. Bestellnummer) nur folgende Zeichen erlaubt: '0-9', 'a-z', 'A-Z', ' ', '+', ',', '-', '.'. Umlaute werden ersetzt, also z.B. ä -> ae.

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

Wird kein Verwendungszweck übergeben, so wird der Verwendungszweck der ursprünglichen Transaktion genutzt.

    reason_2 [0,1] String (27)

Verwendungszweck Zeile 2

siehe reason_1

    partial_refund_id [0,1] String (50) Kann zur Identifikation von einzelnen Teilrückbuchungen einer Transaktion angegeben werden. Wird keine ID übergeben, so wird eine zufällige generiert.
5.4. (API-Schritt 2) Antwort der API mit Rückbuchungsdaten inkl. Status
Parameter Anzahl Typ (Länge) Beschreibung
refunds  (mit Attribut version="3") [0,1] Container Entweder wird das Ergebnis des Rückbuchungsaufrufs zurückgegeben, oder Fehler (<errors>).
  sender [0,1] Container Bankverbindung des Händlers - wird nur beim Zusammenfassen zurückgegeben.
    holder [1] String (27) Name des Händlers
    bank_name   String (255) Name der Bank des Händlers
    iban [1] String (34) IBAN des Absenderkontos
    bic [1] String (11) BIC des Absenderkontos
  title [0,1] String (255) Dateiname der Rückbuchungsdatei
  pain [0,1] String

Zusammengefasste Rückbuchungen im PAIN-Format (DE: pain.001.003.03; AT, CH, NL, BE, FR, IT, ES, SK, CZ, HU: pain.001.001.03) als Base64 codierter String, sofern der <sender> Block im Aufruf übergeben wurde.

Details zur PAIN Spezifikation finden sie in Anlage 3 der Schnittstellenspezifikation für die Datenfernübertragung zwischen Kunde und Kreditinstitut gemäß DFÜ Abkommen Version 2.7, welches ab 04.11.2013 gültig ist.

  refund [1..n] Container Container für Daten zu einer Einzelrückbuchung
    recipient [0,1] Container Bankverbindung des Käufers an den der Rückbuchungsbetrag zurücküberwiesen wird. Wird nur zurückgegeben, sofern <status> den Wert "accepted" hat.
      holder [1]   Name des Käufers
      bank_name [1]   Name der Bank des Käufers
      iban [1]   IBAN des Empfängerkontos
      bic [1]   BIC des Empfängerkontos
    transaction [1] String (27) Transaktionsnummer der ursprünglichen Transaktion
    amount [1] Double (8.2) Betrag der zurückgebucht werden soll, kein Tausender-Trennzeichen, zwei Nachkommastellen, Punkt als Trennzeichen z.B.: 12.24
    comment [0,1] String (255) Optionaler Kommentar, der anschließend im Anbietermenü zur Rückbuchung angezeigt wird
    reason_1 [0,1] String (27) Verwendungszweck Zeile 1
    reason_2 [0,1] String (27) Verwendungszweck Zeile 2
    time [0,1] String (25) Zeitpunkt der Erstellung der Rückbuchung im ISO 8601 Format: YYYY-MM-DDThh:mm:ss+HH:mm. Wird nur zurückgegeben, sofern <status> den Wert "accepted" hat.
    partial_refund_id [1] String (50) Eindeutiger Bezeichner für eine Teilrückbuchung
    status [1] String (10) "accepted", oder "error" (falls die Rückbuchung nicht vorgemerkt werden konnte)
    errors [0,1] Container Container für Fehlermeldungen, die eine bestimmte Rückbuchung betreffen
      error [1..n] Container Fehlerbeschreibung
        code [1] Integer Fehlercode
        message [1] String (255) genaue Fehlerbeschreibung
errors [0,1] Container Fehler - kann alternativ zum Tag <refunds> zurückgegeben werden.
  error [1..n] Container Fehlerbeschreibung
    code [1] Integer Fehlercode
    message [1] String (255) genaue Fehlerbeschreibung
5.4.1. Fehler

Wenn die Vormerkung zur Rückbuchung nicht erfolgreich abgeschlossen werden kann, erhalten Sie im allgemeinen Fall nur einen <errors> Container zurück. Sofern sich der Fehler nur auf eine spezifische Rückbuchung bezieht, erhalten Sie im <status> Tag den Status "error" sowie innerhalb der betreffenden Rückbuchung den Container <errors> zurück.

Allgemeine Fehler
Code Message Beschreibung Simulation
1000 Invalid request. Ungültige Anfrage.  
1001 Technical error. Technischer Fehler.  
7000 Invalid XML XML Struktur ist fehlerhaft. Aufruf mit invalidem XML Dokument, bspw. "xyz" (als einziger POST Inhalt)
7004 XML parameter not provided in request Parameter "xml" not provided in request. Aufruf ohne POST Inhalt
7005 Project has no Deutsche Handelsbank account. Kein Konto der Deutschen Handelsbank für das Projekt hinterlegt Ein "Nicht"-Deutsche Handelsbank-Konto muss im den Projekteinstellungen gespeichert werden.
7006 Service temporarily unavailable due to maintenance Aufgrund von Wartungsarbeiten ist der Dienst nicht verfügbar.

Transaktionsaufruf:
Aufruf mit <reason> Wert "00000-00000-00000000-7006"

Refunds Aufruf:
Aufruf mit <transaction> Wert "00000-00000-00000000-7006"

Spezifische Fehler
Code Message Beschreibung Simulation
5000 Transaction ID missing Keine Transaktions-ID übergeben Aufruf mit fehlendem oder leerem <transaction> tag
5001 Amount missing Betrag fehlt Aufruf mit fehlendem oder leerem <amount> tag
5002 Transaction could not be found Transaktion konnte nicht gefunden werden Aufruf mit <transaction> Wert "00000-00000-00000000-5002"
5003 Amount must not exceed transaction amount Der Betrag darf den Ursprungsbetrag nicht übersteigen Aufruf mit <transaction> Wert "00000-00000-00000000-5003"
5004 Transaction has not been received yet Der Transaktionsbetrag ist noch nicht auf dem Konto bei der Deutschen Handelsbank eingegangen Aufruf mit <transaction> Wert "00000-00000-00000000-5004"
5006 No refund elements provided Kein entsprechender XML-Tag übergeben Aufruf mit fehlendem <refund> tag im Container <refunds>
5007 Buyer Protection not closed Der Käuferschutz ist noch nicht geschlossen Aufruf mit <transaction> Wert "00000-00000-00000000-5007"
5008 Product not supported Das Produkt wird nicht unterstützt oder ist noch nicht freigeschaltet/aktiviert Aufruf mit <transaction> Wert "00000-00000-00000000-5008"
5009 Refund request could not be issued. An unknown error occured. Rückbuchung konnte nicht ausgeführt werden. Unbekannter Fehler Aufruf mit <transaction> Wert "00000-00000-00000000-5009"
5010 Invalid bank code Ungültige oder fehlende Bankleitzahl Aufruf mit invalidem <bank_code> Wert, bspw. "xyz"
5011 Invalid account number Ungültige oder fehlende Kontonummer Aufruf mit invalidem <account_number> Wert, bspw. "0"
5012 Invalid amount Ungültiger Betrag Aufruf mit <transaction> Wert "00000-00000-00000000-5012"
5013 Invalid record data. Ungültige Zeichen im Verwendungszweck oder Comment Aufruf mit <transaction> Wert "00000-00000-00000000-5013"
5018 Invalid BIC Ungültige oder fehlende BIC - eine BIC ist auch ungültig, sofern es keine deutsche BIC ist Aufruf mit <transaction> Wert "00000-00000-00000000-5018"
5019 Invalid IBAN Ungültige oder fehlende IBAN - eine IBAN ist auch ungültig, sofern es keine deutsche IBAN ist Aufruf mit <transaction> Wert "00000-00000-00000000-5019"
5020 Invalid holder Ungültiger Kontoinhaber Aufruf mit fehlendem oder leerem <holder> tag bzw. falls mehr als 27 Zeichen verwendet wurden
5021 Refunding of test and real transactions must not be mixed Rückbuchungen für Test-Transaktionen und echte Transaktionen dürfen nicht gemischt werden Aufruf mit <transaction> Wert "00000-00000-00000000-5021"
5022 The currency of the transaction is not supported Es dürfen nur EUR, CHF, PLN oder HUF Transaktionen rückgebucht werden Aufruf mit <transaction> Wert "00000-00000-00000000-5022"
5023 Sender-Block contains a real account and the records are test transactions. Real sender account and test transactions must not be mixed. Es wurde ein echtes Absenderkonto (vormals Empfängerkonto) für die Rückbuchung angegeben, aber eine Testtransaktion versucht zurückzubuchen Aufruf mit <transaction> Wert "00000-00000-00000000-5023"
5024 Sender-Block contains a test account and the records are real transactions. Test sender account and real transactions must not be mixed. Es wurde das Testabsenderkonto (vormals Empfängerkonto) für Rückbuchungen angegeben, aber eine echte Transaktion versucht zurückzubuchen Aufruf mit <transaction> Wert "00000-00000-00000000-5024"
5025 No sender for this transaction Der Kontoinhaber der ursprünglichen Transaktion konnte nicht ermittelt werden Aufruf mit <transaction> Wert "00000-00000-00000000-5025"
5027 Refund for given partial_refund_id already exists Die Teilrückbuchungs-ID wurde schon vergeben Zweimaliges Absenden des identischen Aufrufs (mit gleicher <partial_refund_id>)
5028 Refund request could not be issued. Transaction too old. No refundable data available Rückbuchung konnte nicht ausgeführt werden. Die Daten stehen nicht mehr zur Verfügung. Aufruf mit <transaction> Wert "00000-00000-00000000-5028"
5029 Request could not be processed. Refund API v1 not supported anymore. Es wurde ein alter API Aufruf verwendet, der nicht mehr unterstützt wurde. Bitte aktualisieren Sie Ihre Integration. Aufruf mit <refunds version="1">
5030 Sender country not supported for refunds or for this currency Es wurde im Absender-Block ein Konto aus einem Land übergeben, welches nicht für Rückbuchungen unterstützt oder die Rückbuchungen in dieser Währung sind nicht möglich Aufruf mit einer Währung ausser der Währungen EUR, HUF, PLN, CHF
5033 Refunding of transaction with different currencies must not be mixed Rückbuchungen verschiedener Währungen dürfen nicht gemischt werden Aufruf mit <transaction> Wert "00000-00000-00000000-5033"

6. Support & Kontakt

Das Team von Sofort 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 89 20 20 889-400
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 89 20 20 889-0

Informationen für Verkäufer und Händler:
Telefon: +49 89 20 20 889-500
Fax:+49 89 20 20 889-120

info@sofort.com
www.sofort.com

Geschäftsführung

Robert Bueninck
Patrick Dittmer
Jacob von Ingelheim

Externer Datenschutzbeauftragter

Hr. Andreas Schmidt, 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.