Integration Guide Payment API v3

Stand: 28.04.2025

Mithilfe dieser Anleitung können Sie in wenigen Schritten die Zahlarten easyCredit-Ratenkauf & easyCredit-Rechnung in Ihren Online-Shop integrieren. Neben allgemeinen Informationen zu den Produkten und zum Prozess enthält das Dokument ebenfalls Anweisungen und konkrete Anwendungsbeispiele für die Integration selbst.

Changelog

Datum Änderungen
28.04.25
  • Ergänzung easyCredit-Rechnung
02.03.23
  • Sequenzdiagramm hinzugefügt
16.02.23
  • Ergänzung Kapitel Voraussetzung für einen Ratenkauf
  • Erweiterung Kapitel Initialisierung
13.10.22
  • Ergänzung Callback-URL bei Autorisierung
  • Änderung Wording Schulungsumgebung -> Test-Ansicht
15.09.22
  • Wechsel der Marke auf easyCredit-Ratenkauf
21.06.22
  • Checkbox bei Datenübermittlungshinweis nicht mehr erforderlich
  • Aktualisierung d. Links zur Weiterleitung auf die Payment Page
  • Ergänzung der Ratenkauf Webcomponents
  • Changelog ergänzt

Allgemeine Informationen zum easyCredit-Ratenkauf

Mittels des easyCredit-Ratenkaufs 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 die Zahlungsforderung gegenüber dem Kunden - inklusive des Risikos seiner Zahlungsunfähigkeit.

Produktdetails:

  • Einkaufsbeträge: 200 Euro - 10.000 Euro
  • Laufzeiten 2 bis 60 Monate frei wählbar
  • Nutzbar in deutschen Online-Shops

Vorteile für den Händler:

  • Einfache und schnelle Integration
  • Sichere Zahlungsart, kein Risiko
  • Faire Konditionen und hohe Flexibilität für die Endkunden

Vorteile für den Kunden:

  • Sofort – Schnell und bequem ohne Gehaltsnachweis und ohne PostIdent-Verfahren.
  • Fair – Klare Darstellung des Teilzahlungspreises ohne versteckte Kosten oder Gebühren.
  • Sicher - Maximaler Schutz der Zahlungsdaten hat höchste Priorität.
  • Flexibel – Vorzeitige Rückzahlung und Zahlpausen des Kunden möglich.

Allgemeine Informationen zu easyCredit-Rechnung

Seit 2025 bieten wir Händlern unser neues Produkt easyCredit-Rechnung an. Mit easyCredit-Rechnung stellen wir Ihnen und Ihren Kunden eine schnelle und bequeme Lösung für eine der beliebtesten Zahlarten im Onlinehandel zur Verfügung.

Produktdetails

Name Wert
Vertriebskanäle E-Commerce
Einkaufsbeträge 50 – 5.000 Euro
Produktart Waren und produktbezogene Dienstleistungen
Fälligkeit Frühestens 30 Tage nach Lieferung
Kosten Ohne zusätzliche Kosten für den Endkunden
Zielgruppe Kunden ab 18 Jahren, wohnhaft in Deutschland
Widerrufsfrist Für den Widerruf der Finanzierung: 2 Wochen ab Bestellabschluss, schriftlich
Rückzahlung Eine vorzeitige Rückzahlung des Rechnungsbetrags ist per Überweisung gebührenfrei möglich

Was ist neu in der Payment-API v3?

Unsere neue Payment-API V3 haben wir weiter stark hinsichtlich Integration vereinfacht und bringt die folgenden neuen Funktionen:

  1. Änderung der Sprache / OpenAPI-Standard

    Unsere API und die dazugehörige Spezifikation sind ab jetzt standardmäßig in Englisch und im OpenAPI-Standard verfasst.

  2. Workflow und Statusmodell

    Das Statusmodell der API wurde in der neuen Version stark vereinfacht und an den übrigen Zahlungsverkehr angeglichen.

    Status Erklärung
    open Vorgang wurde erfolgreich initialisiert
    preAuthorized Entscheidung durchgeführt, der Kunde kann den Warenkorb mit Ratenkauf finanzieren o. per Rechnung kaufen
    declined Entscheidung durchgeführt, dem Kunden kann leider keine Zahlung mit Ratenkauf o. Rechnung angeboten werden. Somit muss eine andere Zahlungsmethode gewählt werden.
    authorized Der Abschluss der Bestellung durch den Kunden wurde bei uns eingemeldet und der Vorgang wurde autorisiert
    expired Der Vorgang kann nicht weiterbearbeitet werden (z.B: abgelaufen). Es muss ein neuer Vorgang initialisiert werden.

    Die Bezeichnungen der Endpoints orientieren sich ebenfalls am neuen Statusmodell. So wird ein Vorgang mittels POST ./transaction initialisiert und mittels POST ./transaction/{id}/authorization wird eine Authorization angelegt.

  3. Authentifizierung mittels Basic-Auth

    Die Authentifizierung erfolgt bei der API v3 über das BASIC-Auth Verfahren, nicht mehr über custom Header. Dadurch wird die Integration stark vereinfacht und es werden keine weiteren Drittanbieter-Module oder -Bibliotheken benötigt. Gleichzeitig wurde durch die Verdoppelung der Zeichenlänge und der Generierung der API-Kennwörter die Sicherheit der Endpoints weiter verstärkt.

    [Details]

  4. 2-Phasen-Bestätigung

    Um zuverlässig sicherzustellen, dass die Auftragsbestätigung einer Bestellung mit unseren Zahlarten erst dann erfolgt, wenn der Vorgang erfolgreich autorisiert wurde, wurde die 2-Phasen-Bestätigung eingeführt.

    Hierzu wird in der ersten Phase eine Authorization angelegt. Diese wird mit dem HTTP-Status 202 Accepted quittiert. Dies bedeutet, dass wir die Anfrage angenommen haben, aber noch in der Verbreitung sind. Ist das erfolgt, kann dem Kunden die Bestätigungsseite über die Bestellung angezeigt werden. Die E-Mail zur Bestell-/Auftragsbestätigung sollte erst versendet werden, wenn der Status des zugehörigen Ratenkaufs auf Authorized steht. Der Status kann mittels GET ./transaction/{id} abgefragt werden.

    [Details]

  5. Body-Signatur

    Ein weiteres Merkmal zur Erhöhung der Sicherheit ist die neue Body-Signatur. Dadurch kann jeder Request mithilfe eines Geheimschlüssels signiert werden. Der Geheimschlüssel kann, wie das API-Kennwort, im Partner-Portal erstellt werden. Jede Response der API wird dann ebenfalls mit dem Geheimschlüssel signiert. So ist sichergestellt, dass Request und Response nicht durch eine Man-In-Middle-Attacke verändert wurden.

    [Details]

Überblick fachlicher Ablauf

