API reference PayPal onboarding - WEBSALE Dokumentation

The payment/paypalonboarding endpoint provides a REST interface for managing PayPal onboarding processes in the shop system. It supports creating, retrieving, updating and deleting onboarding entries, generating the PayPal action URL required for the flow, and processing the PayPal return (return URL).

Supported methods

List of all supported methods.

Command/Info	Endpoints	GET	POST	PUT	DELETE
PayPal onboarding	payment/paypalonboarding

PayPal onboarding process

Data fields of an entry

Name	Type	Usage
id	String	Tracking ID of the onboarding process. It is generated from `<unixTimestamp>_<shopId>_<sequentialId>` and serves as the primary key.
shop	String	Shop identifier to which the entry is assigned.
status	Integer	Current onboarding status, derived from email confirmation, payment capability and response validity, among other things. Possible values: `0` = Unknown (not determined) `1` = NoConnection (no valid PayPal response/connection) `2` = Success (prerequisites met) `3` = EmailNotConfirmed (email not confirmed) `4` = PaymentNotReceivable (account cannot (yet) receive payments) `5` = InvalidResponse (incomplete/unexpected response)
merchantId	String	Merchant ID at PayPal (`merchantIdInPayPal`). It uniquely identifies the PayPal account.
email	String	Primary PayPal email of the merchant account (`primary_email`).
permissionsGranted	Boolean	Indicates whether the required OAuth permissions/scopes were granted (return param `permissionGranted` or from PayPal status).
emailConfirmed	Boolean	Indicates whether the primary email is confirmed at PayPal (`primary_email_confirmed`).
consentStatus	Boolean	Indicates whether legal consents have been granted (return param `consentStatus`).
accountType	String	Account state reported by the PayPal return.
updatedAt	String	Time of the last update of the entry (ISO 8601 format, UTC).
createdAt	String	Time of creation (ISO 8601 format, UTC).
deletedAt	String	Time of deletion (ISO 8601 format, UTC). Empty if the entry is active.
rawResponse	String	Complete, unfiltered response of the PayPal Account Status API (as JSON string) for tracking/debugging.
activePayments	String	Enabled payment methods.
mode	Integer	Operating mode of the entry. It is set on creation, remains stored with the entry and determines all further requests to PayPal. In the admin interface, it appears in the list and detail view as Mode with the values Live and Sandbox. Possible values: `0` = Unknown `1` = Production (Live) `2` = Test (Sandbox)

Example

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

Methods for PayPal onboarding

This section describes the endpoints for managing individual PayPal onboarding entries.

GET payment/paypalonboarding

This endpoint can be used to load a list of existing onboarding entries for the current shop. The search and filter parameters from the request are taken into account and limited to deleted=false. If the request contains the indication of a PayPal return (PPact=finish), the return data is processed first (see PUT payment/paypalonboarding/{id}/checkstatus). To use it, read permissions for PayPal onboarding data are required.

Example

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

Response

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

Filter fields

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

Sort fields

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read PayPal onboarding data.
400 Bad Request	”invalidValue”	`size` ∉ [1;300] `pageToken` is not a number or is less than 0. The sort direction in `sort` is neither “asc” nor “desc”.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
503 Service Unavailable	”internalError”	Reading data failed.

GET payment/paypalonboarding/{id}

This endpoint can be used to retrieve a single onboarding entry by its ID for the current shop. To use this endpoint, read permissions for PayPal onboarding data are required.

Example

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read PayPal onboarding data.
404 Not Found		The data was not found.

GET payment/paypalonboarding/{id}/url

This endpoint can be used to directly request the current PayPal action URL for a tracking ID. The URL is intended to start the PayPal onboarding flow and contains the configured return URL of the shop. To use this endpoint, write permissions for PayPal onboarding data are required.

Example

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write PayPal onboarding data.
404 Not Found		The URL could not be generated. Details can be found in the logs.

POST payment/paypalonboarding

This endpoint can be used to create a new onboarding entry. The tracking ID is made up of a timestamp, shop ID and a sequential number. You specify the operating mode of the new connection in the mode field of the request body. It remains stored with the entry. The generated { "trackingId": "…" } is returned as the result. The shop takes the credentials for the selected mode from the payment.payPalCheckout configuration. If no credentials are stored there for this mode, no connection is created. In the admin interface, the button for creating an entry first leads to the Connect new account page. There, under Select mode, you choose between Live mode and Sandbox mode. Only then does the admin interface create the entry and redirect you to PayPal. To use this endpoint, create permissions for PayPal onboarding data are required.

