Auf Angaben zur Inhaberschaft für ein Financial Connections-Konto zugreifen

Wir empfehlen Ihnen, eine Kundin/einen Kunden mit einer zu der Kundin/dem Kunden gehörenden E-Mail-Adresse zu erstellen, die Sie dann Ihrer Zahlung hinzufügen. Wenn Sie ein Kundenobjekt anhängen, können Sie später zuvor verknüpfte Konten auflisten. Durch Angabe einer E-Mail-Adresse für das Kundenobjekt kann Financial Connections den Authentifizierungsvorgang optimieren, indem es für eine reibungslose Anmeldung oder reibungslose Registrierung auf Kundenseite sorgt, je nachdem, ob es sich um wiederkehrende Link-Nutzer/innen handelt.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}}

Sie müssen ein Konto erfassen, bevor Sie auf die Daten zur Inhaberschaft zugreifen können. Um mehr über die Erfassung von Financial Connections-Konten zu erfahren, lesen Sie den Integrationsleitfaden, der für Ihren Anwendungsfall relevant ist: (zum Beispiel Zahlungen akzeptieren, Connect-Auszahlungen ermöglichen oder durch andere Daten gestützte Produkte entwickeln).

Wenn Sie Connect Onboarding für Custom-Konten verwenden, um Financial Connections-Konten zu erfassen, konfigurieren Sie, auf welche Daten Sie im Dashboard zugreifen möchten.

Wenn Sie eine API-Integration zur Erfassung von Konten verwenden, geben Sie die Daten, auf die Sie Zugriff benötigen, mit dem Parameter Berechtigungen an. Die angeforderten Datenberechtigungen können von den Nutzerinnen und Nutzern im Authentifizierungsablauf eingesehen werden. Financial Connections-Konten können über verschiedene Integrationspfade erfasst werden. Die Art und Weise, wie Sie den Parameter angeben, variiert je nach API leicht.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=ownership \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method

Bei der Verwendung dynamischer Zahlungsmethoden für bestimmte Zahlungs-APIs können Sie die angeforderten Berechtigungen auch im Dashboard konfigurieren. Hier erfahren Sie, wie Sie auf zusätzliche Kontodaten für Financial Connections-Konten zugreifen.

Alle Datenabrufe in Financial Connections sind asynchron. Sie leiten die Aktualisierung einer Inhaberschaft ein, warten auf ihren Abschluss und rufen dann die Ergebnisse ab. Sie können Aktualisierungen der Inhaberschaft mit dem API-Parameter prefetch oder mit der Refresh API abrufen.

Angaben zur Inhaberschaft vorab abrufen

Geben Sie an, ob Sie die Details zur Kontoinaberschaft vor der Kontoerfassung vorab abrufen möchten. Dadurch wird der Aktualisierungsvorgang eingeleitet, sobald Ihr/e Nutzer/in sein/ihr Konto im Authentifizierungsablauf verbindet. Legen Sie prefetch fest, wenn Sie Daten zur Inhaberschaft für jedes verknüpfte Konto benötigen, um sicherzustellen, dass Sie diese mit minimaler Verzögerung erhalten. Der Parameter prefetch ist für alle APIs verfügbar, die Financial Connections unterstützen.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_options[us_bank_account][financial_connections][prefetch][]"=ownership \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=ownership

Eine On-Demand-Aktualisierung einleiten

Verwenden Sie die Refresh API, um On-Demand-Aktualisierungen der Inhaberschaft nach der Kontoerfassung einzuleiten, und Angaben zur Inhaberschaft für ein bestimmtes Konto nach Bedarf abzurufen, sodass Sie die Entscheidung auf einen späteren Zeitpunkt verschieben können. Obwohl sich die Daten zur Kontoinhaberschaft ändern können, ändern sie sich in der Regel nicht so häufig wie Saldodaten oder Transaktionsdaten.

Verwenden Sie die Financial Connections-Konto-ID, um eine Aktualisierung zu starten. Wenn Sie die Integration über einen Zahlungsablauf vornehmen, finden Sie die Konto-ID in der zugehörigen Zahlungsmethode. Wenn Sie eine Financial Connections-Sitzung verwenden, rufen Sie sie über die Sitzung ab.

curl https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}}
/refresh \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "features[]"=ownership

Warten Sie, bis die Aktualisierung der Inhaberschaft abgeschlossen ist

Das Feld ownership_refresh eines Financial Connections-Kontos stellt den Aktualisierungsstatus der Inhaberschaft dar. Dieses Feld bleibt null, bis Sie die Berechtigung ownership anfordern und eine Aktualisierung einleiten. Nachdem Sie eine Aktualisierung der Inhaberschaft gestartet haben, ändert sich der Status in pending und nach Abschluss wechselt er entweder zu succeeded oder zu failed. Wir senden das Ereignis financial_connections.account.refreshed_ownership, wenn die Aktualisierung der Inhaberschaft abgeschlossen ist. Um zu ermitteln, ob die Inhaberschaft erfolgreich aktualisiert wurde, überprüfen Sie das Feld ownership_refresh.status während der Bearbeitung des Webhooks.

Nachdem die Aktualisierung einer Inhaberschaft abgeschlossen wurde, legt Stripe die Verfügbarkeit zukünftiger Aktualisierungen über das Feld ownership_refresh.next_refresh_available_at fest. Überprüfen Sie dieses Feld, bevor Sie eine neue Aktualisierung der Inhaberschaft veranlassen, um sicherzustellen, dass die Aktualisierungen derzeit tatsächlich verfügbar sind. Wenn Sie eine Aktualisierung durchführen und der Wert dabei null ist (dies ist immer der Fall, wenn die Aktualisierung aussteht, oder wenn das Konto inaktiv ist) oder weniger Zeit bleibt als für den Zeitstempel next_refresh_available_at angegeben ist, wird die Aktualisierung nicht veranlasst.

Nachdem die Angaben zur Inhaberschaft aktualisiert wurden, rufen Sie das Financial Connections-Konto über die API ab und erweitern das Feld Inhaberschaft, um Details zur Inhaberschaft anzuzeigen.

curl -G https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=ownership

Dadurch wird das Financial Connections-Konto zurückgegeben, wobei das Eigentümerfeld um die Liste der Kontoinhaber/innen erweitert wurde:

{
  "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid",
  "object": "financial_connections.account",
  "ownership": {
    "id": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb",
    "object": "financial_connections.account_ownership",
    "created": 1651784999,
    "owners": {
      "object": "list",
      "data": [
        {
          "name": "Jenny Rosen",
          "email": "jenny.rosen@example.com",
          "phone": "+1 555-555-5555",
          "ownership": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb",
          "raw_address": "510 Townsend San Francisco, CA 94103",
          "refreshed_at": 1651784999
        }
      ],
      "has_more": false,
      "url": "/v1/financial_connections/accounts/fca_zbyrdjTrwcYZJZc6WBs6GPid/owners?ownership=fcaowns_1MzTG4IG1CZuezXppfPbUpXb"
    }
  },
  "ownership_refresh": {
    "status": "succeeded",
    "last_attempted_at": 1651784999,
    "next_refresh_available_at": 1651785000
  },
  // ...
}

Stripe gibt die von einem Finanzinstitut zur Verfügung gestellten Eigentümerinformationen zurück, wobei deren Verfügbarkeit variiert. Wir geben alle verfügbaren Felder und Eigentümer/innen zurück, die von der Bank bereitgestellt werden. Zu den Eigentumsangaben können Name, Adresse, E-Mail und Telefonnummer des Kontoinhabers/der Kontoinhaberin gehören.