easyCredit-RatenkaufAnleitung Eigenintegration easyCredit-Ratenkauf

Überblick

Dieses Kapitel soll einen kurzen Überblick zu den folgenden Themen liefern:

• Allgemeine Informationen zum easyCredit-Ratenkauf
• Beschreibung des fachlichen Prozesses
• Eckdaten der Ratenkaufumgebung
• Allgemeine Informationen zur Anbindung des Ratenkaufs
• Zugang zum Demoshop

Allgemeine Informationen

Mittels des „easyCredit-Ratenkauf“ kann ein Händler seinen Kunden auf einfache Weise die Möglichkeit einer Ratenzahlung bieten. Der finale Abschluss erfolgt sofort im Rahmen des Online-Bestellprozesses auf Basis eines „echten Factorings“: Die Bank übernimmt für den Händler die Bonitätsprüfung und im Falle eines Abschlusses vom Händler für den geprüften Fall die Zahlungsforderung gegenüber dem Kunden – inklusive des Risikos seiner Zahlungsunfähigkeit.
Die technische Anbindung des easyCredit-Ratenkauf erfolgt über Web Services in Form von REST-Ressourcen , ihr Aufruf kann per JSON oder XML erfolgen. In den Beispielen dieses Dokuments wird eine Anbindung der Web-Services mit JSON demonstriert.

Prozessablauf

Die nachfolgende Grafik zeigt den fachlichen Prozessablauf einer Ratenkaufbestellung. In der Integrationsvariante „Payment-Page“ wird es dem Händler ermöglicht das Produkt ratenkauf by easyCredut über Verlinkung einer bei der TeamBank gehosteten Bezahlseite in seinem Webshop zu integrieren.

Die einzelnen Bestellprozessschritte sind nachfolgend skizziert:

1. Auswahl

   • Die Auswahl des Ratenkaufs als Bezahlvariante erfolgt im Webshop
   • Als Entscheidungshilfe für den Käufer stellt die TeamBank dem Webshop einen Ratenkaufbeispielrechner als Service zur Verfügung
   • Der Kunde muss der Übermittlung seiner Daten zu TeamBank zustimmen.

2. Initialisierung:

   • Die Initialisierung eines Ratenkaufvorgangs erfolgt auf Grundlage einer eindeutigen Vorgangskennung für den Informationsaustausch mit dem Webshop und der Zuordnung auf Seite der TeamBank
   • Sicherstellung eines nichtmanipulierbaren Austauschs von Daten zwischen den Parteien Webshop und TeamBank über eine SSL gesicherte Verbindung und einer Authentifizierung per Webshopspezifischen Token.
   • Übergabe und Validierung von Daten, die im Rahmen des Shoppingvorgangs im Webshop erfasst wurden und für den Ratenkauf relevant sind
   • Erzeugung eines einmaligen und eindeutigen Tokens für den nachgelagerten Informationsaustausch mit Device Ident

3. Erfassung:

   • Erfassung von Kundendaten, die für den Ratenkauf erforderlich sind, jedoch nicht im Rahmen des Shoppingvorgangs im Webshop erhoben wurden
   • Bei der Initialisierung übergebene Daten können nicht mehr geändert werden

4. Zustimmung

   • Einholung der Zustimmungserklärungen des Käufers zur Datenspeicherung bei der TeamBank, zur Bonitätsprüfung durch die TeamBank unter Einbeziehung externer Auskunfteien und zur Erhebung und Auswertung gerätespezifischer Daten durch Device Ident
   • Erteilung des SEPA-Lastschriftmandats für den Einzug der Kreditraten durch den Käufer an die TeamBank mittels elektronischer Zustimmung

5. Entscheidung:

   • Einbeziehung des Entscheidungsbausteins für die Herbeiführung einer verbindlichen Kreditentscheidung inklusive Identitäts- und Betrugsfallprüfung
   • Speicherung der Kunden- und Antragsdaten inklusive des vollständigen Entscheidungs-ergebnisses

6. Annahme:

   • Darstellung des Entscheidungsergebnisses inkl. entsprechender Hinweistexte aus dem Entscheidungsbaustein
   • Entscheidung kann positiv („GRÜN“), negativ („ROT“) oder positiv, jedoch mit Anpassung der Wunschlaufzeit ausfallen.
   • Im Falle einer Ablehnung („ROT“) wird dem Käufer die Rückführung in den Checkout-Prozess angeboten
   • Im Falle einer positiven Entscheidung („GRÜN“) kann der Käufer die Laufzeit im Rahmen der durch die Kreditentscheidung vorgegebenen Grenzen anpassen und anschließend das Finanzierungsangebot annehmen

