# Verknüpfen Sie Financial Connections-Konten neu, die für Zahlungen oder Auszahlungen verwendet werden. Reaktivieren Sie inaktive Konten, um Daten abzurufen, tokenisierte Kontonummern wieder zu aktivieren und Datenberechtigungen zu aktualisieren. Ihre Kundinnen und Kunden müssen ein zuvor verknüpftes [Financial Connections](https://docs.stripe.com/api/financial_connections/accounts/object.md)-Konto möglicherweise aus [verschiedenen Gründen](https://docs.stripe.com/financial-connections/relink.md) erneut autorisieren, beispielsweise um ein Konto zu reaktivieren und so den Datenzugriff wiederherzustellen oder um deaktivierte [tokenisierte Kontonummern](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md) zu aktualisieren. Wenn Sie Financial Connections-Konten verwenden, um Bankkontodaten für Zahlungen oder Auszahlungen zu verifizieren, konfigurieren Sie eine Relink-Sitzung, um ein einziges berechtigtes Konto zu erfassen. Sie können: - [Eines bestimmten Financial Connections-Konto erneut verknüpfen](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-specific-account) - [Alle berechtigten Financial Connections-Konten bei derselben Bank erneut verknüpfen](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account) ## Verstehen, wenn ein Konto inaktiv wird [Serverseitig] Die verknüpften Financial Connections-Konten Ihrer Kundin oder Ihres Kunden können aus mehreren Gründen inaktiv werden. Beispiele: - Der Stripe vom Finanzinstitut zur Verfügung gestellte [OAuth](https://docs.stripe.com/financial-connections/fundamentals.md#how-stripe-links-financial-accounts)-Token läuft nach einer bestimmten Zeitspanne oder aufgrund von Inaktivität ab. - Das Finanzinstitut ändert seine Authentifizierungsanforderungen, z. B. verlangt es eine Multi-Faktor-Authentifizierung (MFA) oder der Kunde/die Kundin ändert den Nutzernamen und das Passwort. - Die Kundin oder der Kunde widerruft über das Online-Banking-Portal Ihre Zugriffsberechtigung. - Der Kunde/die Kundin schließt sein/ihr Konto beim Finanzinstitut. Wir benachrichtigen Sie, wenn ein Financial Connections-Konto mit dem [Webhook](https://docs.stripe.com/financial-connections/webhooks.md) `financial_connections.account.deactivated` inaktiv wird. Inaktive Financial Connections-Konten enthalten zusätzliche Status-Metadaten im Subhash `status_details.inactive`. Sie können nicht alle zugrunde liegenden Ursachen für ein inaktives Konto reparieren. Beispielsweise können Sie ein geschlossenes Konto nur reparieren, wenn die Kundin oder der Kunde es wieder eröffnet. Für Konten, die Sie nicht reparieren können, ist `status_details.inactive.action` `none`. Sie können jederzeit [ein Financial Connections-Konto abrufen](https://docs.stripe.com/api/financial_connections/accounts/retrieve.md), um dessen Status zu überprüfen. - Die Eigenschaft `status_details.inactive.cause` enthält einen übergeordneten Grund dafür, dass ein Financial Connections-Konto inaktiv ist. Wenn beispielsweise die OAuth-Verbindung eines Kontos abläuft, lautet sein Status `access_expired`. - Die Eigenschaft `status_details.inactive.action` enthält die Aktion, die ggf. zur Reaktivierung des Kontos ergriffen werden muss. Wenn Ihr Kunde/Ihre Kundin das Konto reaktivieren kann, indem er/sie einen Authentifizierungsvorgang zur erneuten Verknüpfung durchführt, lautet der Status `relink_required`. Wenn `status_details.inactive.action` `relink_required` ist, fordern Sie Ihre Kundin oder Ihren Kunden auf, den Authentifizierungsvorgang abzuschließen, um das Konto zu reaktivieren. Sie können beispielsweise einen Webhook-Handler wie den folgenden erstellen, um Webhook-Ereignisse zu verarbeiten: #### Python ```python import stripe import requests as r from requests.auth import HTTPBasicAuth # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. client = stripe.StripeClient('<>', stripe_version='2026-04-22.preview') # If you are testing your webhook locally with the Stripe CLI you # can find the endpoint's secret by running `stripe listen` # Otherwise, find your endpoint's secret in your webhook settings in # the Developer Dashboard endpoint_secret = 'whsec_...' @app.route('/webhook', methods=['POST']) def webhook(): event = None payload = request.data sig_header = request.headers["STRIPE_SIGNATURE"] try: event = client.construct_event(payload, sig_header, endpoint_secret) except ValueError as e: # Invalid payload raise e except stripe.error.SignatureVerificationError as e: # Invalid signature raise e if event["type"] == "financial_connections.account.deactivated": account = event["data"]["object"] if account["status"] == "inactive": if "status_details" in account: if account["status_details"]["inactive"]["action"] == "relink_required": prompt_user_to_relink(account) else: # if account does not have "status_details", check that the event destination is configured with the most recent public preview API version else: # No action to be taken. return jsonify(success=True) ``` Der `status` und die `status_details` eines Kontos sind auch verfügbar, wenn Sie ein Financial Connections-Konto abrufen. ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-04-22.preview" ``` ```json { "id": "{{ACCOUNT_ID}}", "object": "financial_connections.account", //..., "authorization": "{{AUTHORIZATION_ID}}", "status": "inactive", "status_details": { "inactive": { "action": "relink_required", "cause": "access_expired" } } } ``` ## Erneute Verknüpfung eines Financial Connections-Kontos [Serverseitig] [Clientseitig] Erstellen Sie eine Relink-Sitzung, die `relink_options.authorization` und `relink_options.account` angibt, bei der Ihre Kundinnen/Kunden das von `relink_options.account` identifizierte Financial Connections-Konto im Authentifizierungsvorgang auswählen muss. Die Sitzung ist nur dann erfolgreich und das Konto wird nur dann verknüpft, wenn Ihre Kundin bzw. Ihr Kunde genau dieses Konto erneut verknüpft. Ressourcen, die unter Verwendung des bestehenden Financial Connections-Kontos erstellt wurden, werden automatisch mit den Daten des neu verknüpften Kontos aktualisiert, einschließlich neuer tokenisierter Kontonummern. Falls Ihre Integration nicht dasselbe Konto erfordert, können Sie Ihren Kundinnen und Kunden gestatten, ein [neues Konto bei derselben Bank zu verknüpfen](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account). Erstellen Sie eine Financial Connections-Sitzung und geben Sie Folgendes an: 1. Setzen Sie `account_holder` auf denselben Wert wie das Feld `account_holder` des Financial Connections-Kontos. Wenn Sie einen [zweistufigen Bestätigungsablauf](https://docs.stripe.com/payments/build-a-two-step-confirmation.md) verwenden oder [Zahlungsdaten vor der Erstellung eines Intents erfassen](https://docs.stripe.com/payments/accept-a-payment-deferred.md), verfügt das Financial Connections-Konto nicht über einen `account_holder`. In diesem Fall setzen Sie `account_holder` bei der Erstellung der Sitzung auf `null`. 1. Legen Sie den Parameter `permissions` für Daten so fest, dass er `payment_method` und alle Daten des Kontos einschließt, die Sie abrufen möchten. Der Parameter `permissions` ist ein Array mit Werten, wie z. B. `[payment_method`, `balances`, `ownership`, `transactions`. Um die Privatsphäre Ihrer Nutzer/innen zu schützen, können Sie nur auf die Kontodaten zugreifen, die Sie im Parameter `permissions` angegeben haben. Überlegen Sie genau, welche Daten für Ihren Use Case erforderlich sind und fordern Sie die Zugriffsberechtigung nur für diese Daten an. Nach Abschluss des Authentifizierungsablaufs sieht Ihre Nutzer/in die Daten, die Sie im Parameter `permissions` angegeben haben, und gibt ihre Zustimmung zur Weitergabe dieser Daten. Das folgende Codebeispiel zeigt, wie `balances` und `payment_method` erfasst werden. 1. Setzen Sie den Parameter `relink_options.authorization` auf denselben Wert wie die `authorization`-ID des Financial Connections-Kontos. 1. Setzen Sie den Parameter `relink_options.account` auf die ID des Financial Connections-Kontos. ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}" \ -d "relink_options[account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" ``` Diese Anfrage gibt eine Antwort ähnlich der folgenden zurück: ``` { "id": "fcsess_abcd", "object": "financial_connections.session", "livemode": true, "account_holder": { "customer": "cus_NfjonN9919dELB", "type": "customer" }, "accounts": [], "client_secret": "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh", "filters": { "account_subcategories": ["checking", "savings"] }, "limits": { "accounts": 1 }, "permissions": ["payment_method", "balances"], "relink_options": { "authorization": "{{AUTHORIZATION_ID}}", "account": "{{ACCOUNT_ID}}" } } ``` 1. Verwenden Sie das zurückgegebene `client_secret` mit clientseitigen Stripe-SDKs, damit Ihre Nutzer/innen ihre Konten erneut verknüpfen können. Ein `client_secret` ermöglicht es den clientseitigen Stripe-SDKs, Änderungen an der Financial Connections-Sitzung vorzunehmen. Es darf nicht gespeichert, protokolliert, in URLs eingebettet oder anderen Personen als Ihren Endnutzerinnen und Endnutzern zugänglich gemacht werden. Stellen Sie sicher, dass TLS auf jeder Seite aktiviert ist, die das Client-Geheimnis enthält. 1. Verwenden Sie in Stripe.js [collectFinancialConnectionsAccounts](https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts), um ein Konto zu erfassen. Der Rückgabewert von `collectFinancialConnectionsAccounts` ist ein Promise. Wenn Nutzer/innen den Authentifizierungsvorgang abschließen, wird das Promise mit einem Objekt aufgelöst, das ein Unterobjekt `relink_result` enthält. Bei Erfolg enthält es auch die Liste der erneut verknüpften Konten. ```js const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }); if (financialConnectionsSession) { if (financialConnectionsSession.relink_result.account) { // relink successful const relinkedAccount = financialConnectionsSession.accounts[0]; } else { switch (financialConnectionsSession.relink_result.failure_reason) { case 'no_account': // user successfully authenticated with their bank, but did not link the expected account break; case 'no_authorization': // user did not successfully authenticate with their bank break; case 'other': // unexpected failure break; } } } ``` Es kann vorkommen, dass sich Ihre Kundinnen und Kunden zwar erfolgreich bei ihrem Finanzinstitut authentifizieren, im Authentifizierungsablauf von Financial Connections jedoch eine Fehlermeldung angezeigt wird. In diesem Fall ist `relink_result.account` nicht gesetzt, da wir das ausgewählte Konto nicht mit dem in `relink_options.account` angegebenen Konto abgleichen können. In diesem Fall empfehlen wir Folgendes: - Bitten Sie Ihren Kunden bzw. Ihre Kundin, eine neue Zahlungsmethode oder ein externes Bankkonto einzurichten. - Bitten Sie Ihren Kunden bzw. Ihre Kundin, es erneut über eine Financial Connections-Sitzung zu versuchen, die [alle berechtigten Konten bei derselben Bank](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account) zulässt. ## Optional: Verbinden Sie jedes berechtigte Financial Connections-Konto bei derselben Bank erneut [Serverseitig] [Clientseitig] Der im vorherigen Abschnitt verwendete Parameter `relink_options.account` setzt voraus, dass die Kundinnen und Kunden ein bestimmtes Financial Connections-Konto verknüpfen. Verknüpfen sie ein anderes Konto, wird ihnen im Authentifizierungsablauf eine Fehlermeldung angezeigt. Sie können stattdessen eine Relink-Sitzung nur mit `relink_options.authorization` erstellen. Dadurch wird Ihre Kundin oder Ihr Kunde aufgefordert, sich bei derselben Bank wie bei der Autorisierung zu authentifizieren, ohne dass sie/er ein bestimmtes Konto auswählen muss. Verwenden Sie `filters.account_subcategories`, um festzulegen, dass Ihre Kundin oder Ihr Kunde nur Giro- oder Sparkonten auswählen kann und verwenden Sie `limits.accounts`, um die Auswahl auf ein einziges Konto zu beschränken. Wenn Ihr Kunde ein bestehendes Financial Connections-Konto auswählt, werden dessen `status`, `permissions` und `account_numbers` aktualisiert. Ressourcen, die unter Verwendung des bestehenden Financial Connections-Kontos erstellt wurden, werden automatisch mit den Daten des neu verknüpften Kontos aktualisiert, einschließlich der neuen tokenisierten Kontonummern. Wenn Ihre Kundin bzw. Ihr Kunde ein neues Konto verknüpft, können Sie dieses zur Erstellung einer Zahlungsmethode verwenden. Bestehende Zahlungsmethoden werden nicht automatisch aktualisiert, wenn im Authentifizierungsablauf zur Neuverknüpfung ein neues Konto ausgewählt wird. Damit Ihre Kundin bzw. Ihr Kunde ein für Zahlungen oder Auszahlungen berechtigtes Financial Connections-Konto bei derselben Bank wie ihr/sein inaktives Konto verknüpfen kann, gehen Sie wie folgt vor: 1. Erstellen Sie eine Financial Connections-Sitzung, wobei `relink_options.authorization` auf die zu reparierende Financial Connections-Autorisierungs-ID, `limits.accounts` auf `1` und `filters.account_subcategories` auf `["checking", "savings"]` gesetzt ist ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "filters[account_subcategories][]=checking" \ -d "filters[account_subcategories][]=savings" \ -d "limits[accounts]=1" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}" ``` 1. Verwenden Sie das zurückgegebene `client_secret` mit clientseitigen Stripe-SDKs, damit Ihre Nutzer/innen ihre Konten erneut verknüpfen können. Ein `client_secret` ermöglicht es den clientseitigen Stripe-SDKs, Änderungen an der Financial Connections-Sitzung vorzunehmen. Es darf nicht gespeichert, protokolliert, in URLs eingebettet oder anderen Personen als Ihren Endnutzerinnen und Endnutzern zugänglich gemacht werden. Stellen Sie sicher, dass TLS auf jeder Seite aktiviert ist, die das Client-Geheimnis enthält. 1. Verwenden Sie in Stripe.js [collectFinancialConnectionsAccounts](https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts), um ein Konto zu erfassen. Der Rückgabewert von `collectFinancialConnectionsAccounts` ist ein Promise. Wenn Nutzer/innen den Authentifizierungsvorgang abschließen, wird das Promise mit einem Objekt aufgelöst, das ein Unterobjekt `relink_result` enthält. Bei Erfolg enthält es auch die Liste der erneut verknüpften Konten. 1. Übergeben Sie eine Liste der verknüpften Konten an die Client-Seite, um festzustellen, ob die Kundin bzw. der Kunde im Rahmen des Authentifizierungsablaufs zur erneuten Verknüpfung ein neues Konto verknüpft hat. ```js // Fetch existing accounts, or embed them in the server-rendered HTML const existingAccountIds = await fetchExistingAccounts(); const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }); const linkedAccount = financialConnectionsSession?.accounts?.[0] if (linkedAccount) { const isNew = existingAccountIds.includes(linkedAccount.id); } else { // user linked no accounts } ``` Wir empfehlen, einer Kundin oder einem Kunden die Verknüpfung eines neuen Kontos zu ermöglichen, um die folgenden Sonderfälle bei der Übergabe von `relink_options.account` zu behandeln: - Es kann vorkommen, dass Stripe nach der Authentifizierung der Kundinnen und Kunden bei ihrem Finanzinstitut keines der verfügbaren Konten erkennt. In diesem Fall und wenn `relink_options.account` gesetzt ist, wird im Authentifizierungsablauf eine Fehlermeldung angezeigt. Ist hingegen nur `relink_options.authorization` gesetzt, kann die Kundin oder der Kunde aus den verfügbaren Konten auswählen und mit dem Verknüpfungsvorgang des Kontos fortfahren. - Bei OAuth-Abläufen kann die Kundin bzw. der Kunde ein anderes Konto auswählen als das ursprünglich im OAuth-Modal seines/ihres Finanzinstituts verknüpfte. ## Optional: Erstellen Sie eine Zahlungsmethode [Serverseitig] [Clientseitig] Relink-Sitzungen, bei denen `relink_options.account` nicht gesetzt ist, können zur Erstellung neuer Financial Connections-Konten führen. In diesem Fall werden die aus bestehenden Financial Connections-Konten erstellten Zahlungsmethoden nicht aktualisiert. #### Zahlungen Verwenden Sie einen `SetupIntent`, um mithilfe des Financial Connections-Kontos eine `PaymentMethod` zu erstellen. Setzen Sie die Eigenschaft `customer` auf denselben Wert wie `account_holder.customer` des Financial Connections-Kontos. Falls Ihr Financial Connections-Konto keinen Wert für `account_holder` enthält, setzen Sie die Eigenschaft `customer` nicht. ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][financial_connections_account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" ``` Dadurch wird ein SetupIntent mit dem `status` `requires_confirmation` erstellt. Zeigen Sie Ihren Kundinnen und Kunden ein [ACH Mandat](https://docs.stripe.com/payments/ach-direct-debit.md#mandates) an und verwenden Sie eine Stripe Client Library, um den SetupIntent zu [bestätigen](https://docs.stripe.com/js/setup_intents/confirm_us_bank_account_setup) und Mandatsdaten zu erfassen. ```html
``` Lesen Sie mehr über die [Annahme von ACH Zahlungen](https://docs.stripe.com/payments/ach-direct-debit.md). #### Auszahlungen Verwenden Sie einen SetupIntent, um mithilfe des Financial Connections-Kontos eine PaymentMethod zu erstellen und zu bestätigen. Setzen Sie die Eigenschaft `customer` auf denselben Wert wie `account_holder.customer` des Financial Connections-Kontos. Falls Ihr Financial Connections-Konto keinen Wert für `account_holder` enthält, setzen Sie die Eigenschaft `customer` nicht. ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "flow_directions[]=outbound" \ -d "payment_method_types[]=us_bank_account" \ -d confirm=true \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][financial_connections_account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" ``` Erstellen Sie anschließend mithilfe der an den SetupIntent angehängten `payment_method` ein Bankkontotoken. Wenn Sie bei der Erstellung des SetupIntent eine/einen `customer` angegeben haben, geben Sie diese/n auch bei der Erstellung des Tokens an. ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" ``` Erfahren Sie mehr über [Connect-Auszahlungen](https://docs.stripe.com/connect/payouts-bank-accounts.md?bank-account-collection-integration=direct-api). ## Optional: Financial Connections-Autorisierung abrufen Financial Connections-Konten haben eine Eigenschaft für die `Autorisierung`, die einer [Financial Connections-Autorisierung](https://docs.stripe.com/api/financial_connections/authorizations/object.md) entspricht. Die Autorisierungsressource beschreibt den allgemeinen Status der Datenverbindung für alle Konten mit der Autorisierung. Wenn mehrere Konten auf dieselbe Autorisierung verweisen, kann die erneute Verknüpfung eines Kontos andere Konten mit derselben Autorisierung reaktivieren. Dies ist ein erwartetes Verhalten und wirkt sich nur in den folgenden Fällen auf Ihre Integration aus: 1. Sie verfügen über einen Webhook-Endpoint, der auf Ereignisse vom Typ `financial_connections.account.reactivated` wartet. 1. Wenn Sie eine Unternehmenslogik haben, die von einer Sitzung für die erneute Verknüpfung ausgeht, bei der der/die Nutzer/in ein einzelnes Konto auswählen muss, wird genau ein Konto reaktiviert. Autorisierung abrufen, um ihren Status anzuzeigen: ```curl curl https://api.stripe.com/v1/financial_connections/authorizations/{{FINANCIALCONNECTIONSAUTHORIZATION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-04-22.preview" ``` ```json { "id": "{{AUTHORIZATION_ID}}", "object": "financial_connections.authorization", "account_holder": { "customer": "cus_TnvzdXv6VwjyrN", "type": "customer" }, "institution": "fcinst_Qn1a6jqpI0Gb84", "institution_name": "StripeBank", "livemode": false, "status": "active", "status_details": {} } ``` ## Testen Befolgen Sie den [Testleitfaden](https://docs.stripe.com/financial-connections/testing.md), um zu erfahren, wie Sie ein Test-Bankkonto über Financial Connections verbinden. Um mit einem deaktivierten Konto zu testen, suchen Sie im Authentifizierungsablauf nach dem Institut für `inaktive Konten` und verbinden Sie eines der angegebenen Bankkonten. Um das Verhalten bei der Aktualisierung der tokenisierten Kontonummer zu testen, suchen Sie im Authentifizierungsablauf nach dem Institut für `tokenisierte Kontonummern` und verbinden Sie eines der angegebenen Bankkonten.