API Dokumentation

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.

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:

• (API-Schritt SR-1) Abruf des Status eines Paycodes
• (API-Schritt SR-2) Antwort auf Statusabruf eines Paycodes

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

• (API-Schritt M-1) Aufruf der API zum Ändern eines Paycodes
• (API-Schritt M-2) Antwort der API zum geänderten Paycode

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

• (API-Schritt DA-1) Aufruf der API zur Deaktivierung eines Paycodes
• (API-Schritt DA-2) Antwort der API mit Bestätigung der Deaktivierung
• (API-Schritt RA-1) Aufruf der API zur Reaktivierung eines Paycodes
• (API-Schritt RA-2) Antwort der API mit Bestätigung der Reaktivierung

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

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

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

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

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

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.

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.

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.

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.

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.

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:

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.

Tabelle 6: Statusmeldungen für Transaktionen mit SOFORT Überweisung Paycode und Konto bei der Deutschen Handelsbank

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.

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

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

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:

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:

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:

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:

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:

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:

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.

Tabelle 16: Parameterdefinition der Antwort bei Fehler

Fehlercodes

Allgemeine Fehler bei Aufruf

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)

Tabelle 18: Spezielle Fehler bei Paycode Requests

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

Tabelle 19: Spezielle Fehler/Warnungen

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

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.