7. Bestätigung:

   • Darstellung aller Details der Bestellung, d.h. inkl. der gewählten Ratenkauf-Finanzierung (mit Laufzeit und Zinsen) im Webshop
   • Verbindliche Käuferentscheidung für den Ratenkauf mit dem zuvor berechneten Ratenplan
   • Übermittlung der Bestellbestätigung vom Webshop an die TeamBank und Prüfung der Response

Umgebung

Der Ratenkauf wird bei der TeamBank in einer gesicherten Umgebung als hochverfügbares System betrieben.

Protokoll	https
Hostname	ratenkauf.easycredit.de
URL-Einstieg in die Payment-Page	/ratenkauf/content/intern/einstieg.jsf?vorgangskennung=
Aktuelle Version Schnittstelle	2
Base-URL	/ratenkauf-ws/rest/v2/

In allen Anfragen an das System Ratenkauf wird die Shop-spezifische Webshop-Kennung mitgeliefert. Der Zugriff erfolgt ausschließlich über HTTPS. Für die Authentifizierung bei Zugriffen auf die Vorgangssteuerung ist zudem die Angabe des Credentials des Webshops (Webshop-ID und Token) nötig. Die Credentials zwischen Produktiv- und Testsystem unterscheiden sich in der jeweiligen Webshop-ID. Die Webshop-ID des Produktivsystems beginnt immer mit 1.de, während die Webshop-ID des Testsystems mit 2.de beginnt.

Für die Integration in ein Testsystem des Händlers zur Entwicklung und Abnahme einer Ratenkauf-Integration werden separate Credentials verwendet. Bei Zugriff auf den Ratenkauf mit einer Test-/Schulungskennung werden einige Prüfungen der Kreditentscheidung nur gegen Testdaten und/oder dedizierte Testsysteme ausgeführt. Zum Test von Fehlersituationen (alle Adressangaben und Bankverbindungen werden validiert) empfiehlt es sich die Integration auch mit ungültigen Angaben zu testen. Eine negative Ratenkaufentscheidung kann z.B. über ein geringes Einkommen (<500 €) provoziert werden.

Das Ratenkauf-System selbst ist identisch und verhält sich im Test analog dem Zugriff mit produktiven Kennungen. Mit Testkennungen abgeschlossene und bestätigte Ratenkäufe werden ignoriert und nicht weiterbearbeitet.

Anbindung und Integration

Neben dieser Dokumentation stehen Ihnen eine generierte Schnittstellendokumentation und andere Dokumente zur Verfügung: https://www.easycredit-ratenkauf.de/system/eigenintegration/

Ratenkauf-Logos zur Bewerbung in ihrem Shop finden Sie unter https://www.easycredit-ratenkauf.de/service-integration/marketingmaterial-schulung/logos-und-werbebanner-fur-den-onlineshop/

Fachlich/rechtliche Texte erhalten Sie unter: https://www.easycredit-ratenkauf.de/service-integration/marketingmaterial-schulung/textvorlagen-produktinformationen/

Da das Ratenkaufsystem selbst (ratenkauf.easycredit.de) für Test und Produktion identisch ist, sind bei der Integrationsvariante „Payment-Page“

• die Webshop-ID
• der Token des Webshops und
• die Base-URL der REST-Endpoints (mit der verwendeten Version der API)

die einzigen umgebungsabhängigen Parameter. Diese sollten in der Ratenkaufanbindung eines Webshops entsprechend konfigurierbar hinterlegt werden, damit auch dort – ohne die Implementie-rung anpassen zu müssen – zentral und gesichert zwischen Test- und Produktivsystem umgeschaltet werden kann.

Die Webshop-ID erhalten Sie von unserem IT-Ansprechpartner. Den Token bzw. das API-Kennwort des Webshops können Sie selbst verwalten. Sie benötigen dazu Zugang zur Anwendung Shopadministration, in der Sie einen initialen Token setzen und bei Bedarf dieses auch jederzeit ändern können. Die Berechtigungen dafür werden von uns verwaltet. Bitte teilen Sie uns mit, falls Sie dazu noch keinen Zugang haben.

