- Dokumentationen
- Integration Guide Transaction API v3
Integration Guide easyCredit-Ratenkauf Transaction-API V3
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.
Inhaltsverzeichnis
- Inhaltsverzeichnis
- Grundlegendes
- Authentifizierung
- Base-URL
- Aufrufe
- Optional: Benachrichtigungs-URL
- Optional: Body-Signatur
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.
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 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.