Händler-Login

API Dokumentation

SOFORT Überweisung Paycode

1. Einführung zu SOFORT Überweisung Paycode

Mit der Funktion SOFORT Überweisung Paycode erhalten Sie die Möglichkeit, einen 10-stelligen Code zu generieren, mit dem Ihre Kunden eine Zahlung via SOFORT Überweisung zu einem beliebigen späteren Zeitpunkt innerhalb des Gültigkeitszeitraums aufnehmen können.

Der Ablauf für eine SOFORT Überweisung mit Paycode stellt sich wie folgt dar:

  1. Generieren Sie einen Paycode. Sie können einen Paycode entweder in Ihrem Anbietermenü bei SOFORT oder über die HTTP-XML-Schnittstelle generieren. (Siehe Kapitel 2: Menüpunkt Paycode im Anbietermenü bei SOFORT oder Kapitel 3: Generierung eines Paycode über eine HTTP-XML Schnittstelle)
  2. Teilen Sie den Paycode Ihrem Kunden mit.
  3. Der Kunde kann den Paycode auf der Seite https://www.sofort.com/paycode/ eingeben und die Bezahlung durchführen.
  4. Sie erhalten je nach Projektkonfiguration entweder eine Mitteilung oder können im Anbietermenü einsehen, dass die Überweisung von Ihrem Kunden in seinem Online-Banking eingestellt wurde.

2. Integrationsschritte

Um SOFORT Überweisung Paycode 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. Aktivieren Sie das Produkt „SOFORT Überweisung Paycode“ (unter „Mein Konto“ → „Produkt-Aktivierung“)
  3. Erstellen Sie ein neues SOFORT-Gateway-Projekt.
  4. Konfigurieren Sie Ihr SOFORT Überweisung Paycode-Projekt; wählen Sie bei den Zahlarten „SOFORT Überweisung Paycode".
  5. Nach Projektanlage und -konfiguration erhalten Sie einen API-Key (diesen finden Sie im linken Menü unter „Weitere Dienste“ → „API-Key“).
  6. Sofern Sie Paycodes automatisch über die SOFORT Schnittstelle generieren wollen, und die Benachrichtigungen über eine erfolgreiche Überweisung in Ihrem Shop automatisiert verarbeiten wollen, folgt die Shop Integration:
    1. Integrieren Sie die Erstellung von Paycodes in Ihrem Shop
    2. Legen Sie die Erfolgs-/Abbruchseite fest bzw. erstellen Sie diese, auf die Ihr Kunde bei erfolgreicher/gescheiterter SOFORT Überweisung weitergeleitet wird.
    3. Konfigurieren Sie Ihren Shop so, dass er Benachrichtigungen empfangen und Statusdetailanfragen initiieren kann.
Ablauf SÜ Paycode Kommunikation

Wichtige allgemeine Hinweise

  • Die verwendete Standardcodierung für alle Parameter ist UTF-8.
  • Die Verwendungszwecke für „SOFORT Überweisung“ werden in bestimmten Fällen durch uns angepasst. Die Änderung bezieht sich auf die Parameter <reason> innerhalb des Containers <reasons>. Dort werden die Textpassagen „sofortüberweisung“, „sofort-ueberweisung“, „Payment Network AG“, „directebanking“ und Kombinationen daraus, z.B. mit Bindestrich „direct-ebanking“ (Groß- und Kleinschreibung wird nicht beachtet) ersatzlos aus dem Verwendungszweck gelöscht. Auch die Domains sofortüberweisung.de, sofortueberweisung.de, sofort-überweisung.de, sofort-ueberweisung.de, directebanking.com und direct-ebanking.com werden herausgenommen.
  • Sofern der Verwendungszweck Zeile 1 nach dem Löschen leer sein sollte, wird dieser mit den Inhalten des Verwendungszweck Zeile 2 befüllt. Sollten danach beide Verwendungszweck Zeilen leer sein, so schreiben wir den Empfängernamen in den Verwendungszweck Zeile 1.

3. Menüpunkt Paycode im Anbietermenü bei SOFORT

3.1. Erstellung von Paycodes

Wenn Sie einen Paycode generieren möchten, können Sie dies bequem im Anbietermenü der SOFORT erledigen.

  1. Um einen Paycode in Ihrem Anbietermenü zu generieren, melden Sie sich mit Ihren Kundendaten bei SOFORT unter der Adresse https://www.sofort.com/payment/users/login an.
  2. Wählen Sie unter dem Punkt "Transaktionen für... Sofort Paycode" (linke Navigationsspalte) den Reiter "Paycode generieren" oder, sofern Sie den Paycode direkt per Mail oder SMS versenden wollen, die Reiter "Per E-Mail verschicken" oder "Per SMS verschicken". 
  3. Sie können nun die gewünschten Kriterien für Ihren Paycode festlegen. Folgende Einstellungen sind möglich:

    Projekt

    Wählen Sie das gewünschte Paycode-Projekt, welches für die Erstellung verwendet werden soll. Beachten Sie, dass in Ihrem Projekt das Produkt "SOFORT Paycode" aktiviert ist.

    Gültigkeit

    Mit dieser Option bestimmen Sie den Zeitraum innerhalb dessen der generierte Paycode gültig sein soll.
    Anzahl Verwendbarkeit (*muss separat durch SOFORT freigeschaltet werden)
    Mit dieser Option bestimmen Sie wie oft dieser Paycode einlösbar sein soll.

    Zahlungsdaten

    Betrag - Geben Sie den gewünschten Betrag ein.
    Währung - Wählen Sie die gewünschte Währung.
    Verwendungszweck - Geben Sie den gewünschten Verwendungszweck ein. Beachten Sie auch den Hinweis aus Kapitel "Integrationsschritte: Wichtige allgemeine Hinweise".

    Einstellungen

    Erfolgslink - Über den Erfolgslink gelangt Ihr Kunde nach erfolgreicher Transaktion wieder zurück in Ihren Shop.
    Abbruchlink - Über den Abbruchlink gelangt Ihr Kunde nach nicht erfolgreicher Transaktion (Abbruch durch Kunden bzw. SOFORT Überweisung nicht möglich) wieder zurück in Ihren Shop.

    Kundenvariablen

    Sie können eigene Variablen übergeben, die Sie z.B. für die interne Zuordnung verwenden können. Näheres zu den Kundenvariablen erfahren Sie in unserem Handbuch zur SOFORT Überweisung.

    Paycode generieren

    Abschließend drücken Sie unten auf der Seite den Button „Paycode generieren“. Ihnen wird nun der Code oben auf der Seite angezeigt inkl. der URL, auf welcher der Paycode eingeben werden kann.

  4. Senden Sie den Paycode an Ihren Kunden zusammen mit dem URL https://www.sofort.com/paycode/. Im Anbietermenü von SOFORT Überweisung haben Sie zusätzlich die Möglichkeit den Paycode direkt per E-Mail oder SMS zu versenden (für den SMS-Versand fallen zusätzliche Kosten an).
  5. Wenn der Kunde die Überweisung vorgenommen hat, erhalten Sie je nach Projektkonfiguration entweder eine Mitteilung (siehe Reiter "Erweiterte Einstellungen" → "Benachrichtigungen") oder können im Anbietermenü einsehen, dass die Bezahlung durchgeführt wurde.