Während die hier vorliegende Dokumentation den fachlichen Prozess sowie alle Schritte der Integration betrachtet, beschränkt sich die generierte Dokumentation auf eine rein technische Beschreibung der Schnittstellen des Systems. Ausgehend von den REST-Ressourcen kann man sich dort alle Request-/Response-Objekte (Elements) mit JSON-Beispiel ansehen. Hier empfiehlt es sich auch die Type-Beschreibungen dieser Elemente anzusehen , da nur diese die zu den Feldern relevanten Beschreibungen enthalten. Eine fachlichere Beschreibung der Felder findet sich auch in Abschnitt 0 im Anhang; für die Integration per Payment-Page sind dort vor allem die Felder mit einer möglichen Vorbelegung durch den Händler interessant (s. Spalte „Vorbelegung“).
Wenngleich auch im Kapitel 2 – insbesondere in den Anwendungsbeispielen – der Aufruf aller relevanten Ratenkauf-Services dokumentiert ist, so ist im Zweifelsfall die eigentliche Schnittstellendo-kumentation maßgebend.

Zugang zum Demoshop

Die Anbindung der Payment-Page kann man sich auch im Demoshop der TeamBank anschauen. Dieser ist über die folgende URL erreichbar:

https://easycredit-demo.docker.netzkollektiv.com/

Beschreibung der Integration der Payment-Page

Im vorherigen Abschnitt wurde der fachliche Prozess des Bestellvorgangs des Ratenkaufs mit Blick auf eine Payment-Page Integration vorgestellt. Im folgenden Kapitel wird gezeigt, wie eine solche Integration technisch realisiert werden kann, und welche Service-Aufrufe an den einzelnen Prozessschritten erforderlich sind.
In den Aufrufbeispielen werden konkrete Versionen der REST-Schnittstellen aufgerufen (z.B. v2) und es sind exemplarisch Shopkennungen enthalten. Im Zweifelsfalle gelten die im Abschnitt Umgebung genannten Parameter des Ratenkauf-Systems und es sind die zugeteilten Test- oder Produktiv-kennungen für Webshop-ID mit den selbstgewählten Token zu verwenden.

Einbindung des Ratenkaufbeispielrechners

Beschreibung

Die Einbindung der Ratenkaufbeispielrechner(Modellrechnung) ist optional. Sinnvollerweise kann die Beispielrechnung auf Produkt-Detailseiten oder im Warenkorb eingebunden werden, um den Ratenkauf zu bewerben. Es werden alle Ratenpläne für alle möglichen Laufzeiten und ein repräsentatives Beispiel zurückgegeben (letzteres wird in der Regel nicht benötigt). Für die Anzeige einer Ratenzahlung im Shop sollte der Ratenplan mit der günstigsten Rate, d.h. mit der längsten Laufzeit gewählt werden, und hieraus die monatliche Rate angezeigt werden.

Ein Aufruf der Modellrechnung ist ohne Bestellvorgang möglich und beliebig wiederholbar (z.B. nach Aktualisierung des Warenkorbs).

Abruf über Modellrechnung Ressource (siehe auch generierte API Beschreibung):

GET /v2/modellrechnung/durchfuehren

Anwendungsbeispiel: Modellrechnung durchführen

Header:

GET https://ratenkauf.easycredit.de/ratenkauf-ws/rest/v2/modellrechnung/durchfuehren?webshopId=2.de.9999.9999&finanzierungsbetrag=432.95 HTTP/1.1

JSON-Response:

{
  "wsMessages": {"messages": {}}, //  Info-, Warn- und Fehlermeldungen
  "uuid": "9c5a7fb4-f7a6-4ff8-b826-f0488d2b80fe",
  "ergebnis": [
    {                               ///Ratenplan
      "gesamtsumme": "440.91",
      "zinsen": {
        "effektivzins": "6.49",
        "nominalzins": "6.30",
        "anfallendeZinsen": "7.96"
      },
      "zahlungsplan": {
        "anzahlRaten": 6,
        "terminErsteRate": 1430491381956,
        "terminLetzteRate": 1446392581956,
        "betragRate": "74.00",
        "betragLetzteRate": "70.91"
      }
    },
………
    {                               ///Ratenplan
      "gesamtsumme": "458.21",
      "zinsen": {
        "effektivzins": "6.49",
        "nominalzins": "6.31",
        "anfallendeZinsen": "25.26"
      },
      "zahlungsplan": {
        "anzahlRaten": 21,
        "terminErsteRate": 1430491381956,
        "terminLetzteRate": 1485963781956,
        "betragRate": "22.00",
        "betragLetzteRate": "18.21"
      }
    }
  ],
  "repraesentativesBeispiel": "Repräsentatives Beispiel: Sollzinssatz <span class=\"nobr\">6,30 % p.a.</span> fest für die gesamte Laufzeit, effektiver Jahreszins <span class=\"nobr\">6,49 %</span>, Bestellwert <span class=\"nobr\">500,00 EUR</span>, Vertragslaufzeit <span class=\"nobr\">12 Monate</span>, Gesamtbetrag <span class=\"nobr\">516,93 EUR</span>, monatliche Rate <span class=\"nobr\">44,00 EUR</span>, letzte Rate <span class=\"nobr\">32,93 EUR.</span>" // Repräsentatives Beispiel
}