Aktion Datenübermittlung > Initialisierung > Redirect Payment Page > Entscheidungsergebnis prüfen > Vorgang bestätigen > Bestätigung prüfen
Status - open - preauthorized / declined preauthorized authorized
Endpoint GET ./webshop POST ./transaction - GET ./transaction/{id} POST ./transaction/{id}/authorization GET ./transaction/{id}

Ablauf

1. Datenübermittlungshinweis anzeigen

  • Im Checkout wählt der Kunde entweder die Zahlart easyCredit-Ratenkauf oder easyCredit-Rechnung.
  • Dem Kunden muss vor Initialisierung und Weiterleitung der Datenübermittlungshinweis angezeigt werden. Eine explizite Zustimmung per Checkbox ist nicht mehr erforderlich. Der Text für den Datenübermittlungshinweis kann und sollte dynamisch von der API bezogen werden.

2. Initialisierung

  • Die Initialisierung erzeugt einen neuen Vorgang mit einer neuen, eindeutigen Vorgangskennung, der technicalTransactionId. Dieser Vorgang ist die Grundlage für den Informationsaustausch zwischen Webshop und der TeamBank bzw. der Payment-API.
  • Es wird eine SSL-gesicherte Verbindung für den Austausch zwischen Webshop und API erstellt, um sicherzustellen, dass die Daten nicht manipuliert werden können.
  • Daten, die der Webshop erfasst hat und für den Raten- oder Rechnungskauf relevant sind (E-Mail, Adresse, etc.), werden an die Payment-API übertragen.
  • Zum Schutz gegen Betrug wird ein einmaliger und eindeutiger Token für den Dienst Device Ident erzeugt.

3. Redirect zur Payment Page

  • Der Kunde wird auf die sog. Payment Page weitergeleitet. Die URL setzt sich aus [https://ratenkauf.easycredit.intern/app/payment/{id}/datenerfassen] und der technischen Vorgangskennung zusammen.
  • Auf der Payment Page werden weitere Kundendaten erhoben, die für den Raten- oder Rechnungskauf notwendig sind, aber nicht im Webshop erfasst wurden, inkl. Zustimmungen zu Datenspeicherung, Bonitätsprüfung und SEPA-Lastschriftmandat.
  • Durch einen Klick auf Zahlungswunsch prüfen startet der Kunde die Bonitätsprüfung. Das passiert auf Basis der eingegebenen Daten, aber auch verschiedener Mechanismen zur Identitäts- und Betrugsfallprüfung.
  • Dem Kunden wird das Entscheidungsergebnis inkl. entsprechendem Hinweistext angezeigt.
  • Das Entscheidungsergebnis kann POSITIVE oder NEGATIVE sein, oder aber POSITIVE mit Anpassung der Wunschlaufzeit.
  • Im Falle einer Ablehnung (NEGATIVE) wird dem Käufer die Rückführung in den Checkout-Prozess angeboten.
  • Im Falle einer positiven Entscheidung (POSITIVE) kann der Käufer die Laufzeit im Rahmen der durch die Kreditentscheidung vorgegebenen Grenzen anpassen und anschließend das Finanzierungsangebot annehmen bzw. Zahlungswunsch übernehmen.

4. Rückleitung & Entscheidung abfragen

  • Der Kunde wird nach der Payment Page auf die Return-URL (urlSuccess) zurückgeleitet, die bei der Initialisierung übergeben wurde.
  • Zu diesem Zeitpunkt muss vom Shop das Ergebnis der Entscheidung abgeholt und geprüft werden, um sicherzustellen, dass nicht alleine die Return-URL zur Bestellung ausreicht. Der Vorgang muss sich im Status preauthorized befinden.

Nur Ratenkauf:

  • Auf der Bestellzusammenfassungsseite muss dem Kunden explizit die Höhe der Zinsen als separater Posten angezeigt und in die Gesamtsumme des Warenkorbs eingerechnet werden.

5. Bestätigen / Autorisierung

  • Durch Klick auf "Zahlungspflichtig bestellen" wird die Bestätigung / Autorisierung an die TeamBank übertragen, mit dem zuvor vom Kunden gewählten Ratenplan.
  • Nach der erfolgreichen Autorisierung kann dem Kunden die "Vielen-Dank-Für-Ihre-Bestellung"-Seite angezeigt werden.

6. Finalisierung

  • Um sicherzustellen, dass die Autorisierung erfolgreich an die TeamBank übertragen wurde, muss der Status des Vorgangs zum Schluss ein weiteres Mal geprüft werden.
  • Befindet sich der Vorgang im Status authorized kann die Bestellbestätigungsmail vom Shopsystem an den Kunden verschickt werden.

Sequenzdiagramm

Sequenzdiagramm easyCredit-Vorgang

[Klick zum Vergrößeren]

Rahmendaten der API

Die technische Anbindung der easyCredit-Zahlarten 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.

OpenAPI-Spezifikation

Die Spezifikation der Payment-API erfolgt im OpenAPI-Standard. Dementsprechend können Sie den Client für die Anbindung unserer API automatisch generieren, entsprechend der eingesetzten Plattform (PHP, Java, JS/Node, Python). Weiterführende Informationen hierzu finden Sie: https://github.com/OpenAPITools/openapi-generator oder https://swagger.io/tools/swagger-codegen/

Die Spezifikation steht als Swagger-UI und als JSON-Datei unter den folgenden URLs zur Verfügung.

Payment-API als Swagger-UI in unserem Portal

Payment-API als JSON-File Changelog

Payment-API auf GitHub Changelog

Versionierung

Unsere API ist im Pfad mit der Major-Version versioniert. Wir stellen sicher, dass wir im Rahmen einen Major-Version nur abwärtskompatible Änderungen/Erweiterungen durchführen. Abwärtsinkompatible Änderungen erfolgen nur im Rahmen einer neuen Major-Version mit einer neuen openAPI-Spezifikation. Die Vorgängerversion bleibt jedoch erhalten. Eine Abkündigung einer veralteten Version erfolgt per E-Mail mit einem entsprechend langen Übergangszeitraum.

Grundsätzliches zur Integration

Anleitungen

Neben diesem Integration Guide stehen Ihnen eine generierte Schnittstellendokumentation und andere Dokumente zur Verfügung. Näheres finden Sie dazu im Kapitel Rahmendaten der API.

Während der hier vorliegende Integration Guide den fachlichen Prozess sowie alle Schritte der Integration inkl. Beispiele betrachtet, beschränkt sich die OpenAPI-Dokumentation auf eine rein technische Beschreibung der Schnittstelle, der Endpoints und der Attribute 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.

Wenngleich auch im Kapitel Integration), insbesondere in den Anwendungsbeispielen, der Aufruf aller relevanten Endpoints dokumentiert ist, so ist im Zweifelsfall die eigentliche Schnittstellendokumentation maßgebend.

Zugang zum Demoshop

Die Anbindung der Payment-API via Payment Page können Sie sich auch im Demoshop der TeamBank anschauen. Dieser ist über die folgende URL erreichbar:

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

Demoshop

Logos & Texte

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/

