API-Referenz Transaktionen

Der Endpunkt transactions/ stellt eine Schnittstelle zur Verfügung, mit der Zahlungsinformationen aus dem Shop-System abgerufen und verwaltet werden können.

Zu jeder Transaktion lassen sich Details wie Zahlungsart, Status, Beträge und zeitliche Abläufe einsehen. Darüber hinaus unterstützt die Schnittstelle die Aktualisierung des Status sowie Aktionen wie Erfassung, Rückerstattung oder Abbruch.

---

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	DELETE	GET	POST	PUT
Transaktionen	transactions/

Datenfelder einer Transaktion

Name	Typ	Bedeutung
accountId	Integer	ID des Kundenkontos, das die Zahlung durchgeführt hat.
amount	String	Betrag der Transaktion (in der jeweiligen Währung).
clearerId	String	ID des Zahlungsdienstleisters (z. B. PayPal, Klarna).
createdAt	String	Zeitpunkt der Erstellung (ISO 8601-Format, UTC).
currency	String	ISO-Währungscode (z. B. “EUR”).
id	String	Eindeutige ID der Transaktion.
orderId	String	ID der Bestellung, zu der die Transaktion gehört.
payedAt	String	Zeitpunkt der Bezahlung (ISO 8601-Format, UTC).
paymentMethod	String	Bezeichner der gewählten Zahlungsart (z. B. “paypalCheckout”).
paymentStatus	Integer	Status der Bezahlung (z. B. offen, bezahlt, fehlgeschlagen). Mögliche Werte: 0 = Pending1 = Finished2 = Error3 = Redirected4 = Canceled5 = Rejected6 = CanceledByAdmin7 = Refunded8 = RefundedPartially
refundedAt	String	Zeitpunkt der Rückerstattung (falls erfolgt).
sessionId	String	ID der Session, in der die Zahlung erfolgt ist.
subshopId	String	ID des Subshops, in dem die Zahlung stattgefunden hat.
updatedAt	String	Zeitpunkt der letzten Aktualisierung (ISO 8601-Format, UTC).
testOrder	Integer	Kennzeichnung, ob es sich um eine Testbestellung handelt (0 = nein, 1 = ja).

Beispiel

{
    "accountId": 4,
    "amount": "23.940000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-20T15:20:26Z",
    "currency": "EUR",
    "id": "7RL91160EW951091F",
    "orderId": "1501",
    "payedAt": "2025-03-20T15:20:26Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 1,
    "refundedAt": "0000-00-00T00:00:00Z",
    "sessionId": "8ed8455230bf1920dda6fe73c550d72620647ff35cec4fe3cfe6c410fa487cc0",
    "subshopId": "deutsch",
    "testOrder": 0,
    "updatedAt": "2025-03-20T15:20:26Z"
}

Methoden für die Transaktionen

Die folgenden Methoden ermöglichen es, Transaktionen im Shop-System zu verwalten. Eine Transaktion erfasst die Zahlungsbewegung zu einer Bestellung und enthält Informationen wie Betrag, Status, Zahlungsart und Zeitpunkte der Zahlung oder Rückerstattung. Über die API können Transaktionen ausgelesen, ihr Status aktualisiert, zurückerstattet, abgebrochen oder erfasst werden.

Für alle Methoden müssen entsprechende Berechtigungen zum Lesen oder Schreiben von Transaktionsdaten vorhanden sein.

GET transactions

Mit dem Endpunkt transactions können Sie auf eine Liste abgeschlossener Transaktionen im Shop zugreifen.

Die API ermöglicht es, Transaktionen nach verschiedenen Kriterien wie Zeiträumen, Zahlungsstatus oder Subshop zu filtern und zu sortieren. Die Transaktionen enthalten unter anderem Informationen zu Beträgen, Zahlungsmethoden, zugehörigen Bestellungen und Kundenkonten.

Um auf diesen Endpunkt zuzugreifen, müssen die entsprechenden Berechtigungen zum Lesen von Transaktionsdaten vorhanden sein.

Beispiel

Das Beispiel zeigt eine Abfrage von bis zu 100 Transaktionen, die im Zeitraum vom 23.03.2025 bis einschließlich 22.04.2025 erstellt wurden.

http://www.<ihr-shop>.de/admin/api/v1/transactions?size=100&filter_gte[createdAt]=2025-03-23T00:00:00.360Z
&filter_lte[createdAt]=2025-04-22T23:59:59.360Z

Antwort