Anwendungsbeispiel: Guenstigster Ratenplan

Der günstigste Ratenplan kann ebenfalls über die Modellrechnungsressource abgefragt werden.

Header:

GET https://ratenkauf.easycredit.de/ratenkauf-ws/rest/v2/modellrechnung/guenstigsterRatenplan?finanzierungsbetrag=432.95&webshopId=2.de.9999.9999  HTTP/1.1

JSON-Response:

{
   "wsMessages": {…},
   "uuid": "…",
   "anzahlRaten": 24,
   "betragRate": 20,
   "gesamtsumme": 471.49
}

Initialisierung eines Vorgangs und Weiterleitung zur Payment-Page

Beschreibung

Die Initialisierung und Weiterleitung ist aus Kundensicht eine „Aktion“, die durchgeführt wird, nachdem der Kunde an der Kasse die Bezahloption „Ratenkauf“ gewählt, der Einverständniserklärung zur Übermittlung seiner Daten an die TeamBank per „Check-Box“ zugestimmt und auf „Weiter“ geklickt hat.

Erzeugung/Initialisierung eines neuen Bestellvorganges über den Web Service /vorgang (siehe auch API Beschreibung)

POST /v2/vorgang

Beim Aufruf müssen – wie bei allen administrativen Zugriffen auf die VorgangResource – die Credentials des Webshops im Request-Header (HttpHeaders) unter den Keys tbk-rk-shop und tbk-rk-token hinterlegt sein. Bei der Initialisierung werden dem Ratenkauf-System die nötigen Informationen vom Webshop übergeben (Kundendaten, Rechnungsadresse, technische Daten wie Rücksprung URLs bei Erfolg/Ablehnung usw.).

Wichtig

Auch wenn bei der Initialisierung viele Felder optional sind, so sind die Angaben zum Kunden, die risikorelevanten Angaben und die Warenkorbpositionen so vollständig wie möglich dem Ratenkauf zu übergeben! Dazu gehören die Attribute kundeSeit, bestellungErfolgtUeberLogin, anzahlBestellungen und logistikDienstleister aus der Gruppe risikorelevanteAngaben. Zusätzlich müssen zu jeder Positionen im Warenkorb die Attribute preis, menge und produktbezeichnung in der Gruppe warenkorbinfos hinzugefügt werden.
Sollte ein Teil der geforderten Informationen nicht geliefert werden können, sprechen Sie bitte mit Ihrem IT-Ansprechpartner!

Das Ratenkauf-System liefert als Antwort eine technische und eine fachliche Vorgangsnummer. Die technische Vorgangsnummer wird nur in der Kommunikation zwischen Webshop und Ratenkauf-System verwendet und nicht weiter kommuniziert. In der Kommunikation mit dem Kunden wird die fachliche Vorgangsnummer (6-stellig, alpha-numerisch, z.B. TXQ7FG) verwendet.

Optional kann der Webshop bei der Initialisierung eine eigene fachliche Shop-Vorgangsnummer über das Feld VorgangskennungShop (z.B. Bestellnummer aus dem Webshop). Diese wird zusätzlich mit dem Vorgang verknüpft und kann in der Kommunikation zwischen Händler und TeamBank verwendet werden (z.B. im Händlerinterface). Alternativ kann das aber auch später bei der Bestätigung erfolgen.

Wichtig: Ein Ratenkauf-Vorgang verfällt 30 Minuten nach der letzten Aktualisierung durch den Kunden. Sofern der Webshop eine eigene Session hat, muss diese über die Verweildauer des Kunden auf der Payment-Page erhalten bleiben (auch hier werden mind. 30 Minuten empfohlen.)

Bei erfolgreicher Initialisierung muss die Weiterleitung unter Angabe der technischen Vorgangskennung auf die unter 1.2 genannte URL erfolgen:

https://ratenkauf.easycredit.de/ratenkauf/content/intern/einstieg.jsf?vorgangskennung=<tbvorgangskennung>

Bedingungen für die Bezahlart easyCredit-Ratenkauf:

• Warenkorbwert muss zwischen 200 EUR und 10.000 EUR liegen
• Lieferanschrift muss eine deutsche Adresse sein
• Rechnungsanschrift muss gleich der Lieferanschrift sein
• Der Kunde muss der Übermittlung seiner Daten an die TeamBank zustimmen, bevor der Vorgang initialisiert wird. Die Zustimmung darf nicht vorausgewählt sein.

Kann einem Kunden auf Grund der Verletzung einer dieser Bedingungen kein Ratenkauf angeboten werden, so sollte der Ratenkauf deaktiviert dargestellt werden mit einem entsprechenden Vermerk, warum der Ratenkauf für ihn nicht wählbar ist (gegen welche Voraussetzungen verstoßen wird). So hat er evtl. noch die Chance, den Mangel zu beheben (die Lieferanschrift zu ändern oder einen weiteren Artikel in den Warenkorb zu legen).

Einbindung in den Checkout

• Zur Einbindung stellen wir Ihnen unser Logo in verschiedenen Größen und Formaten zur Verfügung.
• Außerdem stellen wir Ihnen Beispieltexte für FAQs und zur Ergänzung Ihrer AGBs zur Verfügung, die Sie integrieren können.
• Zusätzlich benötigen Sie eine explizite Erlaubnis des Kunden für die Übermittlung und Rückübermittlung seiner Daten. Diese sollte nicht vorausgewählt sein. Die Zustimmungstexte werden über einen Webservice bereitgestellt.

Anwendungsbeispiel: Zustimmungstexte laden

Nachdem der Kunde die Zahlungsart easyCredit-Ratenkauf gewählt hat, muss der Kunde der Übermittlung seiner Daten an die TeamBank zustimmen. Die Zustimmung muss erfolgen bevor der Vorgang initialisiert wird und der Kunde auf die Payment Page weitergeleitet wird.

Die Zustimmungstexte können über die Ressource /Texte dynamisch geladen und eingebunden werden. Dadurch wird sichergestellt, dass rechtlich relevante Änderungen der Zustimmungstexte direkt übernommen werden und keine manuellen Anpassungen im Webshop notwendig sind.

Header:

GET https://ratenkauf.easycredit.de/ratenkauf-ws/rest/v2/texte/zustimmung/${webshopkennung} HTTP/1.1

JSON-Response:

{
    "wsMessages": "…",
    "uuid": "…",
    "zustimmungDatenuebertragungPaymentPage" : "…",
    "zustimmungDatenuebertragungServiceIntegration": "…",
    "einwilligungsErklaerungServiceIntegration": "…",
    "einwilligungsErklaerungPos": "…",
    "zustimmungZurHandlungInEigenemNamen": "…",
    "zustimmungEmailWerbung": "…"
}

Anwendungsbeispiel: Initialisierung

Header:

POST https://ratenkauf.easycredit.de/ratenkauf-ws/rest/v2/vorgang HTTP/1.1
Content-Type: application/json;charset=UTF-8
tbk-rk-shop: {Ihre-WebshopID}
tbk-rk-token: {Ihr-API-Kennwort}
Host: ratenkauf.easycredit.de

Body:

{
  "integrationsart": "PAYMENT_PAGE",
  "shopKennung": "2.de.9999.9999",
  "bestellwert": 500.99,
  "laufzeit": 12,                   // optional
  "personendaten": {
    "anrede": "HERR",               // ENUM [HERR, FRAU, DIVERS, OHNE]
    "vorname": "Max",
    "nachname": "Mustermann",
    "geburtsdatum": "1988-02-01"    // Ein Datum kann als UNIX-Zeitstempel oder im Format „JJJJ-MM-TT“ übergeben werden

  },
  "rechnungsadresse": {
    "strasseHausNr": "Beuthener Str. 25",
    "adresszusatz": "",
    "plz": "90471",
    "ort": "Nürnberg",
    "land": "DE"
  },
  "lieferadresse": {
    "vorname": "Max",
    "nachname": "Mustermann",
    "strasseHausNr": "Beuthener Str. 25",
    "adresszusatz": "",
    "plz": "90471",
    "ort": "Nürnberg",
    "land": "DE",
    "packstation": false
  },
  "kontakt": {
    "email": "max.mustermann@teambank.de" // Gleiche Mailadresse wie in Shopbestellung
  },
  "risikorelevanteAngaben": {
    "bestellungErfolgtUeberLogin": true,
    "kundeSeit": "2016-01-01", // Muss nicht angeben werden, wenn Kunde keinen Login für Shop hat
    "anzahlBestellungen": "3", // Muss nicht angeben werden, wenn  Kunde keinen Login für Shop hat.
    "kundenstatus": "NEUKUNDE", // ENUM [NEUKUNDE, BESTANDSKUNDE, PREMIUMKUNDE]
    "anzahlProdukteImWarenkorb": "2",
    "logistikDienstleister": "Hermes" // Kann Freitext sein
  },
  "vorgangskennungShop": "IhreEigeneOrdernummer123", // Vorgangskennung des Händlers/Webshops
  "ruecksprungadressen": {
    "urlErfolg": "http://www.easycredit-ratenkauf.de/erfolg",
    "urlAbbruch": "http://www.easycredit-ratenkauf.de/abbruch",
    "urlAblehnung": "http://www.easycredit-ratenkauf.de/ablehnung"
  },
  "warenkorbinfos": [
    {
      "produktbezeichnung": "Waschmaschine",
      "menge": "1",
      "preis": "590.99"
    }
  ],
  "technischeShopparameter": {
    "shopSystemHersteller": "MamutShop4000",
    "shopSystemModulversion": "4.0.1"
  }
}

