Weiter zum Inhalt
Konto erstellen
 oder
anmelden
Das Logo der Stripe-Dokumentation
/
Konto erstellen
Anmelden
Übersicht
Produkte
Treasury

Mit Treasury-Finanzkonten arbeiten

Verwenden Sie Finanzkonten zum Aufbewahren, Senden und Empfangen von Geldern.

Seite kopieren

Nachdem Sie API-Zugriff auf Treasury erhalten haben, fügt Stripe Ihrem Plattformkonto ein Finanzkonto hinzu und ermöglicht Ihnen die Bereitstellung von Finanzkonten für berechtigte verbundene Konten auf Ihrer Plattform. 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 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 dem Finanzkonto und den Salden des verbundenen Kontos verteilt ist. Diese beiden Guthaben bleiben getrennt, aber mit der API können Gelder vom Saldo des verbundenen Kontos zum Saldo des Finanzkontos bewegt werden.

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 jedes Feature zu überprüfen.

Bevor Sie Finanzkonten im Live-Modus für Ihre Treasury-Integration erstellen, empfehlen wir Ihnen, zunächst Finanzkonten in einer Sandbox-Umgebung zu erstellen. Test-Finanzkonten 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 des Stripe-Account-Header des Aufrufs auf, um das FinancialAccount einem verbundenen Konto zuzuordnen.

Mit Ihrem Plattformkonto und verbundenen Konten können mehrere Finanzkonten verknüpft sein. Sie können ein weiteres Finanzkonto auf Ihrem verbundenen Konto erstellen, indem Sie die ID des verbundenen Kontos als Wert in der Stripe-Account-Kopfzeile angeben. Sie können maximal 3 Finanzkonten einem einzigen verbundenen Konto zuordnen (geschlossene Finanzkonten tragen nicht zum Limit bei). Das gleiche Limit gilt für die Anzahl der Finanzkonten, die dem Plattformkonto zugeordnet sind. Wenn Sie einen höheren Schwellenwert für Ihr Konto benötigen, kontaktieren Sie treasury-support@stripe.com.

Die folgende JSON definiert die Objektstruktur des FinancialAccount:

{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "fa_123",
  "country": "US",
  "supported_currencies": ["usd"],
  // Arrays of active, pending and restricted features summarize the status of all requested features
  "active_features": ["financial_addresses.aba", "deposit_insurance"],
  "pending_features": ["inbound_transfers.ach"],
  "restricted_features": ["intra_stripe_flows", "outbound_payments.ach", "outbound_payments.us_domestic_wire"],
  "balance": {
    "cash": {"usd": 9000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 1000}
  },
  // The FinancialAccount gains a FinancialAddress once the `financial_addresses.aba` feature is active. For more information, see "Activating features"
  "financial_addresses": [
    {
      "type": "aba",
      "supported_networks": ["ach", "domestic_wire_us"],
      "aba": {
        "account_number_last4": "7890",
        // Use the expand[] parameter to view the `account_number` field hidden by default
        "account_number": "1234567890",
        "routing_number": "000000001",
        "bank_name": "Goldman Sachs"
      }
    }
  ],
  "livemode": true,
  // Financial accounts begin in the "open" state, but can be closed
  // `status_details.closed` is populated once a financial account is closed
  "status": "open",
  "status_details": {
    "closed": {
      // List of one or more reasons why the FinancialAccount was closed:
      // - account_rejected
      // - closed_by_platform
      // - other
      "reasons": [],
    }
  },
  // User-defined metadata
  "metadata": {},
  "nickname": {},
  // Restrictions that the platform can apply to the FinancialAccount
  "platform_restrictions": {
    "inbound_flows": "unrestricted",
    "outbound_flows": "restricted"
  },
}

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 den treasury-Wert 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.