3.2. Weitere Funktionen im Paycode-Menü

Im Anbietermenü haben Sie außerdem die Möglichkeit, eine Übersicht der bis dato generierten Paycodes zu erhalten.

Klicken Sie im Menü unter "Transaktionen für" auf "SOFORT Überweisung Paycode". Sie erhalten eine Liste mit den bisher erstellten Paycodes sowie zugehörigen Transaktionen (SOFORT Überweisungen) die durch einen Paycode veranlasst wurden. Diese Liste können Sie mit Hilfe der Suche oben weiter filtern.

Zusätzlich haben Sie die Möglichkeit, sich Details zu diesem Paycode anzeigen zu lassen.

4. Generierung eines Paycodes über die HTTP-XML-Schnittstelle (API)

Neben der Erstellung von Paycodes im Anbietermenü haben Sie auch die Möglichkeit, den Paycode über unsere HTTP-XML-Schnittstelle (API) zu generieren und somit den zurück gegebenen Wert (Paycode) direkt in Ihr System einzubauen.

4.1. Kommunikation mit der Schnittstelle für SOFORT Überweisung Paycode

Der Aufruf unserer Schnittstelle (API) erfolgt aus Ihrem Shop 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) Initialer Aufruf der API und Übergabe der Transaktionsparameter
  • (API-Schritt 2) Antwort der API mit generiertem Paycode und Zahlungs-URL
  • (Kundenaktion) Weiterleitung des erhaltenen Paycodes und Einstellung der Überweisung.
  • (API-Schritt 3) Benachrichtigung über eine Änderung des Transaktionsstatus (sofern konfiguriert)
  • (API-Schritt 4) Abruf der Transaktionsdaten
  • (API-Schritt 5) Antwort auf den Abruf der Transaktionsdaten

Für die Statusabfrage eines bereits erstellten Paycodes steht eine weitere Abfragemöglichkeit der API zur Verfügung:

Zur Änderung eines bereits erstellten Paycodes kann folgende API verwendet werden:

Um bestehende Paycodes zu deaktivieren bzw. anschließend wieder zu aktivieren steht folgende API zur Verfügung:

4.2. Initialer Aufruf der API und Übergabe der Transaktionsdaten (API-Schritt 1)
4.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 Parameterübersicht) und per HTTP POST verschickt werden.

Der Aufruf der Schnittstelle erfolgt über folgende URL:

https://api.sofort.com/api/xml
4.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. Ein beispielhafter Aufruf zur Erstellung eines SOFORT Überweisung Paycode könnte in XML formatiert so aussehen:

<?xml version="1.0" encoding="UTF-8" ?>
<paycode>
   <project_id>53245</project_id>
   <interface_version>pn_test_1</interface_version>
   <start_date>2014-01-01T00:00:00+01:00</start_date>
   <end_date>2015-05-01T01:12:59+02:00</end_date>
   <amount>2.20</amount>
   <currency_code>EUR</currency_code>
   <max_usage>100</max_usage>
   <sender>
      <bank_code>00000</bank_code>
      <bic>SFRTDE20XXX</bic>
      <country_code>DE</country_code>
   </sender>
   <reasons>
      <reason>Customer ID 100256</reason>
      <reason>Paycode Int 0</reason>
   </reasons>
   <success_url>https://www.example.com/success.php?trx=-TRANSACTION-</success_url>
   <success_link_redirect>0</success_link_redirect>
   <abort_url>https://www.example.com/abort.php</abort_url>
   <notification_urls>
      <notification_url>https://www.example.com/notify.php</notification_url>
   </notification_urls>
   <notification_emails>
      <notification_email>notify@example.com</notification_email>
   </notification_emails>
   <user_variables>
      <user_variable>Test123</user_variable>
   </user_variables>
   <intervals>
      <interval>
         <from_date>2014-10-01</from_date>
         <amount>3.30</amount>
         <reasons>
            <reason>Customer ID 100256</reason>
            <reason>Paycode Int 1</reason>
         </reasons>
      </interval>
      <interval>
         <from_date>2015-02-01</from_date>
         <amount>4.40</amount>
         <reasons>
            <reason>Customer ID 100256</reason>
            <reason>Paycode Int 2</reason>
         </reasons>
      </interval>
   </intervals>
</paycode>

Durch die Angabe von mehreren Gültigkeitsintervallen innerhalb von <intervals> können für den Paycode Zeiträume definiert werden, zu denen übergebene Beträge und Verwendungszwecke gelten sollen. Dabei legen die zusätzlich übergebenen <interval> Abschnitte fest, ab wann ein neues Intervall beginnt (<from_date>) und welche Werte für dieses Intervall gelten. Somit lassen sich bspw. Frühbucherrabatte oder auch Rechnungsskonti mit dem Paycode abbilden. Für den Paycode, der durch oben aufgeführten Aufruf erstellt wird würden folgende Gültigkeitsintervalle gelten:

Paycode Start - 2014-01-01 00:00:00

Betrag: 2.20
Verwendungszweck: Customer ID 100256
  Paycode Int 0

Intervall 1 - 2014-10-01 00:01:00

Betrag: 3.30
Verwendungszweck: Customer ID 100256
  Paycode Int 1

Intervall 2 - 2015-02-01 00:01:00

Betrag: 4.40
Verwendungszweck: Customer ID 100256
  Paycode Int 2

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

Hinweis: Im Gegensatz zu Start- und Enddatum eines Paycodes beginnen weitere Gültigkeitsintervalle jeweils mit einem neuen Tages um 00:01:00 Uhr. Als Zeitzone gelten MEZ (UTC+1) bzw. MESZ (UTC+2) (je nach Jahreszeit).

