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

> PayPal-Onboarding-Vorgänge über die Admin Interface API anlegen, abrufen, aktualisieren, löschen sowie Action- und Return-URLs erzeugen.

Der Endpunkt `payment/paypalonboarding` stellt eine REST-Schnittstelle bereit, um PayPal-Onboarding-Vorgänge im Shop-System zu verwalten. Er unterstützt das Anlegen, Abrufen, Aktualisieren und Löschen von Onboarding-Einträgen, das Erzeugen der für den Flow benötigten PayPal-Action-URL sowie die Verarbeitung des PayPal-Rücksprungs (Return-URL).

***

## Unterstützte Methoden

Angabe aller unterstützten Methoden.

| **Befehl/Info**       | **Endpunkte**              | **GET**               | **POST**              | **PUT**               | **DELETE**            |
| --------------------- | -------------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **PayPal-Onboarding** | payment/  paypalonboarding | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> |

## PayPal-Onboarding-Vorgang

### Datenfelder eines Eintrags

| **Name**               | **Typ** | **Verwendung**                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**                 | String  | Tracking-ID des Onboarding-Vorgangs; wird aus `<unixTimestamp>_<shopId>_<laufendeId>` generiert und dient als Primärschlüssel.                                                                                                                                                                                                                                                                                                                                       |
| **shop**               | String  | Shopkennung, der der Eintrag zugeordnet ist.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **status**             | Integer | Aktueller Onboarding-Status, abgeleitet u. a. aus E-Mail-Bestätigung, Zahlungsfähigkeit und Antwortvalidität.  Mögliche Werte:  - `0` = Unknown (nicht bestimmt) - `1` = NoConnection (keine gültige PayPal-Antwort/Verbindung) - `2` = Success (Voraussetzungen erfüllt) - `3` = EmailNotConfirmed (E-Mail nicht bestätigt) - `4` = PaymentNotReceivable (Konto kann (noch) keine Zahlungen empfangen) - `5` = InvalidResponse (unvollständige/unerwartete Antwort) |
| **merchantId**         | String  | Händler-ID bei PayPal (`merchantIdInPayPal`); identifiziert das PayPal-Konto eindeutig.                                                                                                                                                                                                                                                                                                                                                                              |
| **email**              | String  | Primäre PayPal-E-Mail des Händlerkontos (`primary_email`).                                                                                                                                                                                                                                                                                                                                                                                                           |
| **permissionsGranted** | Boolean | Gibt an, ob die nötigen OAuth-Berechtigungen/Scopes gewährt wurden (Return-Param `permissionGranted` bzw. aus PayPal-Status).                                                                                                                                                                                                                                                                                                                                        |
| **emailConfirmed**     | Boolean | Gibt an, ob die primäre E-Mail bei PayPal bestätigt ist (`primary_email_confirmed`).                                                                                                                                                                                                                                                                                                                                                                                 |
| **consentStatus**      | Boolean | Gibt an, ob rechtliche Einwilligungen erteilt wurden (Return-Param `consentStatus`).                                                                                                                                                                                                                                                                                                                                                                                 |
| **accountType**        | String  | Vom PayPal-Rücksprung gemeldeter Kontozustand.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **updatedAt**          | String  | Zeit der letzten Aktualisierung des Eintrags (ISO 8601-Format, UTC).                                                                                                                                                                                                                                                                                                                                                                                                 |
| **createdAt**          | String  | Zeitpunkt der Erstellung (ISO 8601-Format, UTC).                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **deletedAt**          | String  | Zeitpunkt der Löschung (ISO 8601-Format, UTC); leer, wenn der Eintrag aktiv ist.                                                                                                                                                                                                                                                                                                                                                                                     |
| **rawResponse**        | String  | Vollständige, ungefilterte Antwort der PayPal-Account-Status-API (als JSON-String) zur Nachverfolgung/Debugging.                                                                                                                                                                                                                                                                                                                                                     |
| **activePayments**     | String  | Freigegebene Zahlungsarten.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **mode**               | Integer | Betriebsmodus des Eintrags (aus Konfiguration ermittelt): Produktion oder Test.  Mögliche Werte:  - `0` = Unknown - `1` = Production - `2` = Test                                                                                                                                                                                                                                                                                                                    |