Legen Sie das Feld nickname eines FinancialAccount-Objekts fest, um einen nutzerdefinierten Namen für das Finanzkonto festzulegen. Sie können Kurznamen verwenden, um Kennungen zu erstellen. Dies ist nützlich, wenn Sie mit mehreren Finanzkonten unter einem einzigen verbundenen Konto arbeiten. Gültige Kurznamen müssen wie folgt aussehen:

  • 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.

Command Line
curl https://api.stripe.com/v1/treasury/financial_accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "supported_currencies[]"=usd \
  -d nickname={{OPTIONAL_NICKNAME}} \
  -d "features[card_issuing][requested]"=true \
  -d "features[deposit_insurance][requested]"=true \
  -d "features[financial_addresses][aba][requested]"=true \
  -d "features[inbound_transfers][ach][requested]"=true \
  -d "features[intra_stripe_flows][requested]"=true \
  -d "features[outbound_payments][ach][requested]"=true \
  -d "features[outbound_payments][us_domestic_wire][requested]"=true \
  -d "features[outbound_transfers][ach][requested]"=true \
  -d "features[outbound_transfers][us_domestic_wire][requested]"=true

Die Antwort ist ein FinancialAccount-Objekt, um die Erstellung eines Finanzkontos zu bestätigen.

{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  "country": "US",
  "supported_currencies": ["usd"],
  "active_features": [
    "card_issuing",
  ],
  // Features that require activation enter a pending state before activating

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.

Command Line
curl https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "metadata[key]"=value

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.

Command Line
curl https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

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.

Command Line
curl -G https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "expand[]"="financial_addresses.aba.account_number"

Bei Erfolg wird in der Antwort das FinancialAccount-Objekt mit oder ohne Kontonummer zurückgegeben, je nachdem ob das expand-Array enthalten ist.

{
  "id": {{FINANCIAL_ACCOUNT_ID}},
  ...
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "jenny",
        "account_number": "4242424242420239",
        "account_number_last4": "0239",
        "bank_name": "Stripe Test Bank",
        "routing_number": "000000001"
      },
      ...
    }
  ],
  ...
}

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:

  • Inaktive Funktionen (die in pending_features oder restricted_features enthalten sind)
  • Aktive Funktionen (in active_features enthalten)
  • Eingeschränkte Funktionen, die Maßnahmen erfordern (in restricted_features enthalten)

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:

  • Es gibt keine ausstehenden eingehenden Zahlungen.
  • Alle angehängten Issuing-Karten werden storniert.
  • Der Kontostand ist Null und für das Konto liegt für die letzten 75 Tage keine Aktivität vor. Alternativ können Sie ein anderes Finanzkonto oder ein externes Konto angeben, an das eingehende Belastungen und Gutschriften weitergeleitet werden.

Achtung

Finanzkonten können nach der Schließung nicht wieder geöffnet werden.

Das Schließen eines Finanzkontos hat keine Auswirkungen auf die Datenspeicherung für zugehörige Objekte, wie z. B. Transactions.

FinancialAccount-Schließung mit der API

Sie können POST/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close verwenden, um das Finanzkonto mit der zugehörigen ID zu schließen. Fügen Sie die zugehörige ID des verbundenen Kontos als Wert für den Header ein.

Command Line
curl https://api.stripe.com/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"

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. Durch Einbeziehung von Weiterleitungseinstellungen beim Schließen eines Finanzkontos kann Stripe automatisch Last- und Gutschriften an das ausgewählte Konto weiterleiten.

Webhooks

Sie können Finanzkonten 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 Status pending_verification haben.
  • 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 oder restricted_features widergespiegelt.
War diese Seite hilfreich?
JaNein
Benötigen Sie Hilfe? Kontaktieren Sie den Kundensupport.
Nehmen Sie an unserem Programm für frühzeitigen Zugriff teil.
Schauen Sie sich unser Änderungsprotokoll an.
Fragen? Sales-Team kontaktieren.
LLM? Lesen Sie llms.txt.
Unterstützt von Markdoc