Onboarding Ihres verbundenen KontosÖffentliche Vorschau

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 mit der verbundenen Konto-ID 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 an die Aktualisierungs-URL weiter, wenn die Konto-Link-URL bereits besucht wurde, abgelaufen oder anderweitig ungültig ist. Stripe leitet verbundene Konten an die Rückgabe-URL weiter, wenn sie den Onboarding-Ablauf abgeschlossen oder verlassen haben. Darüber hinaus müssen Sie, je nach den erfassten Informationen, entweder currently_due oder eventually_due als use_case.account_onboarding.collection_options.fields festlegen. In diesem Beispiel wird eventually_due gewählt, um das Onboarding im Voraus zu verwenden. Für inkrementelles Onboarding setzen Sie es auf currently_due.

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

Ihr verbundenes Konto an die Konto-Link-URL weiterleiten

Leiten Sie das verbundene Konto an die Konto-Link-URL weiter, um es an den Onboarding-Ablauf zu senden. Jede Konto-Link-URL kann nur einmal verwendet werden, da sie Zugriff auf die persönlichen Daten des Kontoinhabers/der Kontoinhaberin gewährt. Authentifizieren Sie das Konto in Ihrer Anwendung, bevor Sie es an diese URL weiterleiten.

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.

Der Konto-Link benötigt eine refresh_url und return_url, um alle Fälle bearbeiten zu können, in denen das verbundene Konto zurück zu Ihrer Plattform geleitet wird. Es ist wichtig, diese korrekt zu implementieren, um Ihren verbundenen Konten den besten Onboarding-Ablauf zu bieten.

Aktualisierungs-URL

Ihr verbundenes Konto wird an die refresh_url weitergeleitet, wenn:

• Der Link ist abgelaufen (seit Erstellung des Links sind ein paar Minuten vergangen).
• Der Link wurde bereits aufgerufen (das verbundene Konto hat die Seite aktualisiert oder auf die Zurück- oder Vorwärts-Schaltfläche geklickt).
• 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.

Konfigurieren Sie die refresh_url so, dass sie eine Methode auf Ihrem Server aufruft, um einen neuen Konto-Link mit denselben Parametern zu erstellen und das verbundene Konto auf die neue Konto-Link-URL umzuleiten.

Rückgabe-URL

Stripe leitet das verbundene Konto zurück zu dieser 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 übergibt keinen Status. Nachdem ein verbundenes Konto an die return_url weitergeleitet wurde, ermitteln Sie, ob das Konto das Onboarding abgeschlossen hat. Rufen Sie das Konto ab und überprüfen Sie den Hash Anforderungen auf ausstehende Anforderungen. Alternativ können Sie das an Ihren Webhook-Endpoint gesendete Ereignis v2.core.account[requirements].updated überwachen und den Status des Kontos in Ihrer Anwendung zwischenspeichern. Wenn das Onboarding unvollständig ist, geben Sie in Ihrer Anwendung Eingabeaufforderungen an, damit das Onboarding zu einem späteren Zeitpunkt fortgesetzt werden kann.

Das von Stripe gehostete Onboarding unterstützt auch von verbundenen Konten initiierte Aktualisierungen der Informationen, die diese bereits angegeben haben. Überwachen Sie das Ereignis v2.core.account[requirements].updated, das an Ihren Webhook-Endpoint gesendet wird. Sie werden benachrichtigt, sobald das Konto die Anforderungen erfüllt und seine Informationen aktualisiert hat.

Wenn Sie einen Kontolink erstellen, können Sie den type entweder auf account_onboarding oder account_updatefestlegen.

Kontolinks für account_onboarding

Konto-Links dieser Art bieten ein Formular zur Eingabe ausstehender Anforderungen. Verwenden Sie es, wenn Sie das Onboarding eines neuen verbundenen Kontos durchführen oder wenn ein/e bestehende/r Nutzer/in neue Anforderungen hat (zum Beispiel wenn ein verbundenes Konto bereits genügend Informationen bereitgestellt hat, Sie jedoch eine neue Funktion angefordert haben, für die zusätzliche Informationen erforderlich sind). Senden Sie sie an diese Art von Konto-Link, um nur die neuen Informationen zu erfassen, die Sie benötigen.

Kontolinks für account_update

Konto-Links dieses Typs sind für Konten aktiviert, bei denen Ihre Plattform für die Anforderungserfassung verantwortlich ist. account_update-Links zeigen die Attribute an, die bereits auf dem Kontoobjekt ausgefüllt sind, und ermöglichen es dem verbundenes Konto, zuvor bereitgestellte Informationen zu bearbeiten. Geben Sie in Ihrer Anwendung eine Option an (z. B. „Mein Profil bearbeiten“ oder „Meine Verifizierungsinformationen aktualisieren“), mit der verbundene Konten selbst Aktualisierungen vornehmen können.