4.3. Antwort der API mit generiertem Paycode und Zahlungs-URL (API-Schritt 2)

Sofern der Aufruf der Schnittstelle korrekt war, erhalten Sie als Antwort von der Schnittstelle den generierten Paycode sowie einen URL zum direkten Aufruf des Paycode Formulars bei SOFORT. Details zur Verwendung der einzelnen Parameter finden Sie in der Parameterübersicht.

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

<?xml version="1.0" encoding="UTF-8" ?>
<new_paycode>
   <paycode>6c9d197ddb</paycode>
   <paycode_url>https://www.sofort.com/paycode/6c9d197ddb</paycode_url>
</new_paycode>

4.4. Weiterleitung des erhaltenen Paycodes und Einstellung der Überweisung (Kundenschritt)

Leiten Sie den generierten Paycode (Inhalt des Tags <paycode>) inkl. dem URL https://www.sofort.com/paycode/ an Ihren Kunden weiter. Nach Aufruf des URLs wird Ihr Kunde gebeten, den Paycode einzugeben. Anschließend wird er durch die SOFORT Überweisung geleitet. Alternativ können Sie Ihren Kunden auch auf den generierten direkten Link zum Zahlformular weiterleiten (Inhalt des Tags <paycode_url>), bspw. innerhalb einer E-Mail zur Zahlungsaufforderung.

Sofern die Überweisung mittels Paycode 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 SOFORT Überweisung 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) und die Bestellung mit entsprechendem Status abgespeichert haben. Ist kein Erfolglink im Projekt angegeben und wurde kein Erfolgslink im initialen API-Aufruf (API-Schritt 1) übergeben, so sieht Ihr Kunde lediglich eine Zusammenfassung der eingestellten Überweisung.

Sollte die SOFORT Überweisung nicht erfolgreich beendet worden sein, so wird Ihr Kunde auf den Abbruchlink weitergeleitet.

4.5. Benachrichtigung über eine Änderung des Transaktionsstatus (sofern konfiguriert) (API-Schritt 3)

Sofern die SOFORT Überweisung 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 oder durch den Versand einer Email. Die Adresse können Sie entweder in Ihrem Projekt hinterlegen oder aber bereits im initialen Aufruf der Schnittstelle (API-Schritt 1) übergeben. In dieser Benachrichtigung wird die Transaktions-ID der Transaktion übergeben, deren Status sich geändert hat. Sollte keine URL/Emailadresse im Projekt hinterlegt sein oder bei Aufruf der API übergeben worden sein, erfolgt keine Benachrichtigung.

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>2013-04-02T14:19:08+01: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.

4.6. 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-04-01</from_time>
   <to_time>2013-04-30</to_time>
   <product>paycode</product>
   <number>10</number>
   <page>2</page>
</transaction_request>

4.7. 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. Beachten Sie, dass nach Abschluss einer Transaktion, die Transaktionsdaten jederzeit abgefragt werden können. 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-04-02T14:19:08+01:00</time>
    <status>pending</status>
    <status_reason>not_credited_yet</status_reason>
    <status_modified>2013-04-02T14:19:08+01:00</status_modified>
    <payment_method>paycode</payment_method>
    <language_code>de</language_code>
    <amount>2.20</amount>
    <amount_refunded>0.00</amount_refunded>
    <currency_code>EUR</currency_code>
    <reasons>
      <reason>Reason Line 1 ueaeoess</reason>
      <reason>Reason Line 2</reason>
    </reasons>
    <user_variables>
      <user_variable>Test123</user_variable>
    </user_variables>
    <sender>
      <holder>Max Mustermann</holder>
      <account_number>23456789</account_number>
      <bank_code>00000</bank_code>
      <bank_name>Demo Bank</bank_name>
      <bic>SFRTDE20XXX</bic>
      <iban>DE06000000000023456789</iban>
      <country_code>DE</country_code>
    </sender>
    <email_customer/>
    <phone_customer/>
    <exchange_rate>1.0000</exchange_rate>
    <recipient>
      <holder>Max Mustermann</holder>
      <account_number>123456789</account_number>
      <bank_code>70011110</bank_code>
      <bank_name>Deutsche Handelsbank</bank_name>
      <bic>DEKTDE7GXXX</bic>
      <iban>DE0370011110123456789</iban>
      <country_code>DE</country_code>
    </recipient>
    <costs>
      <fees>0.00</fees>
      <currency_code>EUR</currency_code>
      <exchange_rate>1.0000</exchange_rate>
    </costs>
    <paycode>
        <code>6c9d197ddb</code>
    </paycode>
    <status_history_items>
      <status_history_item>
        <status>pending</status>
        <status_reason>not_credited_yet</status_reason>
        <time>2013-04-02T14:19:08+01:00</time>
      </status_history_item>
    </status_history_items>
  </transaction_details>
</transactions>

Statusmeldungen

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

Eine Transaktion wird erst dann bei SOFORT 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, bekommen Sie bei einer Anfrage der Transaktionsdaten zu einer übergebenen Transaktions-ID nur eine Antwort mit leerem <transactions /> Tag zurück.

Sofern die SOFORT Überweisung 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 SOFORT 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, ohne eine Konto bei der Deutschen Handelsbank als Empfängerkonto, wird Ihnen nach erfolgreicher Durchführung der SOFORT Überweisung immer der Status "untraceable" angezeigt.

Weitere Detailinformationen zu möglichen Status und deren Beschreibung finden Sie in der Parameterübersicht zu API-Schritt 5.

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

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

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" ?>
<new_paycode>
    ...
    <warnings>
        <warning>
            <code>8049</code>
            <message>Unsupported language.</message>
            <field>language_code</field>
        </warning>
    </warnings>
</new_paycode>

bzw.

<?xml version="1.0" encoding="UTF-8" ?>
<errors>
    <error>
        <code>6100</code>
        <message>Paycode request could not be processed.</message>
        </error>
</errors>

bzw.

<?xml version="1.0" encoding="UTF-8" ?>
<errors>
    <error>
        <code>8014</code>
        <message>Invalid amount.</message>
        <field>amount</field>
    </error>
</errors>

4.9. Abruf des Status eines Paycodes (API-Schritt SR-1)

Wenn Sie vorher einen Paycode generiert haben, können Sie dessen Status mit folgendem Abruf abfragen. Dieser erwartet lediglich die Übergabe des vorher generierten Paycodes:

