> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# API-Referenz Transaktionen

> Zahlungstransaktionen über die Admin Interface API abrufen, Status aktualisieren sowie Erfassung, Rückerstattung oder Abbruch auslösen.

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**](https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3058532986/API-Referenz+Templatekompilierung#3-methhttps-websaleatlassiannet-wiki-spaces-wsdoku-pages-3142778881-api-referenztransaktionen3-methoden-für-die-transaktionen) | transactions/ | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="check" /> |

## 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).  <br />Mögliche Werte:  <br />`0 = Pending`<br />`1 = Finished`<br />`2 = Error`<br />`3 = Redirected`<br />`4 = Canceled`<br />`5 = Rejected`<br />`6 = CanceledByAdmin`<br />`7 = Refunded`<br />`8 = RefundedPartially` |
| `refundedAt`     | String  | Zeitpunkt der Rückerstattung (falls erfolgt).                                                                                                                                                                                                                                           |
| `sandboxPayment` | Boolean | Gibt an, ob die Transkation mit einer Zahlungsart ausgeführt wurde, die im Sandbox-/-Testmodus konfiguriert war.<br />Mögliche Werte:<br />`true` = Zahlungsart im Sandbox-Modus<br />`false` = Zahlungsart im Live-Modus                                                               |
| `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

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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",
    "sandboxPayment": 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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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",
            "sandboxPayment": 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",
            "sandboxPayment": 0,
            "updatedAt": "2025-03-24T13:15:25Z"
        }
    ],
    "nextPageToken": "MQ",
    "totalCount": 2
}
```

#### Filterfelder

`id`, `createdAt`, `payedAt`, `refundedAt`, `paymentStatus`, `subshopId`, `accountId`, `sandboxPayment`

#### Sortierfelder

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

#### Fehlercodes

| **Fehler**              | **Typ**             | **Grund**                                                                      |
| ----------------------- | ------------------- | ------------------------------------------------------------------------------ |
| 401 Unauthorized        |                     | Nicht autorisiert: Sie sind nicht angemeldet.                                  |
| 403 Forbidden           |                     | Sie 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.<br />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/\{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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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",
    "sandboxPayment": 0,
    "updatedAt": "2025-03-24T08:08:16Z"
}
```

#### Fehlercodes

| **Fehler**       | **Typ**   | **Grund**                                                                      |
| ---------------- | --------- | ------------------------------------------------------------------------------ |
| 401 Unauthorized |           | Nicht autorisiert: Sie sind nicht angemeldet.                                  |
| 403 Forbidden    |           | Sie 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/\{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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G/refresh
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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",
    "sandboxPayment": 0,
    "updatedAt": "2025-03-24T08:08:16Z"
}
```

#### Fehlercodes

| **Fehler**       | **Typ**   | **Grund**                                                                          |
| ---------------- | --------- | ---------------------------------------------------------------------------------- |
| 401 Unauthorized |           | Nicht autorisiert: Sie sind nicht angemeldet.                                      |
| 403 Forbidden    |           | Sie 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/\{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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G/cancel
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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",
    "sandboxPayment": 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.                                                                                |
| 403 Forbidden           |                 | Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Transaktionen.                                           |
| 404 Not Found           |                 | Die Transaktion wurde nicht gefunden. <br /> 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. <br /> Die Transaktion konnte nach der Aktualisierung nicht geladen werden.                |

### PUT transactions/\{id}/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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G/refund
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "amount": "5",
    "reason": "Mein Grund"
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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",
    "sandboxPayment": 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.                                                                                |
| 403 Forbidden           |                    | Sie 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. <br /> 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. <br /> Die Transaktion konnte nach der Aktualisierung nicht geladen werden.                |

### 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
http://www.<ihr-shop>.de/admin/api/v1/transactions/86T19828EK510721G/capture
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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",
    "sandboxPayment": 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.                                                                                |
| 403 Forbidden           |                 | Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Transaktionen.                                           |
| 404 Not Found           |                 | Die Transaktion wurde nicht gefunden. <br /> 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. <br /> 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](https://websale.atlassian.net/servicedesk/customer/portal/6)

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