Zugangsdaten

Um den eine oder beide der easyCredit-Zahlarten einsetzen zu können, benötigen Sie als Zugangsdaten eine Webshop-ID und ein API-Kennwort.

Wenn Sie bereits registrierter Händler oder Partner sind, erhalten Sie Ihre Zugangsdaten im Rahmen des normalen Onboarding-Prozesses. Nachdem das Onboarding erfolgt ist, können Sie Ihre Zugangsdaten im Partner Portal in der Shopadministration einsehen und generieren.

Falls Sie bisher nicht registriert sind oder Demo-Daten nutzen wollen, dann wenden Sie sich gerne an ratenkauf@easycredit.de.

Da das System selbst für Test und Produktion identisch ist, sind bei der Integrationsvariante „Payment-Page“

  • die Webshop-ID
  • das API-Kennwort 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.

Mit welchen Zugangsdaten kann ich testen?

Um ein Testbestellungen ohne Bonitätsprüfung etc. durchzuführen haben Sie zwei Möglichkeiten:

  1. Sandbox

    Zu jeder 1.de.-WebshopID, die Sie von uns erhalten, gibt es auch noch eine parallele WebshopID, die mit "2.de." beginnt. Wenn Sie diese nutzen, werden alle Bestellungen, als Testbestellungen erkannt - unabhängig davon, welche Kundendaten benutzt werden. Deshalb sollte diese Option möglichst nicht im Produktiv-Betrieb eingesetzt werden. Die 2.de.-WebshopID eignet sich daher eher für Entwicklungsumgebungen, bei denen oft getestet wird und keine Echt-Bestellungen durchgeführt werden.

    Für die 2.de.-WebshopID muss über den Schalter "Sandbox" unten in der Shopadministration ein separates API-Kennwort generiert werden.

  2. Testmodus

    Auch wenn die 1.de.-WebshopID hinterlegt ist, können Testbestellungen durchgeführt werden. Dazu müssen Sie in der Shopadministration für diese WebshopID den Testmodus aktivieren.

    Ist das der Fall können mit den Kundendaten Ralf Ratenkauf, Beuthener Str. 25, 90471 Nürnberg Testbestellungen angelegt werden. Alle Bestellungen mit anderen Daten laufen nachwievor als echte Bestellungen inkl. Bonitätsprüfung.

    Deshalb eignet sich diese Option besonders für das Testen in der Produktivumgebung, da sie sich auf das restliche Geschäft nicht auswirkt.

    Testmodus

Fachliche Voraussetzungen für Bestellungen

Neben der technischen Ebene gelten für die einzelnen Bestellungen auch inhaltliche Voraussetzungen bzw. Einschränkungen bezüglich der Kunden und Bestelldaten:

  • Finanzierungsbetrag zwischen 200 € - 10.000 € (Ratenkauf) und 50 € - 5.000 € (Rechnung)
  • Wohnsitz in Deutschland
  • Rechnungs- & Lieferadresse müssen identisch sein
  • Unternehmen & Selbstständige ausgeschlossen

Auch wenn die API der TeamBank einige der potentiellen Abweichungen abfangen kann, ist es dennoch wichtig und erforderlich, dass sowohl der Shop, als auch Shopbetreibende die Einhaltung der obenstehenden Kriterien forcieren. Das kann z.B. durch die korrekte Übermittlung der Bestelldaten oder durch Anpassungen am Checkout-Workflow passieren.

Beispiel: In einigen Shops ist es möglich am Ende der Bestellung noch einmal die Lieferadresse zu ändern. Da weder Ratenkauf, noch Rechnung mit abweichenden Adressen genutzt werden darf, darf der Shop entweder die nachträgliche Adressänderung nicht zulassen oder muss beide Adressen auf die neue ändern.

Integration Payment-API

Authentifizierung

Die Authentifizierung an der Payment-API erfolgt, anders als bei den Vorgängerversionen, mittels BASIC Auth. Hierzu wird bei jedem Request im Header das Attribut Authorization erwartet. Der Wert des Attributs setzt sich wie folgt zusammen:

Basic <token>

Der Token berechnet sich aus Webshopkennung (z.B. 2.de.9999.9999) und API-Kennwort. Beides wird mittels : konkateniert und anschließend mittels base64 kodiert.

<token> => base64(1.de.9999.9999:RatenkaufByEasyCredit123!) => MS5kZS45OTk5Ljk5OTk6UmF0ZW5rYXVmQnlFYXN5Q3JlZGl0MTIzIQ==

Der Header sieht dann wie folgt aus:

Authorization: "Basic MS5kZS45OTk5Ljk5OTk6UmF0ZW5rYXVmQnlFYXN5Q3JlZGl0MTIzIQ=="

Weitere allgemeine Details zu BASIC Auth finden sie hier

Integration Check

Um die Korrektheit der Konfiguration und Zugangsdaten im Shopsystem zu prüfen, kann folgender Endpoint aufgerufen werden:

  POST ./webshop/integrationcheck

Mit dem Request Body:

  {
    "message": "easyCredit-Ratenkauf"
  }

Es wird zum einen die Authentifizierung geprüft, zum anderen die Body-Signatur, falls diese für den Webshop aktiviert und konfiguriert wurde. Liefert der Endpoint den HTTP-Status-Code 200 und die übergebene Message im Body zurück, ist die Konfiguration der Zugangsdaten und des Geheimschlüssels korrekt.

Widget anbinden

Um die Kunden auf die easyCredit-Zahlarten aufmerksam zu machen können Sie an verschiedenen Stellen das Widget integrieren. In beiden Fällen werden zusätzliche Informationen zur jeweiligen Zahlart angezeigt, beim Ratenkauf zusätzlich auch noch ein Beispielrechner. Das ist natürlich optional, aber ein entscheidender Baustein für den Erfolg der Zahlarten im Onlineshop. Sinnvoll ist die Platzierung vor allem auf den Produktdetailseiten in der Nähe vom Preis, aber auch auf anderen Seiten wie z.B. der Warenkorbseite kann das Widget eingebunden werden.

Beim Beispielrechner für den Ratenkauf werden alle Ratenpläne für alle möglichen Laufzeiten und ein repräsentatives Beispiel zurückgegeben. Das kann sowohl für einen einzelnen, als auch für mehrere Artikel gleichzeitig angefragt werden, je nachdem wieviele Artikel im Request übergeben werden.

Wir empfehlen bei der Anzeige einer einzelnen Rate immer zuerst die niedrigste Rate anzuzeigen, d.h. den Ratenkauf mit der längsten Laufzeit.

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

Derzeit gibt es zwei Möglichkeiten, wie das Widget / der Ratenrechner technisch integriert werden kann. Einerseits über eine fertige Web Component, die von uns bereitgestellt wird und andererseits händisch über die entsprechenden Endpoints.

Integration via Web Component

Beispiel:

Beispiel

Generelle Anleitung zur Einbindung der Web Components

Beispieldarstellung und Anleitung für das Widget