{
    "endReached": true,
    "items": [
        {
            "accountId": 4,
            "amount": "12.950000",
            "clearerId": "paypal-checkout",
            "createdAt": "2025-03-24T08:08:16Z",
            "currency": "EUR",
            "id": "86T19828EK510721G",
            "orderId": "1553",
            "payedAt": "2025-03-24T08:08:16Z",
            "paymentMethod": "paypalCheckout",
            "paymentStatus": 1,
            "refundedAt": "0000-00-00T00:00:00Z",
            "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
            "subshopId": "deutsch",
            "testOrder": 0,
            "updatedAt": "2025-03-24T08:08:16Z"
        },
        {
            "accountId": 117,
            "amount": "12.950000",
            "clearerId": "paypal-checkout",
            "createdAt": "2025-03-24T13:15:25Z",
            "currency": "EUR",
            "id": "27V62418RL450684B",
            "orderId": "1688",
            "payedAt": "2025-03-24T13:15:25Z",
            "paymentMethod": "paypalCheckout",
            "paymentStatus": 1,
            "refundedAt": "0000-00-00T00:00:00Z",
            "sessionId": "3bd02f1620965216cefd91eee7c55dba5bf3d036386f40a519304fdeef94dc21",
            "subshopId": "deutsch",
            "testOrder": 0,
            "updatedAt": "2025-03-24T13:15:25Z"
        }
    ],
    "nextPageToken": "MQ",
    "totalCount": 2
}

Filterfelder

id, createdAt, payedAt, refundedAt, paymentStatus, subshopId, accountId, testOrder

Sortierfelder

id, createdAt, updatedAt, payedAt, refundedAt, paymentStatus, subshopId, accountId, orderId, sessionId, clearerId, currency, amount, paymentMethod, testOrder

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Transaktionen.
400 Bad Request	”invalidValue”
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.
400 Bad Request	”invalidCharacters”	size ist keine Ganzzahl. Ein Filterwert ist ungültig.
400 Bad Request	”syntaxError”	sort enthält mehr als einen oder keinen ”:“.
503 Service Unavailable	”internalError”	Das Lesen von Daten ist fehlgeschlagen.

GET transactions/

Diese Methode lädt die vollständigen Details einer einzelnen Transaktion basierend auf ihrer eindeutigen ID.

Sie können damit Transaktionsinformationen wie Zahlungsstatus, Adressen sowie Zusatzdaten abrufen.

Damit die Methode verwendet werden kann, müssen die erforderlichen Berechtigungen zum Lesen von Transaktionen vorhanden sein.

Beispiel

http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G

Antwort

