Integration Guide Payment API v3

Logo

Stand: 15.09.2022

Mithilfe dieser Anleitung können Sie in wenigen Schritten die Prozesse, die nach Abschluss eines easyCredit-Ratenkaufs möglich sind, über eine Schnittstelle einbinden. So können Sie mittels der Transaction-API beispielsweise aus Ihrem Shopsystem-Backend Lieferungen und Rückabwicklungen an die TeamBank melden, ohne dass Sie sich in einer weiteren Anwendung einloggen müssen.

Grundlegendes

Bei der Transaction-API handelt es sich, analog zur Payment-API, um eine REST-Schnittstelle, die mittels Requests im JSON-Format angesprochen wird.

Asynchronität

Die Transaction-API arbeitet asynchron. Das bedeutet, dass eingehende Requests erst einmal grundsätzlich mit einer Erfolgsmeldung angenommen werden, sofern sie technisch und syntaktisch korrekt übermittelt werden. Die eigentliche Verarbeitung in den Systemen der Bank erfolgt erst im Anschluss und somit wird erst ab diesem Zeitpunkt deutlich, ob der Request auch inhaltlich korrekt ist und umgesetzt werden kann (Beispiel: Kann die Rückabwicklung über 1000 € des Vorgangs erfolgen, obwohl der Restbetrag niedriger ist?) Anders ausgedrückt: Ein erfolgreiche Response mit bspw. Status Code 200 gewährleistet noch nicht automatisch, dass die gewünschte Änderung an der Ratenkauf-Bestellung erfolgt.

In der Handhabung bedeutet das, dass nach Abschicken des Requests danach immer noch einmal eine Abfrage erfolgen muss, ob die gewünschte Änderung auch tatsächlich erfolgt ist. Alternativ kann dafür auch die Benachrichtigungs-URL genutzt werden, um sich ein manuelles Abfragen zu ersparen. Genaueres dazu erfahren Sie hier

Anleitungen

Neben diesem Integration Guide stehen Ihnen eine generierte Schnittstellendokumentation zur Verfügung.

Falls Sie die Dokumentation im OpenAPI-Format benötigen finden Sie diese hier:

Transaction-API im OpenAPI Format

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.

Ausgehend von den REST-Ressourcen kann man sich dort alle Request-/Response-Objekte (Elements) mit JSON-Beispiel ansehen.

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

Zugangsdaten

Um den die Transaction-API 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.

Authentifizierung

Die Authentifizierung an der Transaction-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

Base-URL

Die Transaction-API hat folgende Base-URL:

https://partner.easycredit-ratenkauf.de/api/merchant/v3/

Aufrufe

Die Transaction-API besteht aus den Aufrufen:

Suchen von Vorgängen/Bestellungen anhand von Parametern
Suchen von einzelnen Vorgängen/Bestellungen anhand der Vorgangskennung
Lieferung melden
Rückabwicklung melden
Billing Dokumente herunterladen

Suchen von Vorgängen/Bestellungen anhand von Parametern

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/transaction

Request-Parameters:

name	type	description	constraints
firstname	string	Vorname d. Kunden
lastname	string	Nachname d. Kunden
orderId	string	Händlereigene Bestellnr.
pageSize	integer	Paginierung	Default value: 100
page	integer	Paginierung
status	array[string]	Status, d. die gesuchten Vorgänge besitzen sollen	REPORT_CAPTURE, REPORT_CAPTURE_EXPIRING, IN_BILLING, BILLED, EXPIRED
minOrderValue	number	minimaler Bestellwert
maxOrderValue	number	maximaler Bestellwert

Anwendungsbeispiel:

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/transaction?firstname=Ralf&minOrderValue=500

Response:

{
    "TransactionList": [
        {
            "transactionId": "V3QAME",
            "status": "REPORT_CAPTURE",
            "bookings": [],
            "customer": {
                "firstName": "Ralf",
                "lastName": "Ratenkauf",
                "customerNumber": "9667463757"
            },
            "creditAccountNumber": "9897838057",
            "orderDetails": {
                "orderId": "20008",
                "clearingDate": null,
                "orderDate": "2022-03-30",
                "currentOrderValue": 950.50,
                "originalOrderValue": 950.50
            },
            "refundDetails": [],
            "refundsTotalValue": 0,
            "expirationDateTime": "2022-07-20T15:00:11+02:00"
        }
    ],
    "PagingDetails": {
        "page": 0,
        "pageSize": 100,
        "count": 1
    }
}

