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.

Inhaltsverzeichnis:

1 1. Unterstützte Methoden
2 2. Datenfelder einer Transaktion
3 3. Methoden für die Transaktionen
4 4. Support

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	DELETE	GET	POST	PUT

Befehl/Info	Endpunkte	DELETE	GET	POST	PUT
Transaktionen	transactions/

2. Datenfelder einer Transaktion

Name	Typ	Bedeutung

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 = Pending` `1 = Finished` `2 = Error` `3 = Redirected` `4 = Canceled` `5 = Rejected` `6 = CanceledByAdmin` `7 = Refunded` `8 = 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).

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",
    "updatedAt": "2025-03-20T15:20:26Z"
}

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

3.1 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",
            "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",
            "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

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"	`size` ∉ [1;300] `sort` ∉ {"asc", "desc"} `pageToken` ist keine Zahl oder kleiner als 0.
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.

3.2 GET transactions/{id}

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",
    "updatedAt": "2025-03-24T08:08:16Z"
}

Fehlercodes:

Fehler	Typ	Grund

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.
503 Service Unavailable	"internalError"	Die Transaktion konnte nicht geladen werden.

3.3 PUT transactions/{id}/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",
    "updatedAt": "2025-03-24T08:08:16Z"
}

Fehlercodes:

Fehler	Typ	Grund

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.
503 Service Unavailable	"internalError"	Die Transaktion konnte nach der Aktualisierung nicht geladen werden.
404 Not Found		Die Daten der Transaktion konnten nach der Aktualisierung nicht gelesen werden.

3.4 PUT transactions/{id}/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"
}

Hinweis: Der paymentStatus kann je nach Umsetzung im Shop z. B. auf einen Wert für „storniert“ gesetzt werden (4).

Fehlercodes:

Fehler	Typ	Grund

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.

3.5 PUT transactions/{id}/refund

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

Der zu erstattende Betrag kann ganz oder teilweise erfolgen und muss im Request übergeben werden. Zusätzlich kann ein optionaler Rückgabegrund angegeben werden. 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",
    "updatedAt": "2025-03-18T15:16:59Z"
}

Hinweis: Der Wert von paymentStatus kann abhängig von der Implementierung im Shop-System auf einen Status wie „erstattet“ (7 oder 8) gesetzt werden.

Fehlercodes:

Fehler	Typ	Grund

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.
503 Service Unavailable	"internalError"	Das Abbrechen ist fehlgeschlagen. \| Die Transaktion konnte nach der Aktualisierung nicht geladen werden.

3.6 PUT transactions/{id}/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"
}

Hinweis: Der Wert paymentStatus wird typischerweise auf einen Status wie „erfasst“ (1) oder “Fehler” (2) gesetzt.

Fehlercodes:

Fehler	Typ	Grund

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.

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

WEBSALE Dokumentation

API-Referenz Transaktionen

Inhaltsverzeichnis:

1. Unterstützte Methoden

2. Datenfelder einer Transaktion

Beispiel:

3. Methoden für die Transaktionen

3.1 GET transactions

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.2 GET transactions/{id}

Beispiel:

Antwort:

Fehlercodes:

3.3 PUT transactions/{id}/refresh

Beispiel:

Antwort:

Fehlercodes:

3.4 PUT transactions/{id}/cancel

Beispiel:

Antwort:

Fehlercodes:

3.5 PUT transactions/{id}/refund

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.6 PUT transactions/{id}/capture

Beispiel:

Antwort:

Fehlercodes:

4. Support