<?xml version="1.0" encoding="UTF-8" ?>
<paycode_request version="2">
   <paycode>6c9d197ddb</paycode>
</paycode_request>

4.10. Antwort auf Statusabruf eines Paycodes (API-Schritt SR-2)

Als Antwort auf die Abfrage eines konkreten Paycodes erhalten Sie alle Informationen des Paycodes. Die Parameter sowie deren Beschreibungen, die eine Antwort enthalten kann, finden Sie in der Parameterübersicht.

<?xml version="1.0" encoding="UTF-8" ?>
<paycode_details>
  <status>open</status>
  <paycode>6c9d197ddb</paycode>
  <project_id>53245</project_id>
  <amount>2.2</amount> 
  <reasons> 
    <reason>Rasenmäher</reason> 
    <reason>Bleistift</reason> 
  </reasons> 
  <time_created>2015-04-10T10:01:07+02:00</time_created> 
  <time_used>2015-04-10T10:55:43+02:00</time_used> 
  <start_date>2015-01-01T00:00:00+01:00</start_date> 
  <end_date>2015-12-12T23:59:59+01:00</end_date> 
  <max_usage>5</max_usage>
  <currency_code>EUR</currency_code> 
  <language_code>DE</language_code> 
  <sender> 
    <bank_code>00000</bank_code> 
    <bic>SKGIDE5FXXX</bic> 
    <country_code>DE</country_code> 
  </sender> 
  <user_variables> 
    <variable>Variable 1</variable> 
    <variable>Variable 2</variable> 
  </user_variables> 
  <transactions> 
    <transaction>99999-53245-5527834B-437A</transaction> 
    <transaction>99999-53245-55278802-16BB</transaction> 
    <transaction>99999-53245-5527900F-5F33</transaction> 
  </transactions>
</paycode_details>

Die Felder transaction und time_used haben erst dann einen Rückgabewert, wenn der Paycode eingelöst wurde.

4.11. Aufruf der API zum Ändern eines Paycodes (API-Schritt M-1)

Wenn Sie vorher einen Paycode generiert haben, können Sie diesen anpassen. Dabei können Sie alle Parameter des initialen API Aufrufs (API-Schritt 1) bis auf <project_id> und <interface_version> angepasst übergeben. Nur die Parameter, die tatsächlich geändert werden sollen, müssen übergeben werden. Alle anderen Parameter behalten ihre vorherigen Werte.

Achtung: Sofern Sie die Gültigkeitsintervalle ändern möchten übergeben Sie bitte eine neue Auflistung an Intervallen mit den entsprechenden Werten. Möchten Sie die Gültigkeitsintervalle löschen, übergeben Sie bitte <intervals></intervals>.

Ein beispielhafter Aufruf kann wie folgt aussehen:

<?xml version="1.0" encoding="UTF-8" ?>
<edit_paycode>
   <paycode>6c9d197ddb</paycode>
   <amount>5.50</amount>
   <minimal_amount>4.00</minimal_amount>
   <start_date>2014-12-01T00:00:00+01:00</start_date>
   <max_usage>30</max_usage>
   <reasons>
      <reason>Reason Line 1 changed</reason>
   </reasons>
   <intervals>
      <interval>
         <from_date>2014-12-15</from_date>
         <amount>6.60</amount>
         <minimal_amount>5.00</minimal_amount>
         <reasons>
            <reason>Reason Line 1 new</reason>
            <reason>Reason Line 2 new</reason>
         </reasons>
      </interval>
      <interval>
         <from_date>2014-12-20</from_date>
         <amount>7.70</amount>
         <minimal_amount>6.00</minimal_amount>
         <reasons>
            <reason>Reason Line 1 newer</reason>
         </reasons>
      </interval>
   </intervals>
</edit_paycode>

4.12. Antwort der API zum geänderten Paycode (API-Schritt M-2)

Als Antwort auf den Änderungsaufruf erhalten Sie den Paycode sowie die Statusnachricht "edited":

<?xml version="1.0" encoding="UTF-8" ?>
<edit_paycode>
   <paycode>6c9d197ddb</paycode>
   <paycode_url>https://www.sofort.com/paycode/6c9d197ddb</paycode_url>
   <status>edited</status>
</edit_paycode>

4.13. Aufruf der API zur Deaktivierung eines Paycodes (API-Schritt DA-1)

Zur Deaktivierung eines bereits erstellten Paycodes können Sie folgenden Aufruf an die API schicken. Anschließend kann ein solcher Paycode nicht mehr eingelöst werden.

<?xml version="1.0" encoding="UTF-8" ?>
<deactivate_paycode>
   <paycode>6c9d197ddb</paycode>
</deactivate_paycode>

4.14. Antwort der API mit Bestätigung der Deaktivierung (API-Schritt DA-2)

Die Bestätigung zur Deaktivierung eines Paycodes lautet wie folgt:

<?xml version="1.0" encoding="UTF-8" ?>
<deactivate_paycode>
   <paycode>6c9d197ddb</paycode>
   <status>deactivated</status>
</deactivate_paycode>

4.15. Aufruf der API zur Reaktivierung eines Paycodes (API-Schritt RA-1)

Zur Reaktivierung eines vorher deaktivierten Paycodes können Sie folgenden Aufruf an die API schicken. Anschließend kann der Paycode mit den zuvor eingerichteten Parametern weiter verwendet werden.

<?xml version="1.0" encoding="UTF-8" ?>
<activate_paycode>
   <paycode>6c9d197ddb</paycode>
</activate_paycode>

4.16. Antwort der API mit Bestätigung der Reaktivierung (API-Schritt RA-2)

Die Bestätigung zur Reaktivierung eines Paycodes lautet wie folgt:

<?xml version="1.0" encoding="UTF-8" ?>
<activate_paycode>
   <paycode>6c9d197ddb</paycode>
   <status>activated</status>
</activate_paycode>

5. Testen

Um die Funktionalität Ihrer Integration des SOFORT Überweisung Paycode komplett zu testen, führen Sie bitte eine Testerstellung inkl. anschließender Testüberweisung direkt über Ihr System aus. Befolgen Sie dabei folgende Schritte:

  • Testmodus aktivieren
  • Test-Paycode generieren
  • 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.

5.1. Testmodus aktivieren

Aktivieren des Testmodus in Ihrem Paycode-Projekt im Händlerbereich auf der Webseite von SOFORT.

