Onboarding Ihres verbundenen Kontos

Sie als Plattform müssen entscheiden, ob die erforderlichen Informationen von den verbundenen Konten vorab oder inkrementell erfasst werden sollen. Beim Onboarding im Voraus werden die eventually_due-Anforderungen für das Konto erfasst, während beim inkrementellen Onboarding nur die currently_due-Anforderungen erfasst werden.

Um zu bestimmen, ob Sie das Onboarding im Voraus oder inkrementelles Onboarding nutzen möchten, überprüfen Sie die Anforderungen für die Standorte und Funktionen Ihrer verbundenen Konten. Auch wenn Stripe versucht, etwaige Auswirkungen auf verbundene Konten zu minimieren, können sich Anforderungen im Laufe der Zeit ändern.

Für verbundene Konten, bei denen Sie für den Einzug der Anforderungen verantwortlich sind, können Sie das Verhalten von future requirements mit dem Parameter collection_options anpassen. Um die zukünftigen Anforderungen des Kontos zu erfassen, setzen Sie collection_options.future_requirements auf include.

Erstellen Sie einen Konto-Link unter Verwendung der ID des verbundenen Kontos und fügen Sie eine use_case.account_onboarding.refresh_url und eine use_case.account_onboarding.return_url hinzu.

Stripe leitet das verbundene Konto zur Aktualisierungs-URL weiter, wenn die Konto-Link-URL bereits aufgerufen wurde, abgelaufen oder aus anderen Gründen ungültig ist. Stripe leitet sie zur Rückgabe-URL weiter, wenn sie den Onboarding-Prozess abgeschlossen oder verlassen haben.

Zusätzlich geben Sie, abhängig davon, ob Sie alle Informationen sofort oder schrittweise erfassen möchten, entweder eventually_due oder currently_due in use_case.account_onboarding.collection_options.fields an. In diesem Beispiel wird eventually_due verwendet, um sowohl die currently_due- als auch die eventually_due-Anforderungen direkt im Rahmen des vollständigen Onboardings zu erfüllen. Für schrittweises Onboarding geben Sie currently_due an, um nur die currently_due-Anforderungen sofort zu erfassen.

curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "account": 
"{{CONNECTED_ACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'

Leiten Sie Ihr verbundenes Konto zum Onboarding-Prozess weiter

Geben Sie die Konto-Link-URL an, um Ihr verbundenes Konto an den Onboarding-Prozess weiterzuleiten. Jede Konto-Link-URL kann nur einmal verwendet werden, da sie Zugriff auf die persönlichen Daten der Kontoinhaberin/des Kontoinhabers gewährt.

Richten Sie Ihre Integration so ein, dass Änderungen der Kontoanforderungen überwacht werden. Sie können den Umgang mit neuen Anforderungen (und wie diese möglicherweise Zahlungen und Auszahlungen deaktivieren) mit den Test-Auslöserkarten testen.

Senden Sie ein verbundenes Konto über das Onboarding zurück, wenn es currently_due- oder eventually_due-Anforderungen erfüllt. Sie müssen die spezifischen Anforderungen nicht identifizieren, da die Onboarding-Schnittstelle weiß, welche Informationen sie erfassen muss. Wenn beispielsweise ein Tippfehler die Verifizierung der Identität des Kontoinhabers/der Kontoinhaberin verhindert, fordert das Onboarding ihn/sie auf, ein Identitätsdokument hochzuladen.

Stripe benachrichtigt Sie über alle bevorstehenden Aktualisierungen der Anforderungen, die sich auf Ihre verbundenen Konten auswirken. Sie können diese Informationen proaktiv erfassen, indem Sie die Anforderungen Ihrer Konten überprüfen, die einen requested_reasons.code von future_requirements aufweisen.

Für verbundene Konten, bei denen Stripe für das Erfassen von Anforderungen verantwortlich ist, erhalten Sie keine Updates mehr für Identitätsangaben, nachdem Sie einen Konto-Link oder eine Kontositzung erstellt haben.

Konten speichern Identitätsinformationen im Hash identity.

Verifizierungsfehler handhaben

Achten Sie auf das Ereignis v2.core.accounts[Anforderungen].updated. Enthält das Konto Anforderungen mit einem minimum_deadline.Status von currently_due, wird beim Erreichen der Frist die entsprechende Funktionalität deaktiviert und diese Status werden zu past_due.