Integration via Endpoints

(nur relevant für easyCredit-Ratenkauf)

Anwendungsbeispiel:

POST https://ratenkauf.easycredit.de/api/ratenrechner/v3/webshop/2.de.9999.9999/installmentplans

JSON-Request:

{
    "articles": [
        {
            "identifier": "Washing Machine I",
            "price": 599.95
        },
        {
            "identifier": "Washing Machine II",
            "price": 599.95
        }
    ]
}

JSON-Response:

{
    "installmentPlans": [
        {                               ///Ratenplan für Artikel 1
            "example": "Repräsentatives Beispiel: Sollzinssatz <span class=\"nobr\">8,64 % p.a.</span> fest für die gesamte Laufzeit, effektiver Jahreszins <span class=\"nobr\">8,99 %</span>, Bestellwert <span class=\"nobr\">103,00 EUR</span>, Vertragslaufzeit <span class=\"nobr\">6 Monate</span>, Gesamtbetrag <span class=\"nobr\">615,11 EUR</span>, monatliche Rate <span class=\"nobr\">103,00 EUR</span>, letzte Rate <span class=\"nobr\">100,11 EUR.</span> Anbieter: Beispielhändler, Beispielstr. 1, 12345 Beispielstadt\n",
            "articleIdentifier": "Washing Machine I",
            "url": "https://ratenkauf.easycredit.de/widget/app/#/ratenwunsch?bestellwert=599.95&shopKennung=2.de.9999.9999",
            "plans": [
                {
                    "term": 6,
                    "installment": "103.00"
                },
                {
                    "term": 9,
                    "installment": "70.00"
                },
                {
                    "term": 12,
                    "installment": "53.00"
                },
                {
                    "term": 15,
                    "installment": "43.00"
                },
                {
                    "term": 18,
                    "installment": "36.00"
                },
                {
                    "term": 21,
                    "installment": "31.00"
                },
                {
                    "term": 24,
                    "installment": "28.00"
                },
                {
                    "term": 27,
                    "installment": "25.00"
                },
                {
                    "term": 30,
                    "installment": "22.50"
                },
                {
                    "term": 33,
                    "installment": "21.00"
                }
            ]
        },
        {                                       ///Ratenplan für Artikel 2
            "example": "Repräsentatives Beispiel: Sollzinssatz <span class=\"nobr\">8,64 % p.a.</span> fest für die gesamte Laufzeit, effektiver Jahreszins <span class=\"nobr\">8,99 %</span>, Bestellwert <span class=\"nobr\">103,00 EUR</span>, Vertragslaufzeit <span class=\"nobr\">6 Monate</span>, Gesamtbetrag <span class=\"nobr\">615,11 EUR</span>, monatliche Rate <span class=\"nobr\">103,00 EUR</span>, letzte Rate <span class=\"nobr\">100,11 EUR.</span> Anbieter: Anbieter: Beispielhändler, Beispielstr. 1, 12345 Beispielstadt\n",
            "articleIdentifier": "Washing Machine II",
            "url": "https://ratenkauf.easycredit.de/widget/app/#/ratenwunsch?bestellwert=599.95&shopKennung=2.de.9999.9999",
            "plans": [
                {
                    "term": 6,
                    "installment": "103.00"
                },
                {
                    "term": 9,
                    "installment": "70.00"
                },
                {
                    "term": 12,
                    "installment": "53.00"
                },
                {
                    "term": 15,
                    "installment": "43.00"
                },
                {
                    "term": 18,
                    "installment": "36.00"
                },
                {
                    "term": 21,
                    "installment": "31.00"
                },
                {
                    "term": 24,
                    "installment": "28.00"
                },
                {
                    "term": 27,
                    "installment": "25.00"
                },
                {
                    "term": 30,
                    "installment": "22.50"
                },
                {
                    "term": 33,
                    "installment": "21.00"
                }
            ]
        }
    ]
}

Verfügbarkeit prüfen

Die Verfügbarkeit des easyCredit-Ratenkaufs und von easyCredit-Rechnung kann über den Endpoint GET ./webshop geprüft werden. Ist dieser Endpoint erreichbar und liefert für das Attribut availability den Wert true zurück, sind die Zahlarten vollumfänglich verfügbar und können im Webshop eingeblendet und genutzt werden.

Anwendungsbeispiel:

GET ./webshop

JSON-Response:

{
    "maxFinancingAmount": 10000,
    "minFinancingAmount": 199,
    "interestRate": 11.99,
    "availability": true,
    "testMode": false,
    "privacyApprovalForm": "Ich möchte mit easyCredit zahlen und habe zur Kenntnis genommen, dass Beispielshop GmbH der TeamBank AG, Beuthener Str. 25, 90471 Nürnberg zur Bonitätsprüfung personenbezogene Daten wie Anrede und Name, Geburtsdatum und -ort, Kontaktdaten (Adresse, Telefon, E-Mail) sowie Angaben zur aktuellen und zu früheren Bestellungen übermittelt.\n\n",
    "declarationOfConsent": null,
    "illustrativeExample": null,
    "productDetails": null,
    "uuid": null,
    "flexprice": false,
    "installmentPaymentActive": true,
    "billPaymentActive": false,
    "minBillingValue": 50.00,
    "maxBillingValue": 5000.00,
    "minInstallmentValue": 200.00,
    "maxInstallmentValue": 10000.00,
    "interestRateFlexibilisation": {
        "interestRate": null,
        "maxInstallments": null
    }
}

Datenübermittlungshinweis anzeigen

Nachdem der Kunde eine der beiden Zahlarten gewählt hat, muss der Kunde via Hinweistext auf die Übermittlung seiner Daten an die TeamBank hingewiesen werden. Der Datenübermittlungshinweis muss angezeigt werden bevor der Vorgang initialisiert und der Kunde auf die Payment Page weitergeleitet wird.

Eine explizite Zustimmung via Checkbox ist, in Abweichung zu früheren Versionen, nicht mehr erforderlich.

Beispiel:

Beispiel_Datenübermittlungshinweis

Die Texte sollen über den Endpoint GET ./webshop 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.

Anwendungsbeispiel:

GET ./webshop

JSON-Response:

{
    [...]
    "testMode": false,
    "privacyApprovalForm": "Ich möchte mit easyCredit zahlen und habe zur Kenntnis genommen, dass Beispielshop GmbH der TeamBank AG, Beuthener Str. 25, 90471 Nürnberg zur Bonitätsprüfung personenbezogene Daten wie Anrede und Name, Geburtsdatum und -ort, Kontaktdaten (Adresse, Telefon, E-Mail) sowie Angaben zur aktuellen und zu früheren Bestellungen übermittelt.\n\n", // Text für Datenübermittlungshinweis
    "declarationOfConsent": null,
    [...]
    }
}

Initialisierung eines neuen Vorgangs