#### Beispiel

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "accountType": "",
    "activePayments": "",
    "consentStatus": false,
    "createdAt": "2025-09-15T09:42:35Z",
    "deletedAt": "",
    "email": "",
    "emailConfirmed": false,
    "id": "1757929355_myshop_8",
    "merchantId": "",
    "mode": 2,
    "permissionsGranted": false,
    "rawResponse": "",
    "shop": "myshop",
    "status": 1,
    "updatedAt": "2025-09-15T09:42:35Z"
}
```

## Methoden für PayPal-Onboarding

Dieser Abschnitt beschreibt die Endpunkte zur Verwaltung einzelner PayPal-Onboarding-Einträge.

### GET payment/paypalonboarding

Mit diesem Endpunkt kann eine Liste der vorhandenen Onboarding-Einträge des aktuellen Shops geladen werden.

Dabei werden Such- und Filterparameter aus der Anfrage berücksichtigt und auf `deleted=false` begrenzt. Enthält die Anfrage den Hinweis auf einen PayPal-Rücksprung (`PPact=finish`), [werden zuerst die Rücksprungdaten verarbeitet](/schnittstellen/admin-interface-api/api-referenz-paypal-onboarding).

Für die Nutzung sind Leseberechtigungen für PayPal-Onboarding-Daten erforderlich.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding?size=100
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "endReached": true,
    "items": [
        {
            "accountType": "",
            "activePayments": "",
            "consentStatus": false,
            "createdAt": "2025-09-12T06:54:33Z",
            "deletedAt": "",
            "email": "",
            "emailConfirmed": false,
            "id": "1757660073_myshop_1",
            "merchantId": "",
            "mode": 2,
            "permissionsGranted": false,
            "rawResponse": "",
            "shop": "myshop",
            "status": 1,
            "updatedAt": "2025-09-12T06:54:33Z"
        },
        {
            "accountType": "",
            "activePayments": "",
            "consentStatus": false,
            "createdAt": "2025-09-15T08:43:26Z",
            "deletedAt": "",
            "email": "",
            "emailConfirmed": false,
            "id": "1757925806_myshop_2",
            "merchantId": "",
            "mode": 2,
            "permissionsGranted": false,
            "rawResponse": "",
            "shop": "myshop",
            "status": 1,
            "updatedAt": "2025-09-15T08:43:26Z"
        }
    ],
    "nextPageToken": "MQ",
    "totalCount": 2
}
```

#### Filterfelder

`id`, `updatedAt`, `status`, `emailConfirmed`, `permissionsGranted`, `mode`, `deleted`

#### Sortierfelder

`updatedAt`, `createdAt`, `id`, `shop`, `merchantId`, `accountType`, `status`, `mode`, `emailConfirmed`, `email`, `consentStatus`, `permissionsGranted`

#### Fehlercodes

| **Fehler**              | **Typ**             | **Grund**                                                                                                                              |
| ----------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                     | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von PayPal-Onboarding-Daten. |
| 400 Bad Request         | "invalidValue"      | `size` ∉ \[1;300]  `pageToken` ist keine Zahl oder kleiner als 0.  Die Sortierrichtung in `sort` ist nicht "asc" oder "desc".          |
| 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 payment/paypalonboarding/\{id}

Mit diesem Endpunkt kann ein einzelner Onboarding-Eintrag anhand seiner ID für den aktuellen Shop abgerufen werden.