Lassen Sie Ihre Konten die Verifizierungsanforderungen regeln, indem Sie sie an das von Stripe gehostete Onboarding-Formular leiten.

Connect Onboarding verlangt, dass Sie sowohl eine return_url als auch eine refresh_url übergeben, um alle Fälle steuern zu können, in denen die Nutzer/innen an Ihre Plattform zurückgeleitet werden. Es ist wichtig, dass Sie diese URLs korrekt implementieren, um Ihren Nutzern/innen die bestmögliche Erfahrung zu bieten.

Rückgabe-URL

Stripe leitet das verbundene Konto zurück zu dieser return_url, wenn sie den Onboarding-Ablauf abschließen oder an einer beliebigen Stelle des Ablaufs auf Für später speichern klicken. Dies bedeutet nicht, dass alle Informationen erfasst wurden oder dass es keine ausstehenden Anforderungen für das Konto gibt. Es bedeutet lediglich, dass der Ablauf ordnungsgemäß gestartet und verlassen wurde.

Diese URL überträgt keinen Status. Nachdem ein verbundenes Konto zur return_url weitergeleitet wurde, prüfen Sie, ob das Konto das Onboarding abgeschlossen hat, indem Sie entweder:

• Abrufen des Kontos und Überprüfen desAnforderungs-Hash für ausstehende Anforderungen.
• Den Status des Kontos in Ihrer Anwendung zwischenspeichern und durch Abhören des v2.core.account[requirements].updated-Ereignisses aktuell halten.

Wenn das Onboarding unvollständig ist, stellen Sie in Ihrer Anwendung Hinweise bereit, damit das Konto das Onboarding später fortsetzen kann.

URL aktualisieren

Stripe leitet den Kontobenutzer in den folgenden Fällen zur refresh_url weiter:

• Der Link ist abgelaufen (einige Minuten sind seit der Erstellung des Links vergangen).
• Die Nutzerin/der Nutzer hat die URL bereits aufgerufen (sie/er hat die Seite aktualisiert oder auf die Zurück/Vorwärts-Schaltfläche im Browser geklickt).
• Ihre Plattform hat keinen Zugang mehr zu diesem Konto.
• Der Link wurde in einer Anmeldeformular eines Drittanbieters freigegeben, z. B. in einem Messaging-Client, der versucht, auf die URL zuzugreifen, um eine Vorschau anzuzeigen. Viele Kunden besuchen automatisch Links, was dazu führt, dass ein Konto-Link abläuft.
• Das Konto wurde abgelehnt.

Konfigurieren Sie die refresh_url so, dass sie eine Methode auf Ihrem Server aufruft, die einen neuen Konto-Link mit denselben Parametern erstellt und das verbundene Konto anschließend zur neuen Konto-Link-URL weiterleitet.

Ein/e Kontonutzer/in, die/der zu Ihrer return_url weitergeleitet wird, hat den Onboarding-Prozess möglicherweise nicht abgeschlossen. Verwenden Sie den Endpoint /v2/core/accounts, um das Account-Objekt abzurufen und zu prüfen, ob configuration.recipient.capabilities.stripe_balance.stripe_transfers.status auf active gesetzt ist. Wenn der Status nicht active ist und configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code den Wert requirements_past_due hat, zeigen Sie in Ihrer Nutzeroberfläche Hinweise an, damit die/der Kontonutzer/in das Onboarding über einen neuen Konto-Link fortsetzen kann. Behandeln Sie andere Codes entsprechend.

Das von Stripe gehostete Onboarding unterstützt außerdem Updates, die vom verbundenen Konto selbst initiiert werden, um bereits bereitgestellte Informationen zu aktualisieren. Beachten Sie das v2.core.account[requirements].updated-Ereignis, das an Ihren Webhook-Endpoint gesendet wird, um benachrichtigt zu werden, wenn das Konto die Anforderungen erfüllt.

Wenn Sie einen Konto-Link erstellen, setzen Sie den type auf account_onboarding. Konto-Links dieses Typs stellen ein Formular bereit, um ausstehende Anforderungen einzugeben. Verwenden Sie ihn, wenn Sie ein neues verbundenes Konto einbinden oder wenn ein bestehendes Konto neue Anforderungen hat (z. B. wenn Sie eine neue Funktion anfordern, die zusätzliche Informationen erfordert).