Suchen von einzelnen Vorgängen/Bestellungen anhand der Vorgangskennung

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/transaction/{transactionId}

Request-Parameters:

name	type	description	constraints
transactionId	string	die fachliche Vorgangskennung (6 Zeichen) d. Vorgangs, d. gesucht werden soll

Anwendungsbeispiel:

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/transaction/V3P6EU

Response:

{
    "transactionId": "V3P6EU",
    "status": "BILLED",
    "bookings": [
        {
            "uuid": "a23d6b43-05c0-41b9-b2ef-7d5ec5c5af40",
            "created": "2022-03-10T18:49:16+01:00",
            "type": "CAPTURE",
            "status": "DONE",
            "message": null
        },
        {
            "uuid": "14c689f3-3dee-4bcf-8b98-4f4f8474e1db",
            "created": "2022-03-10T18:52:05+01:00",
            "type": "REFUND",
            "status": "DONE",
            "message": null
        }
    ],
    "customer": {
        "firstName": "Ralf",
        "lastName": "Ratenkauf",
        "customerNumber": "9631083212"
    },
    "creditAccountNumber": "9368076084",
    "orderDetails": {
        "orderId": "119",
        "clearingDate": null,
        "orderDate": "2022-03-10",
        "currentOrderValue": 0.00,
        "originalOrderValue": 415.31
    },
    "refundDetails": [
        {
            "refundAmount": 415.31,
            "refundBookingDate": null,
            "refundEntryDate": "2022-03-10",
            "refundDate": "2022-03-10",
            "reason": "REFUND_GUARANTEE_WARRANTY"
        }
    ],
    "refundsTotalValue": 415.31,
    "expirationDateTime": null
}

Lieferung melden

Meldet die Lieferung (Capture) für den ausgewählten Vorgang. Pro Vorgang kann die Lieferung nur einmal gemeldet werden.

Im Erfolgsfall der Übertragung bleibt der Body der Response leer. Die Übertragung war dann erfolgreich, wenn die Response den HTTP Status Code 202 trägt.

Durch die asynchrone Verarbeitung der API v3 ist es nicht möglich, direkt aus der Antwort herauszulesen, ob die Änderung am Vorgang auch fachlich verarbeitet werden konnte. Dafür muss der Vorgang entweder noch einmal per ./transaction oder ./transaction/{transactionId} aufgerufen werden oder es kann die [BenachrichtungsURL] genutzt werden.

Anders als in früheren API-Versionen kann und soll das Datum der Lieferung nicht mehr im Request-Body übertragen werden.

Im Body kann die Sendungsverfolgungsnummer des jeweiligen Logistikpartners an die TeamBank übertragen werden via des Felds trackingNumber.

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/transaction/{transactionId}/capture

Request-Parameters:

name	type	description	constraints
transactionId	string	fachliche Vorgangskennung (6 Zeichen) d. Vorgangs zu d. die Lieferung gemeldet werden soll

Anwendungsbeispiel:

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/transaction/V3PQCE/capture

{
    "trackingNumber": "JJD0099999999"
}

Response:

HTTP Status Code 202 - Accepted for processing

Rückabwicklung melden

Meldet eine Rückabwicklung für den ausgewählten Vorgang. Pro Vorgang kann nur eine Rückabwicklung gleichzeitig von der API angenommen werden. Wenn eine weitere Rückabwicklung durchgeführt werden soll, muss abgewartet werden, bis die vorhergehende vom System erfasst wurde.

Eine Rückabwicklung ist zu jeder Zeit innerhalb des Prozesses möglich (sowohl vor, als auch nach Capture) und kann entweder über den kompletten Betrag erfolgen, als auch über einen Teilbetrag.

Über das Feld "value" im Request-Body wird übertragen, um welchen Betrag der aktuelle Bestellwert vermindert werden soll. Es handelt sich NICHT um den Gesamtbetrag nach Rückabwicklung.

Im Erfolgsfall der Übertragung bleibt der Body der Response leer. Die Übertragung war dann erfolgreich, wenn die Response den HTTP Status Code 202 trägt.

Anders als in früheren API-Versionen kann und soll das Datum der Rückabwicklung nicht mehr im Request-Body übertragen werden.

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/transaction/{transactionId}/refund

Request-Parameters:

name	type	description	constraints
transactionId	string	fachliche Vorgangskennung (6 Zeichen) d. Vorgangs zu d. die Rückabwicklung gemeldet werden soll

Anwendungsbeispiel:

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/transaction/V3PQCE/refund

{
    "value": "100"
}

Response:

HTTP Status Code 202 - Accepted for processing

Vorgang nach nochmaligen Aufrufs mittels ./transaction/{transactionId} (siehe "bookings" und "refundDetails"):

{
    "transactionId": "V3PQCE",
    "status": "IN_BILLING",
    "bookings": [
        {
            "uuid": "7761dfcc-3745-45cd-9204-98625f43aceb",
            "created": "2022-04-13T16:44:50+02:00",
            "type": "REFUND",
            "status": "DONE",
            "message": null
        },
        {
            "uuid": "591a3c95-edbe-444c-b4dd-20e1f12fa95b",
            "created": "2022-04-13T16:28:31+02:00",
            "type": "CAPTURE",
            "status": "DONE",
            "message": null
        }
    ],
    "customer": {
        "firstName": "Max",
        "lastName": "Muster",
        "customerNumber": "9527722009"
    },
    "creditAccountNumber": "9259705224",
    "orderDetails": {
        "orderId": null,
        "clearingDate": null,
        "orderDate": "2022-03-16",
        "currentOrderValue": 400.00,
        "originalOrderValue": 500.00
    },
    "refundDetails": [
        {
            "refundAmount": 100.00,
            "refundBookingDate": null,
            "refundEntryDate": "2022-04-13",
            "refundDate": "2022-04-13",
            "reason": "REDUCTION_GUARANTEE_WARRANTY"
        }
    ],
    "refundsTotalValue": 100.00,
    "expirationDateTime": null
}

Billing Dokumente herunterladen

Über diesen Endpoint können Billing Dokumente, wie z.B. Zahlungsavis abgerufen und gesammelt heruntergeladen werden.

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/documents

Request-Parameters:

name	type	description	constraints
billingDateFrom	string($date)	ab-Datum - default letzter Monat, wenn nicht anders angegeben
billingDateTo	string($date)	bis-Datum - default billingDateFrom + 1 Monat, wenn nicht anders angegeben
documentType	array[string]	Dokumententyp	MONTHLY_BILL, ADVICE_OF_SETTLEMENT, LEG_BILL, DUNNING_LETTER
fileType	array[string]	Dateityp	PDF, CSV, MSG

Anwendungsbeispiel:

Request:

GET https://partner.easycredit-ratenkauf.de/api/merchant/v3/documents?fileType=PDF&billingDateFrom=2021-09-22&documentType=MONTHLY_BILL

Response:

HTTP Status Code 200

Optional: Benachrichtigungs-URL

Um schneller und einfacher nachvollziehen zu können, ob die Meldung von Lieferungen und Rückabwicklungen erfolgreich war, können Sie im Partnerportal in der Shopadministration eine individuelle Benachrichtigungs-URL hinterlegen.

Das kann z.B. sinnvoll sein, wenn die API in Ihrem Webshop oder Warenwirtschaftssystem integriert ist und die Prozesse weitestgehend automatisiert werden sollen.

Die Benachrichtigungs-URL wird bei einer Statusänderung eines Vorgangs mit der dazugehörigen Vorgangskennung im Query-Parameter vorgangskennung aufgerufen.

Beispiel:

GET <benachrichtigungsurl>?vorgangskennung=12GA5I7

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.

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	Geh31m5chue5531

Body:

  {
    "message": "ratenkaufByEasyCredit"
  }

Berechnung:

  SHA256({    "message": "easyCredit-Ratenkauf"}Geh31m5chue5531)

Header-Attribut:

  Content-signature: sha256=0d17b9d8c6ad49aaced5cff8788550efe539905a59dc7e1550a85554a3208507

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

Integration Guide Payment API v3

Inhaltsverzeichnis

Grundlegendes

Asynchronität

Anleitungen

Zugangsdaten

Authentifizierung

Base-URL

Aufrufe

Suchen von Vorgängen/Bestellungen anhand von Parametern

Suchen von einzelnen Vorgängen/Bestellungen anhand der Vorgangskennung

Lieferung melden

Rückabwicklung melden

Billing Dokumente herunterladen

Optional: Benachrichtigungs-URL

Optional: Body-Signatur

Unser Partner: Trusted Shops