Auf Salden für ein Financial Connections-Konto zugreifen

Erfahren Sie, wie Sie mit der Erlaubnis Ihrer Nutzer/innen auf die Salden eines Kontos zugreifen können.

Mit der Financial Connections API können Sie aktuelle Salden eines Financial Connections-Kontos abrufen. Daten zum Guthaben sind für eine Vielzahl von Anwendungen nützlich, einschließlich der Reduzierung des Risikos unzureichender Deckung für ACH, der Risikoevaluation und der Entwicklung von Finanzmanagement-Tools.

Bevor Sie loslegen

Sie müssen die Registrierung für Financial Connections abgeschlossen haben, um im Live-Modus auf balances zugreifen zu können. Den Status Ihrer Registrierung können Sie in Ihren Dashboard-Einstellungen einsehen, wo Sie sich alternativ auch neu registrieren können. Die Daten von Financial Connections sind im Test-Modus immer verfügbar.

Kundin/Kunde erstellen
Recommended
Server-side

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.

Zugriff auf die Salden eines Kontos anfordern
Serverseitig

Sie müssen ein Konto erfassen, bevor Sie auf seine Guthabendaten 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: Zahlungen akzeptieren, Connect-Auszahlungen ermöglichen oder durch andere Daten gestützte Produkte entwickeln.

Beim Anlegen eines Accounts geben Sie mit dem Parameter permissions an, auf welche Daten Sie zugreifen möchten. Der Satz der angeforderten Datenberechtigungen ist für den Benutzer im Authentifizierungsablauf sichtbar. Financial Connections Accounts können über verschiedene Integrationspfade gesammelt werden, und die Art und Weise, wie Sie den Parameter angeben, variiert je nach API leicht.

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.

Saldoaktualisierung veranlassen
Serverseitig

Alle Datenabrufe in Financial Connections sind asynchron. Sie leiten eine Saldoaktualisierung ein, warten auf deren Abschluss und rufen dann die Ergebnisse ab. Sie können Saldoaktualisierungen mit dem API-Parameter prefetch oder mit der Refresh API initiieren.

Saldodaten vorab abrufen

Geben Sie an, ob Sie die Kontosalden 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 Saldodaten für jedes verknüpfte Konto benötigen, um sicherzustellen, dass Sie diese mit minimaler Verzögerung erhalten. Ein Beispiel hierfür ist die Planung der Durchführung von Saldoprüfungen vor der Veranlassung einer ACH-Zahlung. Der Parameter prefetch ist für alle APIs verfügbar, die Financial Connections unterstützen.

Eine On-Demand-Aktualisierung einleiten

Verwenden Sie die Refresh API, um On-Demand-Saldosaktionsaktualisierungen nach der Kontoerfassung zu veranlassen und rufen Sie Saldoinformationen nach Bedarf für ein bestimmtes Konto ab. Sie erhalten so die Möglichkeit, die Entscheidung auf einen späteren Zeitpunkt zu verschieben.

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.

Notiz

Inaktive Konten können keine Aktualisierungen durchführen.

Auf den Abschluss der Saldoaktualisierung warten

Das Feld balance_refresh eines Financial Connections-Kontos stellt den Aktualisierungsstatus des Saldos dar. Dieses Feld bleibt null, bis Sie die Berechtigung balances anfordern und eine Aktualisierung einleiten. Nachdem Sie eine Aktualisierung des Saldos 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_balance, wenn die Aktualisierung des Saldos abgeschlossen ist. Um zu ermitteln, ob der Saldo erfolgreich aktualisiert wurde, überprüfen Sie das Feld balance_refresh.status während der Bearbeitung des Webhooks.

Nachdem die Aktualisierung eines Saldos abgeschlossen wurde, legt Stripe die Verfügbarkeit zukünftiger Aktualisierungen über das Feld balance_refresh.next_refresh_available_at fest. Überprüfen Sie dieses Feld, bevor Sie eine neue Aktualisierung des Saldos 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.

Beta

In dem unwahrscheinlichen Fall, dass eine Aktualisierung fehlschlägt, ist das error-Feld auf dem Aktualisierungs-Hash eine Beta-Funktion, die die Ursache des Fehlers angibt und die nächsten Schritte empfiehlt. Wenn Sie es verwenden möchten, senden Sie uns eine E-Mail, um Zugriff anzufordern.

Salden eines Kontos abrufen
Serverseitig