JSON-Response:

{
    "wsMessages": {
        "messages": []
    },
    "uuid": "997d9941-24aa-4171-b096-bc88978ebd16",
    "tbVorgangskennung": "a3c81dc9.1503171643141071763130915444665", // technische Vorgangskennung
    "deviceIdentToken": "77876cc9-cf7d-4c29-b030-c2c88630d410",
    "fachlicheVorgangskennung": "TKXG7Z"
}

Rückführung zum Webshop

Beschreibung

Die Rückführung in den Shop erfolgt – je nach Verlauf der Ratenkauf-Bestellung (Erfolg, Ablehnung oder Abbruch) – auf die bei der Initialisierung des Vorgangs angegebene URLs.

Die angegebenen URLs können entsprechend den Anforderungen des Webshops gestaltet und z.B. zusätzliche Session-bezogene Parameter des Webshops enthalten. Die Unterscheidung der drei Rückführungsmöglichkeiten soll die Integration beim Händler erleichtern.

Abfrage der Ratenkauf-Entscheidung

Beschreibung

Die verbindliche Ratenkauf-Entscheidung muss über eine separate Abfrage des Entscheidungsergebnisses durch den Webshop validiert werden.

Allein die Weiterleitung auf die entsprechende Webshop-URL für „Erfolg“ reicht nicht aus!

Abruf über VorgangResource (siehe auch API Beschreibung)

GET /v2/vorgang/{vorgangskennung}/entscheidung

Wichtig: Nur bei Entscheidung „GRUEN“ ist ein Ratenkauf möglich, und nur in diesem Falle darf der Prozess entsprechend mit Ratenkauf fortgesetzt werden (s. Abschnitt 1.1)

Anwendungsbeispiel

Header:

GET https://ratenkauf.easycredit.de/ratenkauf-ws/rest/v2/vorgang/{vorgangskennung}/entscheidung HTTP/1.1
Accept-Encoding: gzip,deflate
tbk-rk-shop: {Ihre-WebshopID}
tbk-rk-token: {Ihr-API-Kennwort}
Host: ratenkauf.easycredit.de

JSON-Response:

{
   "wsMessages": {"messages": []},
   "uuid": null,
   "timestamp": 0,
   "entscheidung":    {
      "entscheidungsergebnis": "GRUEN",
      "textbaustein": null,
      "laufzeitgrenzen":       {
         "minimaleLaufzeit": 6,
         "maximaleLaufzeit": 60
      }
   }
}

Bestätigung des Vorgangs

• Machen Sie Ihrem Kunden transparent, dass er mit easyCredit-Ratenkauf zahlt und welche Ratenanzahl er gewählt hat.

• Stellen Sie sicher, dass alle mit der Zahlungsart verbundenen Kosten (inkl. Zinsen) abgebildet werden.

• Stellen Sie sicher, dass die Bestätigung von unserer Schnitt-stelle mit einer erfolgreichen Response quittiert wurde.

Bei positiv (GRUEN) entschiedenem Ratenkauf sind dem Kunden alle mit dem Ratenkauf verbundenen Informationen und Zinsen / Kosten auf der abschließenden Bestellbestätigung im Shop zu präsentieren. Hierzu gehören

• die vom Kunden gewählte Laufzeit (Anzahl der Raten)
• die Gesamtsumme der Bestellung mit den ausgewiesenen Zinsen für die Ratenzahlung.

Mögliche Darstellung der aus dem Ratenkauf entstehenden Kosten

