API-Referenz Stripe-Onboarding

Der Endpunkt payment/stripeonboarding bietet eine Schnittstelle zur Verwaltung von verbundenen Stripe-Konten für Shops. Sie ermöglicht das Erstellen, Einsehen, Aktualisieren und Löschen dieser Konten. Zusätzlich generiert die API Onboarding-Links mit Rücksprung- und Refresh-URLs. Zugriffe sind durch feingranulare Berechtigungen (Lesen/Schreiben/Erstellen/Löschen) geschützt; Antworten erfolgen als JSON.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Anfragen	payment/stripeonboarding

Stripe-Onboarding-Vorgang

Globale Parameter wie der Betriebsmodus sind in der Konfiguration payment.stripe hinterlegt.

Datenfelder eines Eintrags

Name	Typ	Verwendung
id	Integer	Interner Primärschlüssel des Onboarding-Eintrags.
accountId	String	Stripe Connected Account-ID (z. B. `acct_1S6Qs6P7aiy99C1h`).
status	Integer	Aktueller Onboarding-Status, abgeleitet u. a. aus E-Mail-Bestätigung, Zahlungsfähigkeit und Antwortvalidität. Mögliche Werte: `0` = MissingData (fehlende Pflichtangaben im Onboarding) `1` = MissingTos (Nutzungsbedingungen nicht akzeptiert) `2` = ChargesDisabled (Zahlungsannahme deaktiviert) `3` = PayoutDisabled (Auszahlungen deaktiviert) `4` = PayoutEnabled (Zahlungen & Auszahlungen aktiviert)
mode	Integer	Betriebsmodus des Eintrags (aus Konfiguration ermittelt): Produktion oder Test. Mögliche Werte: `0` = Sandbox `1` = Live
email	String	E-Mail-Adresse des Stripe-Kontos.
tosAccepted	Boolean	Gibt an, ob die Stripe-Nutzungsbedingungen akzeptiert wurden.
detailsSubmitted	Boolean	Gibt an, ob das Onboarding-Formular bei Stripe „übermittelt“ wurde (`details_submitted`).
chargesEnabled	Boolean	Gibt an, ob Zahlungen erstellt/erfasst werden dürfen.
payoutsEnabled	Boolean	Gibt an, ob Auszahlungen auf das Bankkonto freigeschaltet sind.
capabilities	Objekt	Spiegel der Stripe-Capabilities (z. B. `card_payments`, `transfers`) mit Status (`active/pending/inactive`). Detaillierte Kompetenzmatrix des Kontos.
paymentMethods	Array	Freigegebene Zahlungsarten.
businessType	String	Typ des Unternehmens laut Stripe (`individual`, `company`, `non_profit`, …). Kann leer sein, wenn noch nicht gesetzt.
createdAt	String	Zeitpunkt der Erstellung (ISO 8601-Format, UTC).
updatedAt	String	Zeit der letzten Aktualisierung des Eintrags (ISO 8601-Format, UTC).
deletedAt	String	Zeitpunkt der Löschung (ISO 8601-Format, UTC). Hinweis: Der Standardwert `1970-01-01T00:00:00.000Z` signalisiert „nicht gelöscht“.
rawResponse	Objekt	Vollständige, ungefilterte Antwort der Stripe-Account-API (als JSON-Objekt) zur Nachverfolgung/Debugging.

Beispiel

{
    "accountId": "acct_1S6Qs6P7aiy99C1h",
    "businessType": "",
    "capabilities": {},
    "chargesEnabled": false,
    "createdAt": "2025-09-12T06:54:17.000Z",
    "deletedAt": "1970-01-01T00:00:00.000Z",
    "detailsSubmitted": false,
    "email": "",
    "id": 1,
    "mode": 0,
    "paymentMethods": [
        {
            "available": false,
            "type": "alipay"
        },
        {
            "available": true,
            "type": "amazon_pay"
        },
        {
            "available": true,
            "type": "apple_pay"
        },
        ...
    ],
    "payoutsEnabled": false,
    "rawResponse": { ... },
    "status": 0,
    "tosAccepted": true,
    "updatedAt": "2025-09-12T06:54:17.000Z"
}

Beispiel von rawResponse

{
    "business_profile": {
        "annual_revenue": null,
        "estimated_worker_count": null,
        "mcc": null,
        "minority_owned_business_designation": null,
        "name": null,
        "support_address": null,
        "support_email": null,
        "support_phone": null,
        "support_url": null,
        "url": null
    },
    "business_type": null,
    "capabilities": {},
    "charges_enabled": false,
    "controller": {
        "fees": {
            "payer": "account"
        },
        "is_controller": true,
        "losses": {
            "payments": "stripe"
        },
        "requirement_collection": "stripe",
        "stripe_dashboard": {
            "type": "full"
        },
        "type": "application"
    },
    "country": "DE",
    "created": 1757660056,
    "default_currency": "eur",
    "details_submitted": false,
    "email": null,
    "external_accounts": {
        "data": [],
        "has_more": false,
        "object": "list",
        "total_count": 0,
        "url": "/v1/accounts/acct_1S6Qs6P7aiy99C1h/external_accounts"
    },
    "future_requirements": {
        "alternatives": [],
        "current_deadline": null,
        "currently_due": [],
        "disabled_reason": null,
        "errors": [],
        "eventually_due": [],
        "past_due": [],
        "pending_verification": []
    },
    "id": "acct_1S6Qs6P7aiy99C1h",
    "metadata": {},
    "object": "account",
    "payouts_enabled": false,
    "requirements": {
        "alternatives": [],
        "current_deadline": null,
        "currently_due": [
            "business_profile.product_description",
            "business_profile.support_phone",
            "business_profile.url",
            "external_account",
            "tos_acceptance.date",
            "tos_acceptance.ip"
        ],
        "disabled_reason": "requirements.past_due",
        "errors": [],
        "eventually_due": [
            "business_profile.product_description",
            "business_profile.support_phone",
            "business_profile.url",
            "external_account",
            "tos_acceptance.date",
            "tos_acceptance.ip"
        ],
        "past_due": [
            "business_profile.product_description",
            "business_profile.support_phone",
            "business_profile.url",
            "external_account",
            "tos_acceptance.date",
            "tos_acceptance.ip"
        ],
        "pending_verification": []
    },
    "settings": {
        "bacs_debit_payments": {
            "display_name": null,
            "service_user_number": null
        },
        "branding": {
            "icon": null,
            "logo": null,
            "primary_color": null,
            "secondary_color": null
        },
        "card_issuing": {
            "tos_acceptance": {
                "date": null,
                "ip": null
            }
        },
        "card_payments": {
            "decline_on": {
                "avs_failure": false,
                "cvc_failure": false
            },
            "statement_descriptor_prefix": null,
            "statement_descriptor_prefix_kana": null,
            "statement_descriptor_prefix_kanji": null
        },
        "dashboard": {
            "display_name": null,
            "timezone": "Etc/UTC"
        },
        "invoices": {
            "default_account_tax_ids": null,
            "hosted_payment_method_save": "offer"
        },
        "payments": {
            "statement_descriptor": null,
            "statement_descriptor_kana": null,
            "statement_descriptor_kanji": null
        },
        "payouts": {
            "debit_negative_balances": true,
            "schedule": {
                "delay_days": 7,
                "interval": "daily"
            },
            "statement_descriptor": null
        },
        "sepa_debit_payments": {}
    },
    "tos_acceptance": {
        "date": null
    },
    "type": "standard"
}

Methoden für Stripe-Onboarding

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

GET payment/stripeonboarding

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. Für die Nutzung sind Leseberechtigungen für Stripe-Onboarding-Daten erforderlich.

Beispiel

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

Antwort