Example

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

Request body

{
    "mode": "sandbox"
}

Body parameters

Parameter	Type	Description
`mode`	string	Operating mode of the new connection. `live`: live operation `sandbox`: test operation

Response

{
    "trackingId": "1757929355_myshop_8"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create PayPal onboarding data.
400 Bad Request		Request body could not be loaded. Creating data failed.
404 Not Found		The data could not be loaded after creation.

PUT payment/paypalonboarding/{id}

This endpoint can be used to update an onboarding entry. Alternatively, the PayPal action URL for starting the onboarding can be queried, provided no merchant ID is available yet. Without specifying merchantIdInPayPal, the endpoint returns the action URL ({ "acturl": "…" }). With merchantIdInPayPal, the account/integration status is queried at PayPal. Relevant fields (e.g. email confirmation, payment capability and scopes) are taken over and a corresponding internal status is set. The result is the updated entry as JSON. To use this endpoint, write permissions for PayPal onboarding data are required.

Query parameters

merchantIdInPayPal: (optional) PayPal merchant ID. If it is specified, the account status is queried at PayPal and the entry is updated accordingly. Otherwise, the action URL is returned.

Example

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

Response when no `merchantIdInPayPal` was provided

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

Response when a `merchantIdInPayPal` was provided

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write PayPal onboarding data.
400 Bad Request		Updating data failed.
404 Not Found		The action URL could not be determined or PayPal did not return any account data.

PUT payment/paypalonboarding/{id}/checkstatus

This endpoint receives return data from PayPal (return URL), logs it and assigns it to the corresponding onboarding entry. The provided query parameters are stored. The valid account status is then queried via the PayPal API, persisted in the entry, and the updated entry is returned as JSON. To use this endpoint, write permissions for PayPal onboarding data are required.

Query parameters

commonid: shop ID
merchantId: tracking ID of the entry
merchantIdInPayPal: PayPal merchant ID
accountStatus: account status
consentStatus: consent status (“true”/“false”)
isEmailConfirmed: email confirmed (“true”/“false”)
permissionGranted: permissions granted (“true”/“false”)

Example

https://www.<your-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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write PayPal onboarding data.
400 Bad Request		Updating data failed.
404 Not Found		PayPal did not return any data.

DELETE payment/paypalonboarding/{id}

This endpoint can be used to mark an existing onboarding entry as deleted by its ID (soft delete). The entry remains in the database, but is given a deletion timestamp and is no longer visible in the list. The request returns the updated list in the response body. To use this endpoint, delete permissions for PayPal onboarding data are required.

Example

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete PayPal onboarding data.
404 Not Found		No data was found.

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.

​Supported methods

​PayPal onboarding process

​Data fields of an entry

​Example

​Methods for PayPal onboarding

​GET payment/paypalonboarding

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET payment/paypalonboarding/{id}

​Example

​Response

​Error codes

​GET payment/paypalonboarding/{id}/url

​Example

​Response

​Error codes

​POST payment/paypalonboarding

​Example

​Request body

​Body parameters

​Response

​Error codes

​PUT payment/paypalonboarding/{id}

​Query parameters

​Example

​Response when no merchantIdInPayPal was provided

​Response when a merchantIdInPayPal was provided

​Error codes

​PUT payment/paypalonboarding/{id}/checkstatus

​Query parameters

​Example

​Response

​Error codes

​DELETE payment/paypalonboarding/{id}

​Example

​Response

​Error codes

​Support

Supported methods

PayPal onboarding process

Data fields of an entry

Example

Methods for PayPal onboarding

GET payment/paypalonboarding

Example

Response

Filter fields

Sort fields

Error codes

GET payment/paypalonboarding/{id}

Example

Response

Error codes

GET payment/paypalonboarding/{id}/url

Example

Response

Error codes

POST payment/paypalonboarding

Example

Request body

Body parameters

Response

Error codes

PUT payment/paypalonboarding/{id}

Query parameters

Example

Response when no `merchantIdInPayPal` was provided

Response when a `merchantIdInPayPal` was provided

Error codes

PUT payment/paypalonboarding/{id}/checkstatus

Query parameters

Example

Response

Error codes

DELETE payment/paypalonboarding/{id}

Example

Response

Error codes

Support