Sofern der Kunde die Bestellung unter Inanspruchnahme des Ratenkaufs abschließend tätigt, ist dies vom Webshop beim Ratenkauf-System für diesen Vorgang zu bestätigen.

Wichtig: Die Ratenkaufentscheidung ist vorgangsgebunden und zählt nur für den durch das System Ratenkauf geprüften Vorgang (Stichwort „echtes Factoring“). D.h. der Bestellvorgang muss im Anschluss an die Prüfung ohne weitere Modifikation von Warenkorb, Angaben zur Person oder Adressen abgeschlossen werden. Sollte der Kunde dennoch irgendwelche dieser Daten ändern, ist die Ratenkaufentscheidung hinfällig, und es muss ein neuer Vorgang initialisiert und durchlaufen werden!

Finanzierungsdaten abrufen

Dem Kunden muss klar angezeigt werden, dass er als Zahlungsart Ratenkauf gewählt hat und die Höhe der Zinsen und die daraus resultierende Gesamtsumme.

Header:

GET https://ratenkauf.easycredit.de/ratenkauf-ws/rest/v2/vorgang/{vorgangskennung}/finanzierung HTTP/1.1
Accept-Encoding: gzip,deflate
tbk-rk-shop: {Ihre-WebshopID}
tbk-rk-token: {Ihr-API-Kennwort}
Host: ratenkauf.easycredit.de

JSON-Response:

{
   "wsMessages": {…},
   "uuid": "…",
   "ratenplan":    {
      "gesamtsumme": "248.93",
      "zinsen":       {
         "effektivzins": "8.80",
         "nominalzins": "8.45",
         "anfallendeZinsen": "10.93"
      },
      "zahlungsplan":       {
         "anzahlRaten": 12,
         "terminErsteRate": 1501538400000,
         "terminLetzteRate": 1530396000000,
         "betragRate": "21.00",
         "betragLetzteRate": "17.93"
      }
   },
   "laufzeitgrenzen":    {
      "minimaleLaufzeit": 6,
      "maximaleLaufzeit": 12
   },
   "finanzierung":    {
      "bestellwert": "238.00",
      "laufzeit": 12
   },
   "tilgungsplanText": "Tilgungsplan: Laufzeit 12 Monate, monatliche Rate 21,00 EUR (erste Rate: 19,38 EUR Tilgung, 1,62 EUR Zinsen), Schlussrate 17,93 EUR (17,73 EUR Tilgung, 0,20 EUR Zinsen). Alternativer Tilgungsplan: Laufzeit 9 Monate, monatliche Rate 28,00 EUR (erste Rate: 26,38 EUR Tilgung, 1,62 EUR Zinsen), Schlussrate 22,31 EUR (22,09 EUR Tilgung, 0,22 EUR Zinsen)."
}

Im Attribut ratenplan finden Sie die Gesamtsumme aus Bestellwert und Zinsen (gesamtsumme) und die Summe der Zinsen (anfallendeZinsen).

Bestellung bestätigen

Nachdem der Kunde die Bestellung im Webshop bestätigt hat, muss die Bestätigung auch an die TeamBank übertragen werden.

Wichtig: Bevor der Shop die Bestellung abschließt, muss sichergestellt sein, dass der Bestaetigen-Request von unserem Server mit einer erfolgreichen Response quittiert wurde. Ohne eine erfolgreiche Response darf keine Bestellung erfolgen. Das reine Senden des untenstehenden Requests ist nicht ausreichend!

Die Bestätigung der Bestellung erfolgt über:

Header:

POST https://ratenkauf.easycredit.de/ratenkauf-ws/rest/v2/vorgang/{vorgangskennung}/bestaetigen HTTP/1.1
Accept-Encoding: gzip,deflate
tbk-rk-shop: {Ihre-WebshopID}
tbk-rk-token: {Ihr-API-Kennwort}
Host: ratenkauf.easycredit.de

Body:

{
    "shopVorgangskennung": "IhreEigeneOrderNr" // optional
}

JSON-Response:

{
   "wsMessages": {"messages": [   {
      "key": "BestellungBestaetigenServiceActivity.Infos.ERFOLGREICH",
      "originalKey": null,
      "field": null,
      "severity": "INFO",
      "renderedMessage": "Die Bestellung c291752f.042017483541Vvg71ov9sMQIBbUsO1hpNW / V3DGYF wurde erfolgreich bestätigt.",
      "params":       [
         "c291752f.042017483541Vvg71ov9sMQIBbUsO1hpNW",
         "V3DGYF"
      ],
      "uuid": null
   }]},
   "uuid": null,
   "timestamp": 0
}

Anhang