Die Initialisierung erzeugt einen neuen Vorgang und erfolgt dann, wenn der Kunde, nach Wahl der Zahlart und Zustimmung der Datenübermittlung, auf "Weiter" geklickt hat. Darüber hinaus wird bei der Initialisierung über das Feld paymentType festgelegt, ob es ein Ratenkauf- oder Rechnungsvorgang wird.

"paymentType":"BILL_PAYMENT" erzeugt einen Rechnungskaufvorgang, "paymentType":"INSTALLMENT_PAYMENT" einen Ratenkaufvorgang.

Bei der Initialisierung werden der Payment-API die nötigen Informationen vom Webshop übergeben (Kundendaten, Rechnungs- & Lieferadresse, technische Daten wie Rücksprung URLs bei Erfolg/Ablehnung usw.).

Die Datengruppen customer, customerRelationship und shoppingCartInformation sind so vollständig wie möglich dem Ratenkauf zu übergeben! Dazu gehören die Attribute customerSince, orderDoneWithLogin, numberOfOrders und logisticsServiceProvider aus der Gruppe customerRelationship. Zusätzlich muss zu jeder Positionen im Warenkorb die Attribute price, quantity, productName in der Gruppe shoppingCartInformation hinzugefügt werden.

Sollte ein Teil der geforderten Informationen nicht geliefert werden können, kommen Sie bitte auf uns zu.

Ebenso ist es wichtig, dass die Kriterien aus dem Kapitel Fachliche Voraussetzungen für Bestellungen beachtet werden. Insbesondere ist darauf zu achten, dass Rechnungs- & Lieferadresse in die jeweils dafür vorgesehenen Felder übertragen werden. Wird nur eine der Adressen an sowohl shippingAdress als auch invoiceAdress übertragen, besteht die Gefahr, dass dadurch mit abweichenden Adresse bestellt werden kann. Das ist zu verhindern.

Die API liefert als Antwort u.a. eine transactionId (fachliche Vorgangskennung) und eine technicalTransactionId (technische Vorgangskennung).

Die technicalTransactionId wird ausschließlich in der Kommunikation zwischen Webshop und der Payment-API verwendet, ist dort aber für alle weiteren Endpoints wichtig wie z.B. Entscheidung abrufen oder Vorgang autorisieren.

In der Kommunikation mit dem Kunden und den Ansprechpartnern der TeamBank wird die transactionId (6-stellig, alpha-numerisch, z.B. TXQ7FG) genutzt.

Optional kann neben den anderen ReturnURLs ebenfalls die urlAuthorizationCallback übergeben werden. Sie kann später für die Überprüfung der abgeschlossenen Bestellung benutzt werden.

Ebenfalls optional kann der Webshop bei der Initialisierung eine eigene Order- oder Bestell-ID übergeben. Diese wird zusätzlich mit dem Vorgang verknüpft und kann in der Kommunikation zwischen Händler und TeamBank verwendet werden (z.B. in der Transaktionsverwaltung).

Ein Vorgang verfällt 30 Minuten nach der letzten Aktualisierung durch den Anwender. 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.)

Anwendungsbeispiel:

POST https://ratenkauf.easycredit.de/api/payment/v3/transaction

JSON-Request:

{
    "orderDetails": {
        "orderValue": 2614.79,
        "invoiceAddress": {
            "address": "Beuthener Str. 25",
            "zip": "90471",
            "city": "Nürnberg",
            "country": "DE",
            "additionalAddressInformation": "3 OG"
        },
        "shippingAddress": {
            "address": "Beuthener Str. 25",
            "city": "Nürnberg",
            "country": "DE",
            "firstName": "Max",
            "lastName": "Müller",
            "zip": "90471",
            "additionalAddressInformation": "3 OG"
        },
        "orderId": "A1ZU560", // Shopeigene OrderId
        "numberOfProductsInShoppingCart": 2,
        "shoppingCartInformation": [
            {
                "productName": "Washing Machine",
                "quantity": 1,
                "price": 599.95,
                "manufacturer": "Example vendor",
                "productCategory": "Household Appliances"
            }
        ]
    },
    "customer": {
        "firstName": "Max",
        "lastName": "Müller",
        "contact": {
            "email": "test@teambank.de",
            "mobilePhoneNumber": "01701234567",
            "skipMobilePhoneNumberCheck": false,
            "phoneNumber": "Ut velit aute occaecat minim"
        },
        "gender": "MR",
        "birthDate": "1949-10-17",
        "birthName": "   ",
        "birthPlace": "laboris dolore exercitation eu ipsum",
        "title": "DRDR",
        "bank": {
            "iban": "DE02120300000000202051"
        },
        "employment": {
            "employmentType": "WORKER",
            "monthlyNetIncome": 3000
        }
    },
    "redirectLinks": {
        "urlSuccess": "https://www.beispielwebshop.de/payment_easycredit/return",
        "urlCancellation": "https://www.beispielwebshop.de/module/easycreditratenkauf/canceled",
        "urlDenial": "https://www.beispielwebshop.de/module/easycreditratenkauf/denied",
        "urlAuthorizationCallback": "https://www.beispielwebshop.de/module/easycreditratenkauf/callback"
    },
    "financingTerm": 6,
    "shopsystem": {
        "shopSystemManufacturer": "Shopware 5.5.10",
        "shopSystemModuleVersion": "1.6.3"
    },
    "customerRelationship": {
        "orderDoneWithLogin": false,
        "customerStatus": "NEW_CUSTOMER",
        "customerSince": "2007-10-10",
        "numberOfOrders": 3,
        "negativePaymentInformation": "NO_INFORMATION",
        "riskyItemsInShoppingCart": false,
        "logisticsServiceProvider": "Hermes"
    },
  "paymentType": "INSTALLMENT_PAYMENT",
  "paymentSwitchPossible": false
}

JSON-Response:

{
    "technicalTransactionId": "1.de.4145.1-1020125121-545", // technische Vorgangskennung
    "transactionId": "V32N3T",                              // fachliche Vorgangskennung
    "deviceIdentToken": "a28129b8-3f05-4311-89cf-5f35c44c12a3",
    "timestamp": "2021-10-20T12:51:21.552704+02:00",
    "transactionInformation": {
        "decision": {
            "orderValue": 2614.79,
            "interest": 66.27,
            "totalValue": 2681.06,
            "decisionOutcome": null,
            "numberOfInstallments": 6,
            "installment": 447.00,
            "lastInstallment": 446.06,
            "mtan": {
                "required": true,
                "successful": null,
                "mobilePhoneNumberInvalid": true,
                "skipMobilePhoneNumberValidation": true
            },
            "bankAccountCheck": {
                "required": null,
                "successful": null
            }
        },
        "transaction": {
            "financingTerm": 6,
            "orderDetails": {
                "orderValue": 2614.79,
                "orderId": "A1ZU560",
                "numberOfProductsInShoppingCart": 2,
                "invoiceAddress": {
                    "address": "Beuthener Str. 25",
                    "additionalAddressInformation": "3 OG",
                    "zip": "90471",
                    "city": "Nürnberg",
                    "country": "DE",
                    "firstName": null,
                    "lastName": null
                },
                "shippingAddress": {
                    "address": "Beuthener Str. 25",
                    "additionalAddressInformation": "3 OG",
                    "zip": "90471",
                    "city": "Nürnberg",
                    "country": "DE",
                    "firstName": "Max",
                    "lastName": "Müller"
                },
                "shoppingCartInformation": [
                    null
                ]
            },
            "shopsystem": {
                "shopSystemManufacturer": "Shopware 5.5.10",
                "shopSystemModuleVersion": "1.6.3"
            },
            "customer": {
                "gender": "MR",
                "firstName": "Max",
                "lastName": "Müller",
                "birthDate": "1949-10-17",
                "birthName": "   ",
                "birthPlace": "laboris dolore exercitation eu ipsum",
                "title": "DRDR",
                "contact": {
                    "email": "test@teambank.de",
                    "mobilePhoneNumber": "01701234567",
                    "phoneNumber": "Ut velit aute occaecat minim",
                    "phoneNumbersConfirmed": true
                },
                "bank": {
                    "iban": "DE02120300000000202051"
                },
                "employment": {
                    "employmentType": "WORKER",
                    "monthlyNetIncome": 3000
                }
            },
            "customerRelationship": {
                "customerStatus": "NEW_CUSTOMER",
                "customerSince": "2007-10-10",
                "orderDoneWithLogin": false,
                "numberOfOrders": 3,
                "negativePaymentInformation": "NO_INFORMATION",
                "riskyItemsInShoppingCart": false,
                "logisticsServiceProvider": "Hermes"
            },
            "redirectLinks": {
                "urlSuccess": "https://www.beispielwebshop.de/payment_easycredit/return",
                "urlCancellation": "https://www.beispielwebshop.de/module/easycreditratenkauf/canceled",
                "urlDenial": "https://www.beispielwebshop.de/module/easycreditratenkauf/denied",
                "urlAuthorizationCallback": null
            },
            "consent": {
                "sepaMandate": null,
                "advertisement": false,
                "dataProcessing": null
            },
            "paymentType": "INSTALLMENT_PAYMENT",
            "paymentSwitchPossible": false
        },
        "status": "OPEN"
    }
}

Redirect auf Payment Page

Nach der erfolgreichen Initialisierung nutzen Sie die redirectUrl, die Sie in der Response erhalten, um den Kunden auf die Payment Page weiterzuleiten. Diese wird üblicherweise so aussehen:

https://ratenkauf.easycredit.de/app/payment/{technicalTransactionId}/finanzierungsvorgaben

Wichtig:

Der Button, der die Weiterleitung auslöst, darf nicht "Zahlungspflichtig bestellen" o.ä. benannt sein, da der Bestellprozess an dieser Stelle noch nicht abgeschlossen ist. Besser ist z.B. "Weiter zu easyCredit".

Auf der Payment Page kann der Kunde ggfs. noch einmal den gewünschten Ratenplan wählen, seine persönlichen Daten wie z.B. IBAN und Mobilfunknummer ergänzen und letztlich die Bonitätsprüfung durchführen. Je nachdem wie das Ergebnis ausfällt, wird der Kunde auf einer der drei zuvor übergebenen Return-URLs geleitet (urlSuccess, urlCancellation oder urlDenial).

Beispiel Payment Page:

Beispiel_Payment_Page

Ablehnung oder Abbruch

Für den Fall, dass dem Kunden kein Raten- oder Rechnungskauf angeboten werden kann oder er abgebrochen hat, sollte der Kunde wieder auf die Zahlartenauswahl geleitet werden.

Erfolg & Rückleitung Webshop

Auch im Erfolgsfall wird der Kunde via urlSuccess wieder in den Checkout zurückgeleitet, um dort seine Bestellung abschließen zu können. Die Weiterleitung erfolgt üblicherweise auf die letzte Seite des Checkouts vor dem Bestellabschluss, auf der dem Kunden noch einmal alle Details und Position übersichtlich dargestellt werden.

Dass der Vorgang positiv entschieden wurde, heißt an dieser Stelle noch nicht, dass der Raten- oder Rechnungskauf abgeschlossen wurde, sondern, dass die TeamBank den Forderungsankauf garantiert. Erst wenn der Kunde die Bestellung abgeschlossen hat, ist auch der easyCredit-Vorgang abgeschlossen.

Auf der Bestellübersicht sind nun noch folgende Schritte zu erledigen:

  • Ergebnis der Bonitätsprüfung abrufen
  • (Nur Ratenkauf: Ratenkaufzinsen anzeigen)

Ergebnis von Kreditentscheidung abrufen:

Aus Sicherheitsgründen ist es notwendig, dass nach der Rückkehr in den Checkout noch einmal das Ergebnis der Kreditentscheidung vom Shop abgerufen wird. Das geschieht über den Endpoint GET ./transaction/{id}.

Anwendungsbeispiel:

GET ./transaction/{id}

JSON-Response:

{
    "decision": {
        "orderValue": 2614.79,
        "interest": 611.95,
        "totalValue": 3226.74,
        "decisionOutcome": "POSITIVE", // Entscheidungsergebnis
        "numberOfInstallments": 60,
        "installment": 54,
        "lastInstallment": 40.74,
        "mtan": {
            "required": false,
            "successful": null,
            "mobilePhoneNumberInvalid": null,
            "skipMobilePhoneNumberValidation": null
        },
        "bankAccountCheck": {
            "required": false,
            "successful": null
        }
    },
    "transaction": {
        ...
        }
    },
    "status": "PREAUTHORIZED"
}

Nur solange das decisionOutcome POSITIVE ist, soll der Kunde bestellen können. In allen anderen Fällen darf die Bestellung nicht mit einer der easyCredit-Zahlarten fortgesetzt werden können.

Nur Ratenkauf: Anzeige der Ratenkaufzinsen:

Beim Ratenkauf ist es rechtlich erforderlich, dass dem Kunden vor dem Bestellabschluss alle mit dem Kauf verbundenen Kosten dargestellt werden, inkl. der Ratenkaufzinsen.

Dazu müssen die Zinsen in der Übersicht der Positionen explizit als separate Position angezeigt und zeitgleich in die Gesamtsumme miteinberechnet werden.

Beispiel:

Beispiel Kosten im Checkout

So wie das Ergebnis der Ratenkaufentscheidung können auch die Zinsen über den Endpoint GET ./transaction{id} bezogen werden:

Anwendungsbeispiel:

GET ./transaction/{id}

JSON-Response:

{
    "decision": {
        "orderValue": 2614.79, // Warenwert (inkl. Versand) ohne Zinsen
        "interest": 611.95, // Ratenkaufzinsen
        "totalValue": 3226.74, // Gesamtsumme
        "decisionOutcome": "POSITIVE", 
        "numberOfInstallments": 60,
        "installment": 54,
        "lastInstallment": 40.74,
        "mtan": {
            "required": false,
            "successful": null,
            "mobilePhoneNumberInvalid": null,
            "skipMobilePhoneNumberValidation": null
        },
        "bankAccountCheck": {
            "required": false,
            "successful": null
        }
    },
    "transaction": {
        ...
        }
    },
    "status": "PREAUTHORIZED"
}

Bestätigung & Callback

Hat der Kunde auf "Zahlungspflichtig bestellen" geklickt folgt jetzt die Bestätigung bzw. Autorisierung des Vorgangs. Dafür wurde die neue 2-Phasen-Bestätigung eingeführt, die dafür sorgt, dass eine Bestellung nur dann erfolgreich beendet werden kann, wenn vorher auch die Bestätigung des Ratenkaufs geklappt hat.

Hierzu sieht der Workflow wie folgt aus:

Autorisierung:

Nachdem im vorherigen Schritt bereits geprüft wurde, dass der Vorgang vorautorisiert ist (Status preAuthorized), muss für den Abschluss nun die Autorisierung erfolgen.

Dies geschieht über den Endpoint POST ./transaction/{id}/authorization.

Die erfolgreiche Autorisierung wird mit dem Statuscode 202 quittiert. Dem Kunden kann nun die "Vielen-Dank-Für-Ihre-Bestellung"-Seite angezeigt werden.

Nur wenn die Response geprüft wurde und erfolgreich war (202), darf der Shop die Bestellung anlegen. Wenn das nicht erfüllt ist, soll die Bestellung nicht abgeschlossen werden dürfen.

Anwendungsbeispiel:

POST ./transaction/{id}/authorization

JSON-Request:

{
  "orderId": AGSX1232  // Shopeigene OrderId
}

JSON-Response:

Status 202 Accepted

Wie im obigen Beispiel zu sehen ist, kann in diesem Schritt optional auch noch eine shopeigene Bestell- oder Ordernummer an die TeamBank übergeben werden ("orderId"). Analog zur Initialisierung wird diese orderId dann an den Vorgang geknüpft und bspw. auf Abrechnungsdokumenten oder im Partner Portal angezeigt.

Autorisierung prüfen:

Um zu verhindern, dass Ware fälschlicherweise verschickt wird, obwohl der Vorgang nicht komplett abgeschlossen wurde, stehen zwei Möglichkeiten zur Verfügung, die Statusprüfung (obligatorisch) und der Callback (optional).

Statusprüfung

Bevor die letztendliche Bestellbestätigungsmail vom Shopsystem versendet oder der Zahlstatus auf "BEZAHLT" gesetzt wird, muss über den Endpoint GET ./transaction/{id} geprüft werden, ob die Autorisierung erfolgreich abgeschlossen wurde.

Hierzu muss das Attribut Status im Body der Response geprüft werden. Ist der Status authorized, wurde die Autorisierung erfolgreich verabeitet, der Raten- oder Rechnungskauf final bestätigt und die Auftragsbestätigung kann an den Enkunden versendet werden.

Ist dies nicht der Fall, sollte der Aufruf binnen der nächsten Minuten mehrmals wiederholt werden. Ist der Status weiterhin nicht authorized, kann eine erneute Autorisierung ausgeführt werden.

Anwendungsbeispiel:

  GET ./transaction/{id}

JSON-Response:

  {
    "decision": {
        ...
    },
    "transaction": {
        ...
    },
    "status": "AUTHORIZED"
}

Damit ist auch der Vorgang bei der TeamBank abgeschlossen und die technicalTransactionId verfällt.

Callback

Darüber hinaus ist es optional möglich, dass der Aufruf der Callback-URL (urlAuthorizationCallback) vom Webshop erfolgreich angenommen wird, bevor der Zahlstatus auf "BEZAHLT" gesetzt wird. Diese URL wird bei der Initialisierung des Vorgangs an uns übertragen und wird von den Servern der TeamBank aufgerufen, sobald der Ratenkauf bei uns komplett abgeschlossen und in den Systemen vorhanden ist.

Nach dem abgeschlossenen Kauf ist es notwendig, den Versand der Bestellung an die TeamBank zu melden. Erst danach findet die Auszahlung an den Händler und der Einzug beim Kunden statt. Genaueres dazu finden Sie hier

Optional: Body-Signatur

Mit Hilfe der Body-Signatur können bei Bedarf die Requests an uns signiert werden. Dadurch kann sichergestellt werden, dass die Requests auf dem Weg zur und von der Payment-API nicht manipuliert wurden. Standardmäßig ist diese Funktion deaktiviert und für die Integration optional.

Möchte Sie die Funktion nutzen, müssen sie die Body-Signatur über das Partner Portal aktivieren.

API_Signatur

Im ersten Schritt müssen Sie dazu einen Geheimschlüssel generieren und im Webshop bzw. im Plugin hinterlegen. Anschließend aktivieren Sie im zweiten Schritt die Funktion im Partnerportal. Ab diesem Zeitpunkt werden nur noch signierte Requests von der API akzeptiert und verarbeitet.

Nach erfolgreicher Aktivierung müssen alle Requests das Header-Attribut Content-signature enthalten. In diesem wird die errechnete Signatur zum JSON-formatierten Body des Requests eingetragen. Die Signatur berechnet sich wie folgt:

SHA256( yourJsonBody + signatureSecret )

Im ersten Schritt wird der Json-Body normalisiert in dem alle Tabulatoren (\t), New Lines (\n) und Carriage Returns (\r) entfernt werden. Anschließend wird der Geheimschlüssel an den normalisierten Body konkatiniert.

Für diesen String wird nun der Hashwert mit dem Verfahren SHA-256 berechnet und als Wert des Header-Attributs Content-signature gesetzt.

Beispiel:

Geheimschlüssel Geh31m5ch1ue5531

Body:

  {
    "message": "easyCreditTestSignatur"
  }

Berechnung:

  SHA256({    "message": "easyCreditTestSignatur"}Geh31m5ch1ue5531)

Header-Attribut:

  Content-signature: sha256=5fe1c570db98dba8bf33fa7a9f298a4150e988c02269867d5eab2ccbbc13e632

Stimmt die Signatur im Header mit dem Body überein, wird der Request von uns verarbeitet. Weicht dieser ab, wird dies mit dem Statuscode 400 quittiert. Es erfolgt keine Verarbeitung.

Neben den Requests werden mit der Aktivierung der Body-Signatur im Partner Portal auch die Responses von uns signiert. Hierzu wird ebenfalls der Geheimschlüssel des Shops genutzt. Somit kann der Webshop die Body-Signatur unserer Response prüfen und sicherstellen, dass die Antwort nicht manipuliert wurde. Hierzu muss die Signatur vom Body der Response, analog der Berechnung für den Request-Body, berechnet werden. Anschließend kann die errechnete Signatur mit der Signatur aus dem Header-Attribut Content-signature der Response verglichen werden. Stimmen die Werte überein, kann die Response vom Shop-System verarbeitet werden. Andernfalls sollte diese verworfen werden.

