API-Referenz PayPal-Onboarding - WEBSALE Dokumentation

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

PayPal-Onboarding-Vorgang

Datenfelder eines Eintrags

Name	Typ	Verwendung
id	String	Tracking-ID des Onboarding-Vorgangs. Sie 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`). Sie 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. Er wird beim Anlegen festgelegt, bleibt am Eintrag gespeichert und bestimmt alle weiteren Abrufe bei PayPal. Im Admin Interface erscheint er in Liste und Detailansicht als Modus mit den Werten Live und Sandbox. Mögliche Werte: `0` = Unknown `1` = Production (Live) `2` = Test (Sandbox)

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

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 die 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 (siehe PUT payment/paypalonboarding/{id}/checkstatus). 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
}

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.
403 Forbidden		Sie 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

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
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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

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
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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 setzt sich aus Zeitstempel, Shop-ID und einer fortlaufenden Nummer zusammen. Den Betriebsmodus der neuen Verbindung geben Sie im Feld mode des Request Body an. Er bleibt am Eintrag gespeichert. Als Ergebnis wird die erzeugte { "trackingId": "…" } zurückgegeben. Die Zugangsdaten für den gewählten Modus entnimmt der Shop der Konfiguration payment.payPalCheckout. Sind dort für diesen Modus keine Zugangsdaten hinterlegt, wird keine Verbindung angelegt. Im Admin-Interface führt die Schaltfläche zum Anlegen zunächst auf die Seite Neues Konto verbinden. Dort wählen Sie unter Modus auswählen zwischen Live-Modus und Sandbox-Modus. Erst danach legt das Admin-Interface den Eintrag an und leitet Sie zu PayPal weiter. 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

{
    "mode": "sandbox"
}

Body-Parameter

Parameter	Typ	Beschreibung
`mode`	string	Betriebsmodus der neuen Verbindung. `live`: Echtbetrieb `sandbox`: Testbetrieb

Antwort

{
    "trackingId": "1757929355_myshop_8"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Erstellen von PayPal-Onboarding-Daten.
400 Bad Request		Request body konnte nicht geladen werden. Das Anlegen von Daten ist fehlgeschlagen.
404 Not Found		Die Daten konnten nach dem Anlegen nicht geladen werden.

PUT payment/paypalonboarding/{id}

Über diesen Endpunkt kann ein Onboarding-Eintrag aktualisiert werden. Alternativ kann die PayPal-Action-URL für den Start des Onboardings abgefragt werden, sofern noch keine Händler-ID vorliegt. Ohne Angabe von merchantIdInPayPal liefert der Endpunkt die Aktions-URL ({ "acturl": "…" }). Mit merchantIdInPayPal wird der Konto-/Integrationsstatus bei PayPal abgefragt. Relevante Felder (beispielsweise E-Mail-Bestätigung, Zahlungsfähigkeit und 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 diese angegeben wird, wird der Account-Status bei PayPal abgefragt und der Eintrag entsprechend aktualisiert. Andernfalls wird die Aktions-URL zurückgegeben.

Beispiel

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

Antwort, wenn keine `merchantIdInPayPal` übergeben wurde

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

Antwort, wenn eine `merchantIdInPayPal` übergeben wurde

{
    "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.
403 Forbidden		Sie 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

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

{
    "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.
403 Forbidden		Sie 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}

Über diesen Endpunkt kann ein vorhandener Onboarding-Eintrag anhand seiner ID als gelöscht markiert werden (Soft-Delete). Der Eintrag verbleibt in der Datenbank, wird jedoch mit einem Löschzeitstempel versehen und ist nicht mehr in der Liste sichtbar. 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
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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 Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Unterstützte Methoden

​PayPal-Onboarding-Vorgang

​Datenfelder eines Eintrags

​Beispiel

​Methoden für PayPal-Onboarding

​GET payment/paypalonboarding

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET payment/paypalonboarding/{id}

​Beispiel

​Antwort

​Fehlercodes

​GET payment/paypalonboarding/{id}/url

​Beispiel

​Antwort

​Fehlercodes

​POST payment/paypalonboarding

​Beispiel

​Request Body

​Body-Parameter

​Antwort

​Fehlercodes

​PUT payment/paypalonboarding/{id}

​Query-Parameter

​Beispiel

​Antwort, wenn keine merchantIdInPayPal übergeben wurde

​Antwort, wenn eine merchantIdInPayPal übergeben wurde

​Fehlercodes

​PUT payment/paypalonboarding/{id}/checkstatus

​Query-Parameter

​Beispiel

​Antwort

​Fehlercodes

​DELETE payment/paypalonboarding/{id}

​Beispiel

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

PayPal-Onboarding-Vorgang

Datenfelder eines Eintrags

Beispiel

Methoden für PayPal-Onboarding

GET payment/paypalonboarding

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET payment/paypalonboarding/{id}

Beispiel

Antwort

Fehlercodes

GET payment/paypalonboarding/{id}/url

Beispiel

Antwort

Fehlercodes

POST payment/paypalonboarding

Beispiel

Request Body

Body-Parameter

Antwort

Fehlercodes

PUT payment/paypalonboarding/{id}

Query-Parameter

Beispiel

Antwort, wenn keine `merchantIdInPayPal` übergeben wurde

Antwort, wenn eine `merchantIdInPayPal` übergeben wurde

Fehlercodes

PUT payment/paypalonboarding/{id}/checkstatus

Query-Parameter

Beispiel

Antwort

Fehlercodes

DELETE payment/paypalonboarding/{id}

Beispiel

Antwort

Fehlercodes

Support