5.2. Test-Paycode generieren

Erstellen Sie einen Paycode über Ihr System und den Aufruf der XML-Schnittstelle.

5.3. Testtransaktion durchführen
  • Öffnen Sie den URL https://www.sofort.com/paycode und geben Sie den zuvor generierten Test-Paycode ein.
  • Überprüfen Sie auf dem Zahlformular von SOFORT 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 wählen Sie "Andere" und "999" (3x die Ziffer "9") und für alle anderen Länder "00000" (5x die Ziffer "0") bzw. "Demo Bank". (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.
5.4. 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?

6. Parameterübersicht

Im Folgenden finden Sie 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
6.1. (API-Schritt 1) Initialer Aufruf der API und Übergabe der Transaktionsparameter
6.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.

6.2. Zahldatenübergabe zur Paycode Generierung

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
paycode [1] Container Identifiziert den Paycode API-Aufruf, umschließt die komplette Nachricht
  project_id [1] Integer Projektnummer
  interface_version [0,1] String (255) Version der Shopschnittstelle, z. B. „xt:commerce_v4.1.0“
  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.
  start_date [0,1] String (25) Gültigkeitsbeginn eines Paycodes im Format "YYYY-MM-DDThh:mm:ss+HH:mm" (alternativ auch "YYYY-MM-DD hh:mm:ss"; Zeitzone MEZ/MESZ werden angenommen) - muss vor dem Enddatum liegen. Sofern der Start nicht angegeben wird, gilt der Paycode ab seiner Erstellung.
  end_date [0,1] String (25) Gültigkeitsende eines Paycodes im Format "YYYY-MM-DDThh:mm:ss+HH:mm" (alternativ auch "YYYY-MM-DD hh:mm:ss"; Zeitzone MEZ/MESZ werden angenommen) - muss in der Zukunft liegen (max. 900 Tage ab Startdatum). Sofern das Ende nicht angegeben wird, folgt hier automatisch das Datum des Ablaufs der im Projekt hinterlegten „Max. Gültigkeit in Tagen“ (um 23:59:59).
  amount [1]* Decimal (8.2)

Betrag, Format: keine Tausender-Trennzeichen, zwei Nachkommastellen, mit Punkt "." getrennt. Beispiel: "150.00" (150 Euro)

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

*Sofern in den Projekteinstellungen bei SOFORT die Option "Kunde darf Betrag editieren" aktiviert ist, ist dies kein Pflichtparameter.

  minimal_amount [0,1] Decimal (8.2)

Der Betrag, den ein Zahlender mindestens überweisen muss (wird nur berücksichtigt, falls die Funktion "Kunde darf Betrag editieren" in den Projekteinstellungen aktiviert ist).

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 [0,1] String (3) Währung nach ISO 4217 z. B. "EUR"; sofern kein Wert übergeben wurde, wird als Default-Wert "EUR" gesetzt.
  max_usage [0,1] Integer Die Anzahl der möglichen Einlösungen des Paycodes. Mögliche Werte: 1-999999 (muss durch SOFORT freigeschaltet werden)
  sender [0,1] Container Absenderkonto Ihres Kunden
    bank_code [0,1] String (30) DEPRECATED: BLZ des Kontos Ihres Kunden, bitte stattdessen <bic> benutzen
    bic [0,1] String (11) BIC des Kontos Ihres Kunden
    country_code [0,1] String (2) Länderkürzel des Landes, in dem das Kundenkonto liegt, nach ISO 3166-1, z. B. "de"
  reasons [1] Container Liste mit Verwendungszwecken
    reason [1..2] String (27)

Verwendungszweck; bitte übergeben Sie einen eindeutigen Wert (z. B. Bestellnummer); nur folgende Zeichen sind 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 sowie Benachrichtigungen) kann deshalb ein veränderter String für den ersten und zweiten reason-Tag zurückgegeben werden.

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.

  intervals [0,1] Container Container, der eine Auflistung an Gültigkeitsintervallen beinhaltet. Pro Gültigkeitsintervall können gewisse Parameter einen bestimmten Wert annehmen, der nur für dieses Intervall gültig ist.
    interval [0,n] Container Container, der die Details für ein Gültigkeitsintervall beinhaltet.
      from_date [1] String (19) Startdatum eines Gültigkeitsintervalls im Format "YYYY-MM-DD". Das Intervall gilt entweder bis zum Startdatum eines weiteren Intervalls bzw. falls es kein weitere Intervall mit späterem Startdatum gibt, bis zum Ende des Gültigkeitszeitraums des Paycodes. Das Datum muss zeitlich vor dem <end_date> des Paycodes liegen (d.h. das <end_date> muss weiter in der Zukunft liegen als das Startdatum des Intervalls).
      amount [0,1]* Decimal (8.2)

Betrag der für das Gültigkeitsintervall gilt; Format: keine Tausender-Trennzeichen, zwei Nachkommastellen, mit Punkt "." getrennt. Beispiel: "150.00" (150 Euro)

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

* Mind. eines der Elemente <amount>, <minimal_amount> oder <reasons> muss übergeben werden.

      minimal_amount [0,1]* Decimal (8.2)

Der Betrag, den ein Zahlender mindestens überweisen muss (wird nur berücksichtigt, falls die Funktion "Kunde darf Betrag editieren" in den Projekteinstellungen aktiviert ist).

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

* Mind. eines der Elemente <amount>, <minimal_amount> oder <reasons> muss übergeben werden.

      reasons [0,1]* Container

Liste mit Verwendungszwecken, die während des Gültigkeitsintervalls gelten.

* Mind. eines der Elemente <amount>, <minimal_amount> oder <reasons> muss übergeben werden.

        reason [1..2] String (27)

Verwendungszweck im Gültigkeitsintervall; bitte übergeben Sie einen eindeutigen Wert (z. B. Bestellnummer); nur folgende Zeichen sind 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 sowie Benachrichtigungen) kann deshalb ein veränderter String für den ersten und zweiten reason-Tag zurückgegeben werden.

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.

  success_url [0,1] String (255) Erfolgslink, überschreibt den Default-Wert aus den Projekteinstellungen. Sofern die Transaktionsnummer der SOFORT Überweisung als Teil der URL genutzt werden soll, kann der Ersetzungsparameter '-TRANSACTION-' verwendet werden.
  success_link_redirect [0,1] Boolean Autom. Weiterleitung auf Erfolgsseite. Sofern nicht aktiviert, wird Ihrem Kunden eine Zusammenfassungsseite von SOFORT GmbH angezeigt.
  abort_url [0,1] String (255) Abbruchlink, überschreibt den Default-Wert aus den Projekteinstellungen. Sofern die Transaktionsnummer der SOFORT Überweisung 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; Eine exemplarische Übergabe finden Sie im Beispiel XML-Aufruf. Sofern die Transaktionsnummer der SOFORT Überweisung 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 kommasepariert Status angegeben werden. Bspw: <notification_url

notify_on=“pending, loss“>

Mögliche Status: "pending", "received", "loss", "refunded".

  notification_emails [0,1] Container Liste mit Benachrichtigungs-E-Mail-Adressen
    notification_email [0..10] String (255) Benachrichtigungs-E-Mail-Adresse
    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 kommasepariert Status angegeben werden. Bspw: <notification_email

notify_on=“pending, loss“>

Mögliche Status: "pending", "received", "loss", "refunded".

  user_variables [0,1] Container Liste mit Variablen, die Sie frei belegen können
    user_variable [0,20] String (255) Variable, die Sie frei belegen können

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

6.3. (API-Schritt 2) Antwort der API mit generiertem Paycode und Zahlungs-URL

Als Antwort auf den Aufruf unserer Schnittstelle erhalten Sie einen Paycode und einen URL zum Zahlungsformular, auf den Sie Ihren Kunden weiterleiten können. U.U. Enthält die Antwort auch eine Warnung.

Parameter Anzahl Typ (Länge) Erklärung
new_paycode [0,1] Container Identifiziert die Antwort auf einen Paycode API-Aufruf, umschließt die komplette Nachricht
  paycode [1] String (10) Der generierte Paycode, der zur Weiterleitung an Ihren Kunden gedacht ist
  paycode_url [1] String (255) Der Link zum Zahlformular mit angehängtem Paycode. Führt Ihren Kunden sofort auf das richtige Zahlungsformular
  warnings [0,1] Container Warnungsliste
    warning [1..n] Container Warnungsliste
      code [1] Integer Warnungsnummer
      message [1] String (255) Warnungsmeldung
      field [1] String (255) Feld, auf das sich die Warnung bezieht
errors [0,1] Container Fehler (Definition siehe unten) - kann alternativ zum Tag <new_paycode> zurückgegeben werden.
  ...      

Tabelle 2: Parameterdefinition der Antwort des initialen Aufrufs mit generiertem Paycode (API-Schritt 2)

6.4. (API-Schritt 3) Benachrichtigung über eine Änderung des Transaktionsstatus (sofern konfiguriert)

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. 2010-06-17T18:30:00+02:00

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

6.5. (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
  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 Transaktionendie 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 abgeschlossen wurden. Default: Aufrufzeitpunkt.

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 ("paycode": SOFORT Überweisung Paycode, "payment": SOFORT Überweisung)
  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)

6.6. (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 des Aufrufs (mit Zeitzone) nach ISO 8601 im Format „YYYY-MM-DDThh:mm:ss+HH:mm“, z. B. 2013-03-13T08:59:00+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-13T08:59:00+01:00
    payment_method [1] String (7) Zahlmethode die benutzt wurde ("paycode" - für SOFORT Überweisung Paycode – weitere: su)
    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 (kann auch ein Teilbetrag des ursprünglichen Betrages sein)
    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) DEPRECATED: Kontonummer
      bank_code [1] String (30) DEPRECATED: 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) E-Mail-Adresse Ihres Kunden
    phone_customer [1] String (255) Telefonnummer Ihres Kunden
    exchange_rate [1] Decimal (8.4) Umrechnungskurs
    recipient [1] Container Daten des Überweisungs-Empfängers (Bankkonto des Anbieters)
      holder [1] String (27) Kontoinhaber
      account_number [1] String (30) DEPRECATED: Kontonummer
      bank_code [1] String (30) DEPRECATED: 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
    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 der Gebühren nach ISO 4217 (z. B. EUR)
      exchange_rate [1] Decimal (8.4) Umrechnungskurs
    paycode [1] Container Container für Einträge zum Paycode
      code [1] String(10) Zur Transaktion zugeordneter Paycode
    status_history_items [1] Container Container für Einträge der Statushistorie
      status_history_item [0..n] Container Untercontainer für einzelne 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; Datum und Uhrzeit (mit Zeitzone) nach ISO 8601 im Format

YYYY-MM-DDThh:mm:ss+HH:mm z.B. 2010-06-17T18:30:00+02: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)

Statusmeldungen

In einer Transaktionsdetailnachricht ist auch stets ein Status der Transaktion enthalten, sofern ein Konto bei der Deutschen Handelsbank vorhanden ist.

<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 Überweisung Paycode und Konto bei der Deutschen Handelsbank

<transactions><transaction_details><status> <transactions><transaction_details><status_reason> Bedeutung
untraceable sofort_bank_account_needed Die Paycode Transaktion 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 Überweisung Paycode ohne Konto bei der Deutschen Handelsbank

6.7. (API-Schritt SR-1) Abruf des Status eines Paycodes

Zusätzlich steht für die Statusabfrage eines vorher erstellten Paycodes eine weitere Abfragemöglichkeit der API zur Verfügung.

Parameter Anzahl Typ (Länge) Erklärung
paycode_request version="2" [1] Container Identifiziert den Status Abruf eines übergebenen Paycodes, umschließt die komplette Nachricht
  paycode [1] String (10) Paycode, dessen Status abgefragt werden soll

Tabelle 8: Parameterdetails für den Abruf des Status eines Paycodes

