Mit Treasury-Finanzkonten arbeiten

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

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 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 des Stripe-Account-Header des Aufrufs auf, um das FinancialAccount einem verbundenen Konto zuzuordnen.

Verbundenen Konten können mehrere Finanzkonten zugeordnet sein, indem dieselbe ID des verbundenen Kontos als Wert im Stripe-Account-Header angegeben wird. Sie können maximal 1 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:

JSON (mit Kommentar)
{
  "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.

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. Diese können Sie nutzen, 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": "{{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.

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.

Antwort mit erweitertem Konto
{
  "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.

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.

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 \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -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.