Nachdem die Saldoaktualisierung abgeschlossen ist, rufen Sie das Financial Connections-Konto aus dem Text des financial_connections.account.refreshed_balance-Ereignisses oder über die API ab.

Wenn die Aktualisierung erfolgreich abgeschlossen wurde, enthält das Kontoobjekt Saldodaten.

{
  "id": "fca_1Jbry3BAjqvGMUSxCDjFsrLU",
  "object": "financial_connections.account",
  "balance": {
    "as_of": 1651516592,
    "cash": {
      "available": {
        "usd": 6000
      }
    },
    "current": {
      "usd": 6000
    },
    "type": "cash"
  },
  "balance_refresh": {
    "last_attempted_at": 1651516582,
    "next_refresh_available_at": 1651516583,
    "status": "succeeded",
  },
  // ... other fields on the Financial Connections Account
}

Saldodaten-Details

Der Hash balance beschreibt die von einem Finanzinstitut bereitgestellten verschiedenen Guthabenarten.

Arten von Guthaben	Beschreibung
`current`	Das `current` Guthaben ist der Geldbetrag, der auf das Konto gebucht wurde. Dieser Betrag ignoriert Ereignisse, die noch ausstehen, z. B. ein- und ausgehende Überweisungen sowie andere Einbehaltungen, die noch gebucht werden müssen. Ein positiver Betrag zeigt an, dass dem/der Kontoinhaber/in Geld geschuldet wird. Ein negativer Betrag an, dass der/die Kontoinhaber/in Geld schuldet.
`available`	Das Saldo-Objekt ist polymorph, mit den Typen `cash` und `credit`. Wenn der Saldo den `type: "cash"` hat, sehen Sie ein Unterobjekt `cash` mit der Eigenschaft `available`. Dies ist der Geldbetrag, der zur Verfügung steht, zum Beispiel für Überweisungen oder Auszahlungen, nach Berücksichtigung von ein- und ausgehenden Einbehaltungen.
`used`	Das Saldo-Objekt ist polymorph, mit den Typen `cash` und `credit`. Wenn der Saldo den `type: "credit"` hat, gibt es ein Unterobjekt `credit` mit der Eigenschaft `used`, d. h. der Geldbetrag, der nach Berücksichtigung der ausgehenden einbehaltenen Beträge verbraucht wurde. Bei Guthaben gilt für `current` und `used` Beträge die gleiche Vorzeichenkonvention wie für Barguthaben: ein positiver Betrag bedeutet, dass dem/der Kontoinhaber/in Gelder geschuldet werden, ein negativer Betrag bedeutet, dass von dem/der Kontinhaber/in Geld geschuldet wird. In den meisten Fällen weist ein Guthaben negative Beträge auf.

Die Verfügbarkeit von Guthaben variiert je nach zugrunde liegendem Finanzinstitut. Wir geben alle Saldodaten, auf die wir Zugriff haben, zurück. In seltenen Fällen, meistens bei kleineren Finanzinstituten, kann Stripe keine Saldodaten von einem Finanzinstitut oder einem Partner abrufen. In diesem Fall ist das balance-Objekt null. Das Saldo-Objekt ist auch dann null, wenn das Konto getrennt wurde. In einigen Fällen wird nur ein current-Saldo zurückgegeben. Informationen zur Datenabdeckung finden Sie in unserer Liste der unterstützten Institute.

Verwenden Sie für den Saldotyp cash das Unterobjekt available, um zu bestätigen, dass ausreichend Gelder vorhanden sind, bevor Sie eine ACH-Lastschriftzahlung einleiten. Wenn ein available Saldo null ist, können Sie den current Saldo verwenden, um zu bestätigen, dass ausreichend Gelder vorhanden sind, bevor Sie eine ACH-Lastschrift initiieren. Beachten Sie jedoch, dass bei diesem Betrag Ereignisse ignoriert werden, die noch nicht auf einem Konto gebucht wurden, wie z. B. eingehende Transfers, ausgehende Transfers und sonstige zurückgehaltene Beträge.

Das Feld as_of eines Saldos ist das Datum und die Uhrzeit, zu der das Finanzinstitut diesen Saldo berechnet hat. Dies ist nicht identisch mit dem Datum und der Uhrzeit des Abrufs der Saldodaten. Beispielsweise aktualisieren bestimmte Institute die Saldodaten nur einmal täglich, während andere häufiger aktualisieren.