6.8. (API-Schritt SR-2) Antwort auf Statusabruf eines Paycodes
Parameter Anzahl Typ (Länge) Erklärung
paycode_details [1] Container Identifiziert den Paycode API-Aufruf, umschließt die komplette Nachricht
  status [1] String (20) Status des Paycodes (open, used, expired, deactivate)
  paycode [1] String (10) Paycode, dessen Status abgefragt wurde
  project_id [1] Integer Projektnummer, welcher der Paycode zugeordnet ist
  transactions [1] Container Liste von Transaktionsnummern; kann leer sein, sofern zum Paycode bisher keine Transaktion durchgeführt wurde
    transaction [0..n] String (27) Transaktionsnummer
  amount [1] Decimal (8.2) Betrag, der bei Paycode-Erstellung angegeben wurde
  reasons [1] Container Liste mit Verwendungszwecken
    reason [1..2] String (27) Verwendungszweck
  time_created [1] String (25) Zeitpunkt zu dem der Paycode erstellt wurde (mit Zeitzone) nach ISO 8601 im Format „YYYY-MM-DDThh:mm:ss+HH:mm“, z.B. 2013-03-13T08:59:00+01:00
  time_used [0,1] String (25) Zeitpunkt der Einlösung des Paycodes; ist nur gesetzt, wenn der Paycode eingelöst wurde, ansonsten ist der Tag leer (mit Zeitzone) nach ISO 8601 im Format „YYYY-MM-DDThh:mm:ss+HH:mm“, z.B. 2013-03-13T08:59:00+01:00
  start_date [0,1] String (25) Zeitpunk zu dem die Gültigkeit des Paycodes beginnt (mit Zeitzone) nach ISO 8601 im Format „YYYY-MM-DDThh:mm:ss+HH:mm“, z.B. 2013-03-13T08:59:00+01:00
  end_date [0,1] String (25) Zeitpunkt zu dem die Gültigkeit des Paycodes abläuft (mit Zeitzone) nach ISO 8601 im Format „YYYY-MM-DDThh:mm:ss+HH:mm“, z.B. 2013-03-13T08:59:00+01:00
  max_usage [1] Integer Die Anzahl der möglichen Einlösungen des Paycodes (muss durch SOFORT freigeschaltet werden)
  currency_code [1] String (3) Währung nach ISO 4217 (z.B. EUR)
  language_code [0,1] String (2) Sprache nach ISO 639-1
  sender [0,1] Container Daten des Überweisungs-Absenders (Bankkonto Ihres Kunden)
    bank_code [1] String (30) DEPRECATED: BLZ
    bic [1] String (11) BIC
    country_code [1] String (2) Länderkürzel nach ISO 3166-1
  user_variables [0,1] Container Liste mit Benutzervariablen
    variable [0..20] String (255) Benutzervariable
errors [0,1] Container Fehler (Definition siehe unten) - kann alternativ zum Tag <paycode_details> zurückgegeben werden
  ...      

Tabelle 9: Parameterdetails für die Antwort auf den Statusabruf eines Paycodes

Bzgl. der Tags "sender" und "user_variables"  ist zu beachten, dass die Daten immer den Daten entsprechen, die bei der Erstellung des Paycodes übergeben wurden. So können z.B. die sender-Daten zwischen Paycode und Transaktion unterschiedlich sein.

6.9. (API-Schritt M-1) Aufruf der API zum Ändern eines Paycodes

Bestehende Paycodes können angepasst werden, wobei folgende Parameter verwendet werden können:

Parameter Anzahl Typ (Länge) Erklärung
edit_paycode [1] Container Identifiziert den Änderungsaufruf für einen übergebenen Paycode, umschließt die komplette Nachricht
  paycode [1] String (10) Paycode, der geändert werden soll
  ... ... ... [alle Tags aus API-Schritt 1 möglich, mit Ausnahme von <project_id> und <interface_version>]

Tabelle 10: Parameterdetails für den Änderungsauruf eines Paycodes

6.10. (API-Schritt M-2) Antwort der API zum geänderten Paycode

Eine Antwort auf den Änderungsaufruf enthält folgende Parameter:

Parameter Anzahl Typ (Länge) Erklärung
edit_paycode [0,1] Container Identifiziert die Antwort auf einen Paycode API-Änderungsaufruf, umschließt die komplette Nachricht
  paycode [1] String (10) Der Paycode, der geändert wurde
  paycode_url [1] String (255) Der Link zum Zahlformular mit angehängtem Paycode. Führt Ihren Kunden sofort auf das richtige Zahlungsformular
  status [1] String (6) Status "edited"
  warnings [0,1] Container Warnungsliste
    warning [1..n] Container Warnung
      code [1] Integer Warnungsnummer
      message [1] String (255) Warnungsmeldung
      field [0,1] String (255) Feld, auf das sich die Warnung bezieht
errors [0,1] Container Fehler (Definition siehe unten) - kann alternativ zum Tag <edit_paycode> zurückgegeben werden.
  ... ... ...  

Tabelle 11: Parameterdetails für die Antwort auf einen Änderungsauruf eines Paycodes

6.11. (API-Schritt DA-1) Aufruf der API zur Deaktivierung eines Paycodes

Bestehende Paycodes können deaktiviert werden, wodurch anschließend ein solcher Paycode nicht mehr eingelöst werden kann. Folgende Parameter sind hierfür notwendig:

Parameter Anzahl Typ (Länge) Erklärung
deactivate_paycode [1] Container Identifiziert den Aufruf zur Deaktivierung eines Paycodes, umschließt die komplette Nachricht
  paycode [1] String (10) Paycode, der deaktiviert werden soll

Tabelle 12: Parameterdetails für den Auruf zur Deaktivierung eines Paycodes

6.12. (API-Schritt DA-2) Antwort der API mit Bestätigung der Deaktivierung

Eine Antwort auf den Aufruf zur Deaktivierung eines Paycode enthält folgende Parameter:

Parameter Anzahl Typ (Länge) Erklärung
deactivate_paycode [0,1] Container Identifiziert die Antwort zur Deaktivierung eines Paycodes, umschließt die komplette Nachricht
  paycode [1] String (10) Der Paycode, der deaktiviert wurde
  status [1] String (6) Status "deactivated"
  warnings [0,1] Container Warnungsliste
    warning [1..n] Container Warnung
      code [1] Integer Warnungsnummer
      message [1] String (255) Warnungsmeldung
      field [0,1] String (255) Feld, auf das sich die Warnung bezieht
errors [0,1] Container Fehler (Definition siehe unten) - kann alternativ zum Tag <deactivate_paycode> zurückgegeben werden.
  ... ... ...  

Tabelle 13: Parameterdetails für die Antwort der Deaktivierung eines Paycodes

6.13. (API-Schritt RA-1) Aufruf der API zur Reaktivierung eines Paycodes

Deaktivierte Paycodes können reaktiviert werden, wodurch anschließend ein solcher Paycode wieder eingelöst werden kann. Die vorher gesetzten Parameter sind nun wieder gültig. Folgende Parameter sind hierfür notwendig:

Parameter Anzahl Typ (Länge) Erklärung
activate_paycode [1] Container Identifiziert den Aufruf zur Reaktivierung eines Paycodes, umschließt die komplette Nachricht
  paycode [1] String (10) Paycode, der reaktiviert werden soll