{
    "accountId": 4,
    "amount": "12.950000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-24T08:08:16Z",
    "currency": "EUR",
    "id": "86T19828EK510721G",
    "orderId": "1553",
    "payedAt": "2025-03-24T08:08:16Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 1,
    "refundedAt": "0000-00-00T00:00:00Z",
    "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
    "subshopId": "deutsch",
    "testOrder": 0,
    "updatedAt": "2025-03-24T08:08:16Z"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Transaktionen.
404 Not Found		Die Transaktion wurde nicht gefunden.
400 Bad Request	”missing”	id fehlt.

PUT transactions//refresh

Mit dieser Methode wird der aktuelle Status einer vorhandenen Transaktion beim angebundenen Zahlungsdienstleister abgefragt und aktualisiert. Sie kann verwendet werden, wenn der Status einer Transaktion nicht mehr aktuell erscheint (z. B. bei ausstehenden Zahlungen oder Rückerstattungen).

Es müssen entsprechende Berechtigungen zum Schreiben von Transaktionsdaten vorhanden sein.

Beispiel

http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G/refresh

Antwort

{
    "accountId": 4,
    "amount": "12.950000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-24T08:08:16Z",
    "currency": "EUR",
    "id": "86T19828EK510721G",
    "orderId": "1553",
    "payedAt": "2025-03-24T08:08:16Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 1,
    "refundedAt": "0000-00-00T00:00:00Z",
    "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
    "subshopId": "deutsch",
    "testOrder": 0,
    "updatedAt": "2025-03-24T08:08:16Z"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Transaktionen.
400 Bad Request	”missing”	id fehlt.
404 Not Found		Die Daten der Transaktion konnten nach der Aktualisierung nicht gelesen werden.

PUT transactions//cancel

Mit dieser Methode wird versucht, eine Transaktion beim angebundenen Zahlungsdienstleister zu stornieren. Dies ist beispielsweise bei noch nicht abgeschlossenen oder fehlerhaften Zahlungen erforderlich.

Nach erfolgreicher Stornierung wird die aktualisierte Transaktion zurückgegeben.

Es müssen entsprechende Berechtigungen zum Schreiben von Transaktionen vorhanden sein.

Beispiel

http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G/cancel

Antwort

{
    "accountId": 4,
    "amount": "12.950000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-24T08:08:16Z",
    "currency": "EUR",
    "id": "86T19828EK510721G",
    "orderId": "1553",
    "payedAt": "2025-03-24T08:08:16Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 4,
    "refundedAt": "2025-04-24T10:30:00Z",
    "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
    "subshopId": "deutsch",
    "testOrder": 0,
    "updatedAt": "2025-04-24T10:30:00Z"
}

Nach erfolgreicher Stornierung wird der paymentStatus in der Regel auf 4 (Canceled) oder 6 (CanceledByAdmin) gesetzt. Der genaue Wert hängt vom Zahlungsdienstleister ab.

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Transaktionen.
404 Not Found		Die Transaktion wurde nicht gefunden. Die Daten der Transaktion konnten nach der Aktualisierung nicht gelesen werden.
400 Bad Request	”missing”	id fehlt.
503 Service Unavailable	”internalError”	Das Abbrechen ist fehlgeschlagen. Die Transaktion konnte nach der Aktualisierung nicht geladen werden.

PUT transactions//refund

Diese Methode löst eine Rückerstattung eines bereits bezahlten Betrags bei der angegebenen Transaktion aus.

Optional kann ein Teilbetrag (amount) und ein Rückgabegrund (reason) im Request Body übergeben werden. Wird kein Betrag angegeben, wird der gesamte Betrag erstattet. Nach erfolgreicher Rückerstattung wird die aktualisierte Transaktion zurückgegeben.

Für diese Aktion müssen entsprechende Berechtigungen zum Schreiben von Transaktionen vorhanden sein.

Beispiel

http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G/refund

Request Body

{
    "amount": "5",
    "reason": "Mein Grund"
}

Antwort

{
    "accountId": 2,
    "amount": "30.990000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-18T14:37:51Z",
    "currency": "EUR",
    "id": "1MV26007FY832013B",
    "orderId": "1330",
    "payedAt": "2025-03-18T14:37:51Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 7,
    "refundedAt": "2025-03-18T15:16:59Z",
    "sessionId": "ba068bace905c4ce9a32219e2170af2f69a959dd6a59d7b9909718885d259c4a",
    "subshopId": "deutsch",
    "testOrder": 0,
    "updatedAt": "2025-03-18T15:16:59Z"
}

Nach erfolgreicher Rückerstattung wird der paymentStatus auf 7 (Refunded) oder 8 (RefundedPartially) gesetzt, je nachdem ob der gesamte oder ein Teilbetrag erstattet wurde.

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Transaktionen.
400 Bad Request		Request body konnte nicht geladen werden.
404 Not Found		Die Transaktion wurde nicht gefunden. Die Daten der Transaktion konnten nach der Aktualisierung nicht gelesen werden.
400 Bad Request	”missing”	id fehlt.
400 Bad Request	”invalidValue”	amount ist ≤ 0 oder größer als der Betrag der Transaktion.
400 Bad Request	”invalidFormat”	amount oder reason ist kein String.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request Body übergeben.
503 Service Unavailable	”internalError”	Das Erstatten ist fehlgeschlagen. Die Transaktion konnte nach der Aktualisierung nicht geladen werden.

PUT transactions//capture

Diese Methode dient dazu, eine reservierte Transaktion zu erfassen, d. h. der ursprünglich nur vorgemerkte Betrag wird final vom Kundenkonto abgebucht.

Diese Funktion wird vor allem bei Zahlungsanbietern benötigt, bei denen eine Autorisierung und eine separate Erfassung erforderlich sind (z. B. Kreditkarte). Die aktualisierte Transaktion wird im Anschluss zurückgegeben.

Für diese Aktion müssen entsprechende Berechtigungen zum Schreiben von Transaktionen vorhanden sein.

Beispiel

http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G/capture

Antwort

{
    "accountId": 4,
    "amount": "12.950000",
    "clearerId": "paypal-checkout",
    "createdAt": "2025-03-24T08:08:16Z",
    "currency": "EUR",
    "id": "86T19828EK510721G",
    "orderId": "1553",
    "payedAt": "2025-04-24T11:05:00Z",
    "paymentMethod": "paypalCheckout",
    "paymentStatus": 2,
    "refundedAt": "0000-00-00T00:00:00Z",
    "sessionId": "3a8a5e026ce14ec37b906654e27f5551aadae6049e4050405b4fc5b295d4db6e",
    "subshopId": "deutsch",
    "testOrder": 0,
    "updatedAt": "2025-04-24T11:05:00Z"
}

Nach erfolgreicher Erfassung wird der paymentStatus in der Regel auf 1 (Finished) gesetzt. Bei einem Fehler wird er auf 2 (Error) gesetzt.

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Transaktionen.
404 Not Found		Die Transaktion wurde nicht gefunden. Die Daten der Transaktion konnten nach der Aktualisierung nicht gelesen werden.
400 Bad Request	”missing”	id fehlt.
503 Service Unavailable	”internalError”	Das Erfassen ist fehlgeschlagen. Die Transaktion konnte nach der Aktualisierung nicht geladen werden.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.