{
    "endReached": true,
    "items": [
        {
            "accountId": "acct_1S6Qs6P7aiy99C1h",
            "businessType": "",
            "capabilities": {},
            "chargesEnabled": false,
            "createdAt": "2025-09-12T06:54:17.000Z",
            "deletedAt": "1970-01-01T00:00:00.000Z",
            "detailsSubmitted": false,
            "email": "",
            "id": 1,
            "mode": 0,
            "paymentMethods": [],
            "payoutsEnabled": false,
            "rawResponse": {},
            "status": 0,
            "tosAccepted": false,
            "updatedAt": "2025-09-12T06:54:17.000Z"
        },
        {
            "accountId": "acct_1S6Qs70EemSb0vRy",
            "businessType": "",
            "capabilities": {},
            "chargesEnabled": false,
            "createdAt": "2025-09-12T06:54:18.000Z",
            "deletedAt": "1970-01-01T00:00:00.000Z",
            "detailsSubmitted": false,
            "email": "",
            "id": 2,
            "mode": 0,
            "paymentMethods": [],
            "payoutsEnabled": false,
            "rawResponse": {},
            "status": 0,
            "tosAccepted": false,
            "updatedAt": "2025-09-12T06:54:18.000Z"
        },
        ...
    ],
    "nextPageToken": "Mw",
    "totalCount": 4
}

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 Stripe-Onboarding-Daten.
400 Bad Request	”invalidValue”	`sort`-Richtung ist ungültig (nicht “asc” oder “desc”). `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 ”:”.

GET payment/stripeonboarding/{id}

Mit diesem Endpunkt kann ein einzelner Onboarding-Eintrag anhand seiner ID geladen werden. Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Stripe-Onboarding-Daten erforderlich.

Beispiel

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

Antwort

{
    "accountId": "acct_1S6Qs6P7aiy99C1h",
    "businessType": "",
    "capabilities": {},
    "chargesEnabled": false,
    "createdAt": "2025-09-12T06:54:17.000Z",
    "deletedAt": "1970-01-01T00:00:00.000Z",
    "detailsSubmitted": false,
    "email": "",
    "id": 1,
    "mode": 0,
    "paymentMethods": [],
    "payoutsEnabled": false,
    "rawResponse": {},
    "status": 0,
    "tosAccepted": false,
    "updatedAt": "2025-09-12T06:54:17.000Z"
}

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 Stripe-Onboarding-Daten.
404 Not Found		Die Daten wurden nicht gefunden.

POST payment/stripeonboarding

Mit diesem Endpunkt wird ein verbundenes Stripe-Konto erstellt und dazu ein lokaler Onboarding-Eintrag im Modus Live oder Sandbox angelegt. Als Ergebnis wird ein Onboarding-Link (URL) zurückgegeben, über den die Einrichtung bei Stripe abgeschlossen werden kann. Für die Nutzung dieses Endpunkts sind Erstellberechtigungen für Stripe-Onboarding-Daten erforderlich.

Beispiel

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

Request Body

{}

Antwort

{
    "url": "https://connect.stripe.com/setup/s/acct_1S7cvB14358LTRqf/0LSOodpShtzK"
}

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 Stripe-Onboarding-Daten.
503 Service Unavailable	”serviceUnavailable”	Es konnte kein Stripe-Konto angelegt werden. Der Onboarding-Link konnte nicht erstellt werden.
503 Service Unavailable	”internalError”	Das Speichern von Daten in der WEBSALE-Datenbank ist fehlgeschlagen.

PUT payment/stripeonboarding/{id}

Dieser Endpunkt aktualisiert einen bestehenden Onboarding-Eintrag anhand seiner ID und unterscheidet zwei sinnvolle Anwendungsfälle über das Feld type im Request-Body:
– type = "finish": Der Eintrag wird mit dem aktuellen Zustand des verbundenen Stripe-Kontos synchronisiert. Dabei werden u. a. übermittelte Stammdaten, ToS-Annahme, Freigabe von Zahlungen und Auszahlungen geprüft und in einen verständlichen Status überführt (z. B. „fehlende Daten“, „ToS nicht bestätigt“, „Zahlungen/Auszahlungen deaktiviert“ oder „Auszahlungen aktiviert“). Zusätzlich werden E-Mail, Capabilities, die Standard-Konfiguration der Zahlungsarten und die unveränderte Rohantwort gespeichert. Das Ergebnis ist der aktualisierte Eintrag als JSON.
– type = "refresh": Es wird ein neuer Onboarding-Link erzeugt, damit der Händler die Einrichtung bei Stripe nahtlos fortsetzen kann (z. B. nach einer Unterbrechung oder wenn weitere Angaben nötig sind). Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Stripe-Onboarding-Daten erforderlich.

Beispiel

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

Request Body

{
    "type": "finish"
}

Antwort, wenn `type` gleich `"finish"` gilt

{
    "accountId": "acct_1S7cvB14358LTRqf",
    "businessType": "",
    "capabilities": {},
    "chargesEnabled": false,
    "createdAt": "2025-09-15T13:58:24.000Z",
    "deletedAt": "1970-01-01T00:00:00.000Z",
    "detailsSubmitted": false,
    "email": "",
    "id": 2,
    "mode": 0,
    "paymentMethods": [
        {
            "available": false,
            "type": "alipay"
        },
        {
            "available": false,
            "type": "amazon_pay"
        },
        {
            "available": true,
            "type": "apple_pay"
        },
        {
            "available": false,
            "type": "bancontact"
        },
        {
            "available": false,
            "type": "billie"
        },
        {
            "available": false,
            "type": "blik"
        },
        {
            "available": true,
            "type": "card"
        },
        {
            "available": false,
            "type": "cartes_bancaires"
        },
        {
            "available": false,
            "type": "customer_balance"
        },
        {
            "available": false,
            "type": "eps"
        },
        {
            "available": false,
            "type": "giropay"
        },
        {
            "available": false,
            "type": "google_pay"
        },
        ...
    ],
    "payoutsEnabled": false,
    "rawResponse": {
        "business_profile": {
            "annual_revenue": null,
            "estimated_worker_count": null,
            "mcc": null,
            "minority_owned_business_designation": null,
            "name": null,
            "support_address": null,
            "support_email": null,
            "support_phone": null,
            "support_url": null,
            "url": null
        },
        "business_type": null,
        "capabilities": {},
        "charges_enabled": false,
        "controller": {
            "fees": {
                "payer": "account"
            },
            "is_controller": true,
            "losses": {
                "payments": "stripe"
            },
            "requirement_collection": "stripe",
            "stripe_dashboard": {
                "type": "full"
            },
            "type": "application"
        },
        "country": "DE",
        "created": 1757944702,
        "default_currency": "eur",
        "details_submitted": false,
        "email": null,
        "external_accounts": {
            "data": [],
            "has_more": false,
            "object": "list",
            "total_count": 0,
            "url": "/v1/accounts/acct_1S7cvB14358LTRqf/external_accounts"
        },
        "future_requirements": {
            "alternatives": [],
            "current_deadline": null,
            "currently_due": [],
            "disabled_reason": null,
            "errors": [],
            "eventually_due": [],
            "past_due": [],
            "pending_verification": []
        },
        "id": "acct_1S7cvB14358LTRqf",
        "metadata": {},
        "object": "account",
        "payouts_enabled": false,
        "requirements": {
            "alternatives": [],
            "current_deadline": null,
            "currently_due": [
                "business_profile.product_description",
                "business_profile.support_phone",
                "business_profile.url",
                "external_account",
                "tos_acceptance.date",
                "tos_acceptance.ip"
            ],
            "disabled_reason": "requirements.past_due",
            "errors": [],
            "eventually_due": [
                "business_profile.product_description",
                "business_profile.support_phone",
                "business_profile.url",
                "external_account",
                "tos_acceptance.date",
                "tos_acceptance.ip"
            ],
            "past_due": [
                "business_profile.product_description",
                "business_profile.support_phone",
                "business_profile.url",
                "external_account",
                "tos_acceptance.date",
                "tos_acceptance.ip"
            ],
            "pending_verification": []
        },
        "settings": {
            "bacs_debit_payments": {
                "display_name": null,
                "service_user_number": null
            },
            "branding": {
                "icon": null,
                "logo": null,
                "primary_color": null,
                "secondary_color": null
            },
            "card_issuing": {
                "tos_acceptance": {
                    "date": null,
                    "ip": null
                }
            },
            "card_payments": {
                "decline_on": {
                    "avs_failure": false,
                    "cvc_failure": false
                },
                "statement_descriptor_prefix": null,
                "statement_descriptor_prefix_kana": null,
                "statement_descriptor_prefix_kanji": null
            },
            "dashboard": {
                "display_name": null,
                "timezone": "Etc/UTC"
            },
            "invoices": {
                "default_account_tax_ids": null,
                "hosted_payment_method_save": "offer"
            },
            "payments": {
                "statement_descriptor": null,
                "statement_descriptor_kana": null,
                "statement_descriptor_kanji": null
            },
            "payouts": {
                "debit_negative_balances": true,
                "schedule": {
                    "delay_days": 7,
                    "interval": "daily"
                },
                "statement_descriptor": null
            },
            "sepa_debit_payments": {}
        },
        "tos_acceptance": {
            "date": null
        },
        "type": "standard"
    },
    "status": 0,
    "tosAccepted": true,
    "updatedAt": "2025-09-15T13:58:24.000Z"
}

Antwort, wenn `type` gleich `"refresh"` gilt

{
    "url": "https://connect.stripe.com/setup/s/acct_1S7dWp1yCkcDDzUj/biADCkORd6Jm"
}

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 Stripe-Onboarding-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidValue”
404 Not Found		`id` fehlt oder ist keine Ganzzahl. Der Eintrag wurde in der WEBSALE-Datenbank nicht gefunden. Das Aktualisieren von Daten ist fehlgeschlagen.
503 Service Unavailable	”serviceUnavailable”	Das Stripe-Konto konnte nicht geladen werden. Der Onboarding-Link konnte nicht erstellt werden.

DELETE payment/stripeonboarding/{id}

Mit diesem Endpunkt kann ein bestehender Onboarding-Eintrag anhand seiner ID entfernt werden. Das Konto bei Stripe bleibt bestehen, aber der aktuelle Shop wird keine Zahlungen mehr für dieses Konto verarbeiten. Für die Nutzung dieses Endpunkts sind Löschberechtigungen für Stripe-Onboarding-Daten erforderlich.

Beispiel

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

Antwort

{
    "success": true
}

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 Stripe-Onboarding-Daten.
404 Not Found		Es wurde kein Eintrag gefunden, oder das Löschen ist fehlgeschlagen.

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.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Unterstützte Methoden

Stripe-Onboarding-Vorgang

Datenfelder eines Eintrags

Beispiel

Beispiel von rawResponse

Methoden für Stripe-Onboarding

GET payment/stripeonboarding

Beispiel

Antwort

Fehlercodes

GET payment/stripeonboarding/{id}

Beispiel

Antwort

Fehlercodes

POST payment/stripeonboarding

Beispiel

Request Body

Antwort

Fehlercodes

PUT payment/stripeonboarding/{id}

Beispiel

Request Body

Antwort, wenn `type` gleich `"finish"` gilt

Antwort, wenn `type` gleich `"refresh"` gilt

Fehlercodes

DELETE payment/stripeonboarding/{id}

Beispiel

Antwort

Fehlercodes

Support

​Unterstützte Methoden

​Stripe-Onboarding-Vorgang

​Datenfelder eines Eintrags

​Beispiel

​Beispiel von rawResponse

​Methoden für Stripe-Onboarding

​GET payment/stripeonboarding

​Beispiel

​Antwort

​Fehlercodes

​GET payment/stripeonboarding/{id}

​Beispiel

​Antwort

​Fehlercodes

​POST payment/stripeonboarding

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT payment/stripeonboarding/{id}

​Beispiel

​Request Body

​Antwort, wenn type gleich "finish" gilt

​Antwort, wenn type gleich "refresh" gilt

​Fehlercodes

​DELETE payment/stripeonboarding/{id}

​Beispiel

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Stripe-Onboarding-Vorgang

Datenfelder eines Eintrags

Beispiel

Beispiel von rawResponse

Methoden für Stripe-Onboarding

GET payment/stripeonboarding

Beispiel

Antwort

Fehlercodes

GET payment/stripeonboarding/{id}

Beispiel

Antwort

Fehlercodes

POST payment/stripeonboarding

Beispiel

Request Body

Antwort

Fehlercodes

PUT payment/stripeonboarding/{id}

Beispiel

Request Body

Antwort, wenn `type` gleich `"finish"` gilt

Antwort, wenn `type` gleich `"refresh"` gilt

Fehlercodes

DELETE payment/stripeonboarding/{id}

Beispiel

Antwort

Fehlercodes

Support