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

Inhaltsverzeichnis:

1 1. Unterstützte Methoden
2 2. PayPal-Onboarding-Vorgang
3 3. Methoden für PayPal-Onboarding
4 4. Support

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE

Befehl/Info

Endpunkte

GET

POST

PUT

DELETE

PayPal-Onboarding

payment/

paypalonboarding

2. PayPal-Onboarding-Vorgang

Datenfelder eines Eintrags:

Name	Typ	Verwendung

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:

{
    "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"
}

3. Methoden für PayPal-Onboarding

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

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

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

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding?size=100

Antwort:

{
    "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
}

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 PayPal-Onboarding-Daten.
400 Bad Request	"invalidValue"	"stage" ist ungültig. `size` ∉ [1;300] `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 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:

https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757660073_myshop_1

Antwort:

{
    "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

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.

3.3 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 sind Schreibberechtigungen erforderlich.

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

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757925806_myshop_2/url

Antwort:

{
    "action_url": "https://www.sandbox.paypal.com/bizsignup/partner/entry?referralToken=NjlhMjM3ODctMDZjMy00MjZkLWJjMGQtMTU1YzdiZjRiMjQwMm5xRk9weFNtYjNDRmpYb2g3b25RdzVqeWtacEVCSnVTZzRaL3NsMkdXRT12Mg=="
}

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 PayPal-Onboarding-Daten.
404 Not Found		Die URL konnte nicht generiert werden. Details sind in Logs zu finden.

3.4 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:

https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding

Request Body:

{}

Antwort:

{
    "trackingId": "1757929355_myshop_8"
}

Fehlercodes:

Fehler	Typ	Grund

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.

3.5 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 ein leeres JSON {}.

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

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757927249_myshop_6

Request Body:

{}

Antwort, wenn keine `merchantIdInPayPal` übergeben wurde:

{
    "action_url": "https://www.sandbox.paypal.com/bizsignup/partner/entry?referralToken=YjY3Nzk2ODQtYTQwOS00MjhiLWFhYWUtMzc1YjcyOTMwZmViVkN0MXA2RlFxTDhZTnRxWGxnL0s4Mmpick5udERFUmNFZ3NJZVlmNDZpUT12Mg=="
}

Antwort, wenn eine `merchantIdInPayPal` übergeben wurde:

{}

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 PayPal-Onboarding-Daten.
400 Bad Request		Das Aktualisieren von Daten ist fehlgeschlagen.
404 Not Found		Pay-Pal hat keine Daten geliefert.

3.6 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. Dieser Handler führt keine explizite Berechtigungsprüfung aus und wird auch automatisch verarbeitet, wenn eine Listenabfrage mit PPact=finish eingeht.

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

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/storage/keys

Request Body:

{}

Antwort:

{
    "accountType": "",
    "activePayments": "",
    "consentStatus": false,
    "createdAt": "2025-09-15T09:07:29Z",
    "deletedAt": "",
    "email": "",
    "emailConfirmed": false,
    "id": "1757927249_myshop_6",
    "merchantId": "",
    "mode": 2,
    "permissionsGranted": false,
    "rawResponse": "",
    "shop": "myshop",
    "status": 1,
    "updatedAt": "2025-09-15T09:07:29Z"
}

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 PayPal-Onboarding-Daten.
400 Bad Request		Das Aktualisieren von Daten ist fehlgeschlagen.
404 Not Found		Pay-Pal hat keine Daten geliefert.

3.7 DELETE payment/paypalonboarding/{id}

Mit diesem Endpunkt wird ein vorhandenes Onboarding-Eintrag anhand seiner ID dauerhaft entfernt.

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:

https://www.<ihr-shop>.de/admin/api/v1/payment/paypalonboarding/1757929355_myshop_8

Antwort:

{
    "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

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.

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.

API-Referenz PayPal-Onboarding

Inhaltsverzeichnis:

1. Unterstützte Methoden

2. PayPal-Onboarding-Vorgang

Datenfelder eines Eintrags:

Beispiel:

3. Methoden für PayPal-Onboarding

3.1 GET payment/paypalonboarding

Beispiel:

Antwort:

Fehlercodes:

3.2 GET payment/paypalonboarding/{id}

Beispiel:

Antwort:

Fehlercodes:

3.3 GET payment/paypalonboarding/{id}/url

Beispiel:

Antwort:

Fehlercodes:

3.4 POST payment/paypalonboarding

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.5 PUT payment/paypalonboarding/{id}

Beispiel:

Request Body:

Antwort, wenn keine merchantIdInPayPal übergeben wurde:

Antwort, wenn eine merchantIdInPayPal übergeben wurde:

Fehlercodes:

3.6 PUT payment/paypalonboarding/{id}/checkstatus

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.7 DELETE payment/paypalonboarding/{id}

Beispiel:

Antwort:

Fehlercodes:

4. Support

Antwort, wenn keine `merchantIdInPayPal` übergeben wurde:

Antwort, wenn eine `merchantIdInPayPal` übergeben wurde: