Mit Treasury-Finanzkonten arbeiten
Wenn Sie Stripe Treasury auf Ihrer Plattform aktivieren, können Sie Ihrer Plattformarchitektur FinancialAccount
-Objekte hinzufügen, um das effiziente Speichern Senden und Empfangen von Geldern zu ermöglichen. Nachdem Sie API-Zugriff auf Treasury erhalten haben, fügt Stripe Ihrem Plattformkonto ein Finanzkonto hinzu und ermöglicht Ihnen die Bereitstellung eines individuellen Finanzkontos für jedes berechtigte verbundene Custom-Konto auf Ihrer Plattform.
Notiz
Multiple Financial Accounts beta Mit der Beta-Funktion für mehrere Finanzkonten können Sie mehrere Finanzkonten für ein einzelnes verbundenes Custom-Konto eröffnen. Kontaktieren Sie treasury-support@stripe.com, um auf den Test-Modus für diese Funktion zuzugreifen und sich auf die Warteliste setzen zu lassen.
Jedes Finanzkonto hat ein eigenes Guthaben, das vom Saldo des Kontos, mit dem es verknüpft ist, getrennt ist. Der/die Inhaber/in eines verbundenen Custom-Kontos auf Ihrer Plattform könnte beispielsweise über ein 100 USD Guthaben auf dem verbundenen Konto und ein 200 USD Guthaben auf dem Finanzkonto verfügen. In diesem Szenario verfügt der/die Inhaber/in des verbundenen Kontos über eine Summe von 300 USD, die zwischen seinem/ihren Finanzkonto und den Salden des verbundenen Kontos verteilt ist. Diese beiden Guthaben bleiben getrennt, aber mit der API ist die Geldbewegung vom Saldo des verbundenen Kontos zum Saldo des Finanzkontos möglich.
In der Stripe API dienen FinancialAccount
-Objekte als Quelle und Ziel von API-Anfragen für Geldbewegungen. Sie fordern Features
über die API an, die FinancialAccounts
zugewiesen werden und zusätzliche Funktionen für die Finanzkonten auf Ihrer Plattform bereitstellen. Um beispielsweise Zahlungskartenfunktionen für ein bestimmtes Finanzkonto zu aktivieren, senden Sie eine API-Anfrage mit der FinancialAccount
-ID für die Funktion card_issuing
. Weitere Informationen zu Feature
-Objekten finden Sie unter Funktionen von Finanzkonten. Lesen Sie den Abschnitt Verfügbare Funktionen in diesem Leitfaden, um die erforderlichen Funktionen für verbundene Konten für jede Feature
zu überprüfen.
Bevor Sie Finanzkonten im Live-Modus für Ihre Treasury-Integration erstellen, empfehlen wir Ihnen, zunächst Finanzkonten im Test-Modus zu erstellen. Finanzkonten im Test-Modus können kein echtes Geld empfangen oder senden, können nicht im Live-Modus verwendet werden und generieren kein Live-Konto mit echten Routing- und Kontoinformationen, sind aber ansonsten hinsichtlich Konfiguration und Funktionalität identisch.
FinancialAccount erstellen
Verwenden Sie POST /v1/treasury/financial_accounts
, um FinancialAccounts
zu erstellen. Nehmen Sie die verbundene Konto-ID als Wert der Kopfzeile Stripe-Account
des Aufrufs auf, um das FinancialAccount
einem verbundenen Konto zuzuordnen. Derzeit kann jedes verbundene Konto nur ein FinancialAccount
haben.
Notiz
Multiple Financial Accounts beta Verbundenen Konten können mehrere Finanzkonten zugeordnet sein, indem dieselbe ID des verbundenen Kontos als Wert im Stripe-Account
-Header angegeben wird. Standardmäßig können Sie maximal zehn Finanzkonten mit einem einzigen verbundenen Konto verknüpfen (geschlossene Finanzkonten werden hierbei nicht berücksichtigt). Wenn Sie mehr Finanzkonten verknüpfen möchten, wenden Sie sich an treasury-support@stripe.com.
Die folgende JSON definiert die Objektstruktur des FinancialAccount
:
In der Regel fordern Sie bei einer API-Anfrage zur Kontoerstellung auch Finanzkontofunktionen an. Unabhängig von den von Ihnen angeforderten Features
muss für das verbundene Konto die treasury
-Funktion aktiviert sein. Wenn Sie sich nicht sicher sind, ob das verbundene Konto über die Funktion verfügt, überprüfen Sie dies mithilfe von GET /v1/accounts/{{CONNECTED_ACCOUNT_ID}}
. Der capabilities
-Hash des Kontos muss einen treasury
-Wert von active
haben.
… "capabilities": { "card_issuing": "active", "card_payments": "active", "transfers": "active", "treasury": "active", "us_bank_account_ach_payments": "active" }, …
Wenn Sie Karten ausstellen möchten, die mit dem Saldo des Finanzkontos verknüpft sind, muss für die verbundenen Konten Ihrer Plattform außerdem die Funktion „Issuing“ (card_issuing
) aktiviert sein. Das verbundene Konto muss über diese Funktion verfügen, bevor Sie die Funktion card_issuing
für sein Finanzkonto anfordern können. Wenn das verbundene Konto nicht über diese Funktion verfügt, führt der Versuch, ein FinancialAccount
mit einer Anforderung für die Funktion card_issuing
zu erstellen, zu einem Fehler.
Notiz
Multiple Financial Account beta Sie können das Feld nickname
eines FinancialAccount
-Objekts festlegen, um dem Finanzkonto einen nutzerdefinierten Namen zuzuweisen. Sie können Kurznamen verwenden, um eindeutige Kennungen zu erstellen. Dies kann nützlich sein, wenn Sie mit mehreren Finanzkonten unter einem einzigen verbundenen Konto arbeiten. Damit Kurznamen gültig sind, müssen sie:
- Für jedes Finanzkonto unter einem bestimmten verbundenen Konto eindeutig sein
- Eine nicht leere Zeichenfolge sein
- Weniger als 250 Zeichen enthalten
Wenn Sie bei der Kontoerstellung keinen Kurznamen angeben, bleibt das Feld für den Kurznamen leer und gibt null
zurück. Sie können Kurznamen nach dem Erstellen eines FinancialAccount
aktualisieren.
Die folgende Anfrage erstellt ein Finanzkonto, das dem verbundenen Konto mit der in der Stripe-Account
-Kopfzeile zugeordneten ID zugewiesen ist.
Die Antwort ist ein FinancialAccount
-Objekt, um die Erstellung eines Finanzkontos zu bestätigen.
{ "object": "treasury.financial_account", "created": 1612927106, "id": "fa_123", "country": "US", "supported_currencies": ["usd"], "active_features": [ "card_issuing", ], // Features that require activation enter a pending state before activating "pending_features": [ "deposit_insurance", "financial_addresses.aba", "inbound_transfers.ach", "intra_stripe_flows", "outbound_payments.ach", "outbound_payments.us_domestic_wire", "outbound_transfers.ach", "outbound_transfers.us_domestic_wire" ], "restricted_features": [], // A FinancialAddress is not added until the financial_addresses.aba feature has been activated "financial_addresses": [], "livemode": true, "status": "open", ... }
FinancialAccount aktualisieren
Verwenden Sie POST /v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}
, um das FinancialAccount
mit der zugehörigen ID zu aktualisieren. Fügen Sie die ID des verbundenen Kontos als Wert des Headers Stripe-Account
ein. Im folgenden Beispiel werden die Metadaten des FinancialAccount aktualisiert.
FinancialAccount und Kontonummer abrufen
Verwenden Sie GET /v1/treasury/financial_accounts/{{FINANCIALACCOUNT_ID}}
, um das FinancialAccount
mit der zugehörigen ID abzurufen. Fügen Sie die zugehörige ID des verbundenen Kontos als Stripe-Account
-Kopfzeilenwert ein.
Standardmäßig ist die Kontonummer für ein Finanzkonto nicht in der Antwort enthalten. Um die Kontonummer abzurufen, fügen Sie das Feld financial_addresses.aba.account_number
in das expand
-Array ein.
Bei Erfolg wird in der Antwort das FinancialAccount
-Objekt mit oder ohne Kontonummer zurückgegeben, je nachdem ob das expand
-Array enthalten ist.
Weitere Informationen zum Parameter expand
finden Sie unter Erweiterung der Antworten.
Übersicht der Funktionen
Das FinancialAccount
-Objekt enthält eine Zusammenfassung der Zustände all seiner Features
in drei Arrays – active_features
, pending_features
und restricted_features
.
{ "object": "treasury.financial_account", "id": "fa_987", "status": "open", ... "active_features": ["card_issuing"], "pending_features": ["financial_addresses.aba"], "restricted_features": ["outbound_transfers.ach"], }
In diesen Arrays können Sie Folgendes schnell und bequem einsehen:
- Alle Funktionen, die nicht aktiv sind (
pending_features
oderrestricted_features
sind nicht leer) - Funktionen, die aktiv sind (
active_features
enthält die bestimmten Funktionen) - Eingeschränkte Funktionen, die Maßnahmen erfordern (
restricted_features
ist nicht leer)
Weitere Informationen finden Sie unter Funktionen von Finanzkonten
FinancialAccount schließen
Sie können ein Finanzkonto dauerhaft schließen, wenn es folgende Bedingungen erfüllt:
- Hat ein Null-Saldo.
- Es gibt keine ausstehenden eingehenden Zahlungen.
- Alle angehängten Issuing-Karten werden storniert.
Achtung
Finanzkonten können nach der Schließung nicht wieder geöffnet werden.
Um ein Finanzkonto zu schließen, wenden Sie sich an treasury-support@stripe.com und geben Sie die ID des FinancialAccount
an, das Sie schließen möchten, sowie den Grund für die Schließung. Sie müssen Ihrer Nutzer/innen Mitteilungen über die Kontoschließung zukommen lassen, wie in den Konformitätsrichtlinien von Treasury beschrieben.
Das Schließen eines Finanzkontos hat keine Auswirkungen auf die Datenspeicherung für zugehörige Objekte, wie z. B. Transactions
.
Sie können kein neues Finanzkonto für ein verbundenes Konto eröffnen, wenn Sie zuvor ein mit diesem verbundenen Konto verknüpftes Finanzkonto geschlossen haben. Sie müssen ein neues verbundenes Konto eröffnen, um ein neues Finanzkonto zu erstellen.
Notiz
Multiple Financial Account beta Mit der Beta-Funktion für mehrere Finanzkonten können Sie ein Finanzkonto schließen und ein neues eröffnen, das mit demselben verbundenen Konto verknüpft ist, ohne ein neues verbundenes Konto eröffnen zu müssen.
FinancialAccount-Schließung über API Beta
Nachdem Sie Zugang zum Beta-Programm erlangt haben, verwenden Sie POST/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close
, um das Finanzkonto mit der zugehörigen ID zu schließen. Fügen Sie die zugehörige ID des verbundenen Kontos als Kopfzeilenwert ein.
curl https://api.stripe.com/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close \ -u
: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"sk_test_4eC39HqLyjWDarjtT1zdp7dc
Die Antwort ist das FinancialAccount
-Objekt mit dem status
closed
, um die Aktion zu bestätigen.
{ "id": "{{FINANCIAL_ACCOUNT_ID}}", "object": "treasury.financial_account", "status": "closed", "status_details": { "closed": { "reasons": ["closed_by_platform"] } }, "active_features": [], "pending_features": [], "restricted_features": ["financial_addresses.aba"], ... }
Umgang mit Transaktionen auf geschlossene Konten
In seltenen Fällen können Finanzkonten Gutschriften oder Abbuchungen für geschlossene Konten erhalten, die Stripe nicht automatisch zurückgeben kann. Als Inhaber/in einer Plattform sind Sie für negative Salden verantwortlich, die nach der Schließung eines Kontos entstehen. Der Stripe-Support arbeitet mit Ihnen zusammen, um verbleibende Gelder an den/die Verkäufer/in oder Dienstleister/in zurückzugeben und geschlossene Konten mit einem negativen Saldo zu bereinigen.
Webhooks
Sie können das Finanzkonto erstellen, bevor Sie die Onboarding-Anforderungen erfüllen. In diesem Fall wird das Finanzkonto asynchron geöffnet und dann der Webhook treasury.financial_account.features_status_updated
mit einer aktualisierten Ansicht für alle Funktionen ausgelöst, die aufgrund ausstehender Onboarding-Anforderungen noch eingeschränkt sind.
account.updated
- Bei der Anforderung neuer Funktionen erhält die Plattform möglicherweise den Webhook
account.updated
, der Sie darüber informiert, dass sich der Anforderungs-Hash geändert hat und einige neue Felder jetzt den Statuspending_verification
haben.
- Bei der Anforderung neuer Funktionen erhält die Plattform möglicherweise den Webhook
treasury.financial_account.created
- Wird immer ausgelöst, wenn ein neues FinancialAccount erstellt wird.
treasury.financial_account.closed
- Benachrichtigt, wenn sich der Status des FinancialAccount der obersten Ebene in „geschlossen“ ändert.
treasury.financial_account.features_status_updated
- Weist darauf hin, dass eine oder mehr Funktionen ihren Status geändert haben. Dies wird in den Änderungen an den Arrays
active_features, pending_features
oderrestricted_features
widergespiegelt.
- Weist darauf hin, dass eine oder mehr Funktionen ihren Status geändert haben. Dies wird in den Änderungen an den Arrays