Nach der Bestellung

Ist die Bestellung korrekt in Ihrem Shopsystem eingegangen und die Ware versandbereit, dann ist es erforderlich, der TeamBank den Versand der Ware zu melden. Erst danach startet einerseits der Einzug beim Endkunden und andererseits die Auszahlung an den Händler.

Auch gibt es die Möglichkeit teilweise oder vollständige Rückabwicklungen an uns zu melden, unabhängig davon, ob die Ware bereits verschickt wurde oder noch nicht.

Details dazu finden Sie auch in unserem Händlerhandbuch.

Beides kann entweder über das bereitgestellte Partner Portal erfolgen oder über eine separate API, die Sie bei sich integrieren können, die MerchantAPI.

Integration Transaction-API

Neben der bisher hauptsächlich behandelten Payment-API gibt es auch noch die Transaction-API, die für die Meldung von Lieferungen und Rückabwicklungen genutzt werden kann.

Diese können Sie bei Bedarf in Ihr Shopsystem oder ERP integrieren, um damit diese Prozesse möglichst automatisiert in Ihren bestehenden Workflow einzubetten.

Anders als bei der Payment-API oder der früheren Händlerinterface-API handelt es sich bei der Transaction-API um eine asynchrone Schnittstelle.

Die Dokumentation zur Integration der Transaction-API finden Sie hier und den Integration Guide dazu hier.

Go-Live & Abnahme

Checkliste

Sie wollen wissen, ob Sie an alles gedacht haben und ob Ihre Integration abgenommen werden kann? Dann können Sie unsere Checkliste zur Hilfe nehmen:

  • Vollständiger Workflow inkl. Autorisierung

    Alle oben genannten vorgangsrelevanten Endpoints wurden abgerufen, der Status des Vorgangs ist authorized und die Autorisierung wurde noch einmal mit GET ./transaction/{id} geprüft.

  • Anzeige Datenübermittlungshinweis

    Der Datenübermittlungshinweis wird auf der Zahlartenauswahl angezeigt.

  • Anzeige Zinsen Bestellübersicht (Nur Ratenkauf)

    Auf der Bestellübersichtsseite (vor dem Abschluss) werden dem Kunden die Ratenkaufzinsen als separate Position angezeigt und in den Gesamtbetrag eingerechnet.

  • Anzeige AGB-Ergänzungen

    (Nur für Shopbetreiber relevant) Auf der Shopseite der AGB werden die AGB-Ergänzungen der TeamBank angezeigt.

  • Anzeige Ratenrechner (optional)

    Auf den Produktseiten wird das easyCredit-Widget beim Produktpreis angezeigt und kann geöffnet werden.

Abnahme der easyCredit-Integration

Nach der erfolgreichen Integration der easyCredit-Zahlarten ist eine Abnahme durch das easyCredit-Team verpflichtend. Dafür führen wir ein oder mehrere Testkäufe durch, dokumentieren die einzelnen Schritte und geben Ihnen im Fall des Falles selbstverständlich Hinweise, wenn etwas verbessert werden kann.

Wenn alle Punkte der Checkliste erfüllt sind, dann wenden Sie sich gerne an ratenkauf@easycredit.de. Dort werden wir Sie beim Livegang unterstützen.

Web Components

Seit einiger Zeit bieten wir zentralseitig Web Components an.

Die easyCredit Web Components sind ein Set von Webkomponenten, die universell in E-Commerce-Plattformen wie z.B. Magento oder Shopware o.ä. eingesetzt werden können. Die Webkomponenten erleichtern die Integration der easyCredit-Zahlarten durch vielseitige Web-Frontend-Elemente für Marketing, Checkout und Händlerverwaltung.

Eine Installationsanleitung und viele interaktive Beispiele zu den Components finden Sie hier:

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/getting-started-installation--page

Beispiele

Modellrechner-Widget

Modellrechner-Widget

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/marketing-widget--widget-normal

Checkout-Widget Rechnung

Checkout-Widget Rechnung

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/checkout-checkout--checkout-initial

Checkout-Widget Ratenkauf

Checkout-Widget Ratenkauf

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/checkout-checkout--checkout-initial

Infopage Ratenkauf inkl. FAQ

Infopage-Widget

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/marketing-infopage--infopage

Einbindung via Script

Zur Integration der Web Components in ein beliebiges System fügen Sie die folgenden Zeilen in den <head> Ihres Shops ein:

<script type="module" src="https://ratenkauf.easycredit.de/api/resource/webcomponents/v3/easycredit-components/easycredit-components.esm.js"></script>
<script nomodule src="https://ratenkauf.easycredit.de/api/resource/webcomponents/v3/easycredit-components/easycredit-components.js"></script>

Jetzt können Sie jede der Komponenten innerhalb der Website verwenden:

<easycredit-widget amount="500" webshop-id="1.de.1234" />

In ein bestehendes JavaScript-Projekt installieren

Um die Komponenten in einem JavaScript-Projekt zu verwenden, installieren Sie das NPM-Package:

npm install --save @easycredit-ratenkauf/web-components
# or
yarn add @easycredit-ratenkauf/web-components

Sie können die Komponenten nun importieren:

import { EasyCreditWidget } from "@easycredit-ratenkauf/web-components";

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 (POSITIVE) oder nicht (NEGATIVE). Eine Positiventscheidung mit zwingender Anpassung der Laufzeit ("POSITIVE mit Einschränkung") stellt kein eigenständiges Entscheidungsergebnis dar.

Bestellwert / Finanzierungsbetrag

Der monetäre Betrag für die Ware(n) inkl. Versandkosten eines Händlers, die ein Käufer über easyCredit-Rechnung o. -Ratenkauf finanzieren will.

Finanzierungszusage

Eine Finanzierungszusage der TeamBank an den Händler bedeutet, dass die TeamBank sich bereit erklärt, den Raten- o. Rechnungskauf 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 o. Rechnungs-Vorgang

Die Vorgangsdaten umfassen alle relevanten Angaben zur Geschäftsabwicklung des Rechnungs- o. 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.

Webshop-ID

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

Technische Vorgangskennung / technicalTransactionId

Eine global eindeutige Kennung, im Schnittstellenmodell technicalTransactionId 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 technicalTransactionId nicht weiterverwendet. Ein Vorgang kann im Bestand auch nicht mehr über die technicalTransactionId identifiziert werden.

Shopeigene Order- / Bestellnummer

Eine vom Händler gegenüber dem Kunden oder intern in der Buchhaltung verwendete Referenz zur Bestellung im Shop. Die shopeigene Order- / Bestellnummer wird nicht zur technischen Identifikation eines Vorgangs verwendet, sondern lediglich zur menschlichen Nachvollziehbarkeit z.B. in der Händler-Abrechnung oder den Zahlungsavis. Abgeschlossene Bestellungen können im Partner Portal auch über das Feld Bestellnummer gesucht werden.

Fachliche Vorgangskennung / transactionId

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