Begriffsdefinitionen

Device Ident:

Dienst, der gerätespezifische Informationen erhebt und verwendet, um potentielle Betrugsfälle zu erkennen. Die erhobenen Daten sind anonym in dem Sinne, dass aus diesen allein kein Rückschluss auf die Person möglich ist. Das verwendete Gerät wird wiedererkannt und erhält aufgrund seines Aktivitäten-Profils über ein Regelwerk, das ein Kunde (z.B. die TeamBank) bearbeiten und festlegen kann, ein Scoring.

Entscheidungsergebnis:

Ergebnis der Kreditentscheidung der TeamBank, ob diese einem Käufer eine Finanzierung gewährt (Grün) oder nicht (Rot). Eine Positiventscheidung mit zwingender Anpassung der Laufzeit ("Grün mit Einschränkung") stellt kein eigenständiges Entscheidungsergebnis dar.

Bestellwert / Finanzierungsbetrag:

Der monetäre Betrag für die Ware(n) eines Händlers, die ein Käufer über Produkt Ratenkauf finanzieren will.

Finanzierungszusage:

Eine Finanzierungszusage der TeamBank an den Händler bedeutet, dass die TeamBank sich bereit erklärt, den Ratenkauf zu den angegebenen Konditionen bereitzustellen. Die Zusage gilt vorbehaltlich einer im Webshop eines Händlers erfolgenden Bestellung durch den Käufer und stellt bis zu diesem Zeitpunkt auch keine Kreditzusage dar.

Laufzeit:

Zeit in Monaten, innerhalb derer ein Käufer den Bestellwert zzgl. Zinsen an die TeamBank zurückzahlen muss.

Ratenkauf-Vorgänge:

Die Vorgangsdaten eines Ratenkaufs umfassen alle relevanten Angaben zur Geschäftsabwicklung des Ratenkaufs, darunter z.B. Vorgangsstatus, Kundendaten, Händler-ID.

Ratenplan:

Informationsgrundlage der Finanzierung für den Käufer. Enthält Ratenhöhe, Laufzeit, Gesamtsumme, Effektivzins und Termine für erste und letzte Rate.

Shop-Kennung
Die TeamBank liefert ein eindeutiges Identifikationsmerkmal, welches auch als eindeutige Webshop-Kennung dient und manuell an den Händler kommuniziert wird.

Vorgangskennung TeamBank (TB-VK):

Eine global eindeutige Kennung, im Schnittstellenmodell tbVorgangskennung in den allgemeinen Vorgangsdaten, mittels derer die Vorgangsdaten eines bestimmten Käufers identifiziert werden können. Die Navigation des Käufers aus dem Webshop zur Payment-Page oder der Zugriff vom Webshop auf den Vorgang erfolgt lediglich mit dieser Vorgangskennung, aus der kein Rückschluss auf die Daten möglich ist. Die Payment-Page verwendet die Vorgangskennung, um die zuvor initialisierten Vorgangsdaten zu laden. Da zu diesem Zeitpunkt noch keine Einwilligung des Käufers zur Datenspeicherung vorliegt, werden Daten initialisierter, jedoch nicht weiter bearbeiteter Vorgänge nach einer angemessen kurzen Zeitspanne (derzeit 30 Minuten) vollständig gelöscht.

Nach erfolgter oder abgelaufener Bestellung wird die TB-VK nicht weiterverwendet. Ein Ratenkauf-Vorgang kann im Bestand auch nicht mehr über die TB-VK identifiziert werden.

Vorgangskennung Shop (SHOP-VK):

Eine vom Händler gegenüber dem Kunden oder intern in der Buchhaltung verwendete Referenz zur Bestellung im Shop. Die SHOP-VK wird nicht zur technischen Identifikation eines Vorgangs verwendet, sondern lediglich zur menschlichen Nachvollziehbarkeit z.B. in der Händler-Abrechnung. Abgeschlossene Ratenkaufbestellungen können im Händlerinterface auch über die SHOP-VK gesucht werden.

Fachliche Vorgangsnummer:

Eine menschenlesbare, eindeutige, sechsstellige ID, mittels derer die Vorgangsdaten einer bestimmten Bestellung identifiziert werden können. Die fachliche Vorgangsnummer ist die offizielle Referenz zum Ratenkauf und wird in den Vorvertraglichen Informationen und in den Folgeprozessen der Kreditverarbeitung (nach der Bestellung) als primäres Identifikationsmerkmal des Ratenkauf-Vorgangs in der menschlichen und technischen Kommunikation mit Händler und Kunden verwendet.