Für die Nutzung dieses Endpunkts sind Leseberechtigungen für PayPal-Onboarding-Daten erforderlich.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757660073_myshop_1
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "accountType": "",
    "activePayments": "",
    "consentStatus": false,
    "createdAt": "2025-09-12T06:54:33Z",
    "deletedAt": "",
    "email": "",
    "emailConfirmed": false,
    "id": "1757660073_myshop_1",
    "merchantId": "",
    "mode": 2,
    "permissionsGranted": false,
    "rawResponse": "",
    "shop": "myshop",
    "status": 1,
    "updatedAt": "2025-09-12T06:54:33Z"
}
```

#### Fehlercodes

| **Fehler**       | **Typ** | **Grund**                                                                                                                              |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |         | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von PayPal-Onboarding-Daten. |
| 404 Not Found    |         | Die Daten wurden nicht gefunden.                                                                                                       |

### GET payment/paypalonboarding/\{id}/url

Mit diesem Endpunkt kann die aktuelle PayPal-Action-URL zu einer Tracking-ID direkt angefordert werden.

Die URL ist für den Einstieg in den PayPal-Onboarding-Flow bestimmt und enthält die konfigurierte Return-URL des Shops.

Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für PayPal-Onboarding-Daten erforderlich.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757925806_myshop_2/url
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "action_url": "https://www.sandbox.paypal.com/bizsignup/partner/entry?referralToken=NjlhMjM3ODctMDZjMy00MjZkLWJjMGQtMTU1YzdiZjRiMjQwMm5xRk9weFNtYjNDRmpYb2g3b25RdzVqeWtacEVCSnVTZzRaL3NsMkdXRT12Mg=="
}
```

#### Fehlercodes

| **Fehler**       | **Typ** | **Grund**                                                                                                                                  |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized |         | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von PayPal-Onboarding-Daten. |
| 404 Not Found    |         | Die URL konnte nicht generiert werden. Details sind in Logs zu finden.                                                                     |

### POST payment/paypalonboarding

Mit diesem Endpunkt kann ein neuer Onboarding-Eintrag angelegt werden.

Die Tracking-ID wird aus Zeitstempel, Shop-ID und einer fortlaufenden Nummer gebildet; der Betriebsmodus (Production/Test) wird aus der Konfiguration ermittelt. Als Ergebnis wird die erzeugte `{ "trackingId": "…" }` zurückgegeben.

Für die Nutzung dieses Endpunkts sind Erstellberechtigungen für PayPal-Onboarding-Daten erforderlich.

#### Beispiel

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

#### Request Body

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "trackingId": "1757929355_myshop_8"
}
```

#### Fehlercodes

| **Fehler**       | **Typ** | **Grund**                                                                                                                                                                       |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |         | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von PayPal-Onboarding-Daten.                                      |
| 400 Bad Request  |         | Request body konnte nicht geladen werden.  In der `setupConfig` wurde kein Modus angegeben. Mögliche Werte: `"production"`, `"test"`  Das Anlegen von Daten ist fehlgeschlagen. |
| 404 Not Found    |         | Die Daten konnten nach dem Anlegen nicht geladen werden.                                                                                                                        |

### PUT payment/paypalonboarding/\{id}

Mit diesem Endpunkt kann ein Onboarding-Eintrag aktualisiert oder – falls noch keine Händler-ID vorliegt – die PayPal-Action-URL für den Start des Onboardings abgefragt werden.

Ohne `merchantIdInPayPal` liefert der Endpunkt die Aktions-URL (`{ "acturl": "…" }`). Mit `merchantIdInPayPal` wird der Konto-/Integrationsstatus bei PayPal abgefragt, relevante Felder (z. B. E-Mail-Bestätigung, Zahlungsfähigkeit, Scopes) werden übernommen und ein entsprechender interner Status gesetzt; das Ergebnis ist der aktualisierte Eintrag als JSON.

Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für PayPal-Onboarding-Daten erforderlich.

#### Query-Parameter

`merchantIdInPayPal` – (optional) PayPal-Merchant-ID. Wenn angegeben, wird der Account-Status bei PayPal abgefragt und der Eintrag aktualisiert. Wenn nicht angegeben, wird stattdessen die Aktions-URL zurückgegeben.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757927249_myshop_6
```

#### Antwort, wenn keine `merchantIdInPayPal` übergeben wurde

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "acturl": "https://www.sandbox.paypal.com/bizsignup/partner/entry?referralToken=YjY3Nzk2ODQtYTQwOS00MjhiLWFhYWUtMzc1YjcyOTMwZmViVkN0MXA2RlFxTDhZTnRxWGxnL0s4Mmpick5udERFUmNFZ3NJZVlmNDZpUT12Mg=="
}
```

#### Antwort, wenn eine `merchantIdInPayPal` übergeben wurde

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "accountType": "BUSINESS",
    "activePayments": "",
    "consentStatus": true,
    "createdAt": "2025-09-15T09:07:29Z",
    "deletedAt": "",
    "email": "merchant@example.com",
    "emailConfirmed": true,
    "id": "1757927249_myshop_6",
    "merchantId": "ABCDEF123456",
    "mode": 2,
    "permissionsGranted": true,
    "rawResponse": "{...}",
    "shop": "myshop",
    "status": 2,
    "updatedAt": "2025-09-15T10:15:00Z"
}
```

#### Fehlercodes

| **Fehler**       | **Typ** | **Grund**                                                                                                                                  |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized |         | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von PayPal-Onboarding-Daten. |
| 400 Bad Request  |         | Das Aktualisieren von Daten ist fehlgeschlagen.                                                                                            |
| 404 Not Found    |         | Die Aktions-URL konnte nicht ermittelt werden oder PayPal hat keine Account-Daten geliefert.                                               |

### PUT payment/paypalonboarding/\{id}/checkstatus

Mit diesem Endpunkt werden Rücksprungdaten von PayPal (Return-URL) entgegengenommen, protokolliert und dem zugehörigen Onboarding-Eintrag zugeordnet.

Die gelieferten Query-Parameter werden gespeichert; anschließend wird der gültige Account-Status über die PayPal-API abgefragt, im Eintrag persistiert und der aktualisierte Eintrag als JSON zurückgegeben.

Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für PayPal-Onboarding-Daten erforderlich.

#### Query-Parameter

`commonid` – Shop-ID\
`merchantId` – Tracking-ID des Eintrags\
`merchantIdInPayPal` – PayPal-Merchant-ID\
`accountStatus` – Kontostatus\
`consentStatus` – Zustimmungsstatus ("true"/"false")\
`isEmailConfirmed` – E-Mail bestätigt ("true"/"false")\
`permissionGranted` – Berechtigungen erteilt ("true"/"false")

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757927249_myshop_6/checkstatus?commonid=myshop&merchantId=1757927249_myshop_6&merchantIdInPayPal=ABCDEF123456&accountStatus=BUSINESS&consentStatus=true&isEmailConfirmed=true&permissionGranted=true
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "accountType": "BUSINESS",
    "activePayments": "",
    "consentStatus": true,
    "createdAt": "",
    "deletedAt": "",
    "email": "",
    "emailConfirmed": false,
    "id": "1757927249_myshop_6",
    "merchantId": "ABCDEF123456",
    "mode": 0,
    "permissionsGranted": true,
    "rawResponse": "{...}",
    "shop": "myshop",
    "status": 5,
    "updatedAt": ""
}
```

#### Fehlercodes

| **Fehler**       | **Typ** | **Grund**                                                                                                                                  |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized |         | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von PayPal-Onboarding-Daten. |
| 400 Bad Request  |         | Das Aktualisieren von Daten ist fehlgeschlagen.                                                                                            |
| 404 Not Found    |         | PayPal hat keine Daten geliefert.                                                                                                          |

### DELETE payment/paypalonboarding/\{id}

Mit diesem Endpunkt wird ein vorhandenes Onboarding-Eintrag anhand seiner ID als gelöscht markiert (Soft-Delete). Der Eintrag verbleibt in der Datenbank, wird jedoch mit einem Löschzeitstempel versehen und erscheint nicht mehr in der Liste.

Die Anfrage liefert die aktualisierte Liste im Response Body zurück.

Für die Nutzung dieses Endpunkts sind Löschberechtigungen für PayPal-Onboarding-Daten erforderlich.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757929355_myshop_8
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "endReached": true,
    "items": [
        {
            "accountType": "",
            "activePayments": "",
            "consentStatus": false,
            "createdAt": "2025-09-12T06:54:33Z",
            "deletedAt": "",
            "email": "",
            "emailConfirmed": false,
            "id": "1757660073_myshop_1",
            "merchantId": "",
            "mode": 2,
            "permissionsGranted": false,
            "rawResponse": "",
            "shop": "myshop",
            "status": 1,
            "updatedAt": "2025-09-12T06:54:33Z"
        },
        ...
    ],
    "nextPageToken": "Ng",
    "totalCount": 7
}
```

#### Fehlercodes

| **Fehler**       | **Typ** | **Grund**                                                                                                                                |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |         | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von PayPal-Onboarding-Daten. |
| 404 Not Found    |         | Es wurden keine Daten gefunden.                                                                                                          |

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