Tabelle 14: Parameterdetails für den Auruf zur Reaktivierung eines Paycodes

6.14. (API-Schritt RA-2) Antwort der API mit Bestätigung der Reaktivierung

Eine Antwort auf den Aufruf zur Reaktivierung eines Paycode enthält folgende Parameter:

Parameter Anzahl Typ (Länge) Erklärung
activate_paycode [0,1] Container Identifiziert die Antwort zur Reaktivierung eines Paycodes, umschließt die komplette Nachricht
  paycode [1] String (10) Der Paycode, der deaktiviert wurde
  status [1] String (6) Status "activated"
  warnings [0,1] Container Warnungsliste
    warning [1..n] Container Warnung
      code [1] Integer Warnungsnummer
      message [1] String (255) Warnungsmeldung
      field [0,1] String (255) Feld, auf das sich die Warnung bezieht
errors [0,1] Container Fehler (Definition siehe unten) - kann alternativ zum Tag <activate_paycode> zurückgegeben werden.
  ... ... ...  

Tabelle 15: Parameterdetails für die Antwort der Reaktivierung eines Paycodes

6.15. 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
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 16: Parameterdefinition der 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 leere POST Daten
7005 Project has no Deutsche Handelsbank account. Es ist kein Konto bei der Deutschen Handelsbank im 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 17: Allgemeine Fehler

Fehlercodes für Paycode Requests (API-Schritt 1, API-Schritt 6, API-Schritt M-1, API-Schritt DA-1  & API-Schritt RA-1)

Code Message Beschreibung
6100 Paycode request could not be processed Der Paycode Aufruf konnte nicht erfolgreich durchgeführt werden, weil z. B. das Projekt für Paycode nicht freigeschaltet ist, der Testmodus nicht läuft, das Projekt nicht dem Anbieter gehört, ein übergebener Paycode nicht im System gefunden werden konnte.
6101 Provide valid future datetime Datum liegt in der Vergangenheit.
6102 Invalid date format. Falsches Datumsformat für das Feld 'start_date' oder 'end_date' übergeben. Korrektes Format: YYYY-MM-DD HH-MM-SS. Feld darf auch leer bleiben.
6103 Start date has to be earlier than end date. Das Startdatum muss for dem Enddatum liegen.
6104 A paycode can only be used for maximal 900 days. Das Intervall zwischen Startdatum und Enddatum ist zu groß und darf maximal 900 Tage betragen.
6105 Interval start date has to be in the validity period of the paycode. Das Startdatum eines Gültigkeitsintervalls muss zwischen Startdatum und Enddatum des Paycodes liegen.
6106 Provide a valid start date for the interval. Es wurde kein oder ein fehlerhaftes Startdatum für ein Gültigkeitsintervall übergeben.
6107 Invalid parameter in interval provided. Innerhalb des Tags <interval> wurde ein nicht erlaubter Parameter übergeben.
6108 Provide at least one parameter for an interval. Innerhalb des Tags <interval> wurde weder <amount> noch <reasons> übergeben.
6109 This paycode has already been used and cannot be changed anymore. Der Paycode wurde bereits eingelöst und kann daher nicht mehr geändert werden.
6110 This paycode has already been deactivated. Der Paycode wurde bereits deaktiviert.
6111 This paycode is already active. Der Paycode ist bereits aktiviert.
6112 End date was updated automatically based on project settings. Provide end_date in the API request to change it manually. Das Enddatum wurde automatisch auf Basis der Projekteinstellungen in die Zukunft verschoben, da bei der Änderung des Paycodes nur das Startdatum und kein Enddatum übergeben wurde.
6113 The code has already been used and cannot be changed anymore. Der Paycode wurde bereits eingelöst und kann daher nicht mehr geändert werden.
6114 End date has to be after the start date. Das Enddatum muss zeitlich nach dem Startdatum liegen.
6115 Changing start_date or end_date of the Paycode may affect the validity of intervals. Durch die Änderung des Startdatums oder des Enddatums des Paycodes können weitere Gültigkeitsintervalle ggf. ungültig werden.
6116 The paycode is in use and therefore locked for 30 minutes. Please try again later. Der Paycode wurde gerade aufgerufen und ist daher für 30 Minuten gesperrt. Sofern der Paycode nicht eingelöst wurde kann er nach 30 Minuten wieder aufgerufen werden.
6117 The minimal amount is higher than the paycode amount. Der Minimalbetrag den ein Zahlender zahlen muss ist größer als der aktuelle Paycode Betrag.
6118 The minimum amount is only relevant, if the consumer is allowed to change the amount. Der Minimalbetrag ist nur dann sinnvoll zu setzen, wenn in den Projekteinstellungen das Feature aktiviert ist, dass der Zahlende den Betrag editieren darf.
6119 The amount of the interval may not be smaller than the minimal amount of the paycode Der Betrag in einem übergebenenen Gültigkeitsintervall darf nicht kleiner sein als der Minimalbetrag, der vom Zahlenden gezahlt werden muss.
6120 No paycode provided. Ein obligatorischer Paycode fehlt. Bitte wiederholen Sie den Aufruf und übergeben Sie dabei einen Paycode.
6122 Value for maximal usage of the paycode is out of range. Die Anzahl der maximalen Verwendungen muss zwischen 1 und 999999 liegen.

Tabelle 18: Spezielle Fehler bei Paycode Requests

Fehlercodes für Transaction Request/Response (API-Schritt 1)

Code Message Kommentar
8000 No project ID provided Es wurde keine Projekt-ID übergeben
8001 Unknown project Unbekanntes Projekt
8002 Validation Error  
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 Tag für eine Zahlart ü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
8024 only German addresses (DE) are supported Es wurde eine ausländische Adresse angegeben für die Rechnungs- oder Lieferadresse angegeben.
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>).
8042 consumer protection is only available for sender accounts from DE, AT and CH Der Käuferschutz ist nur für Absenderkonten aus DE, AT und Ch möglich.
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 chars 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 ist keine Zahlungen in der gewünschten Währung möglich sind
8060 Blacklisted Die Zahlung kann nicht ausgeführt werden, da entweder die übergebene Bankverbindung oder 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 19: Spezielle Fehler/Warnungen

Fehlercodes für Transaction Details Request/Response (API-Schritt 4)

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ß

Tabelle 20: Fehler bei der Abfrage der Transaktionsdetails

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

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

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