Accounts v2 APIÖffentliche Vorschau

Erfahren Sie, wie Sie die Accounts v2-API verwenden, um Ihre verbundenen Konten auf Stripe darzustellen.

Mit der Accounts v2 API können Sie Ihre/n Nutzer/in als einzelne Entität bei Stripe darstellen.

Diese API-Struktur bietet Folgendes:

Eine einzelne Einheit, die ein verbundenes Konto für alle seine Aktivitäten über mehrere Konfigurationen hinweg darstellt
Daten zu strukturierten Identitäten über die Person oder das Unternehmen, die bzw. das durch das Konto repräsentiert werden
Variable Konfigurationen, die eine produktübergreifende Einführung und Upgrades unterstützen
Funktionen, die konfigurationsbasierte Funktionen darstellen, die von bestimmten Anforderungen abhängen

So geben Kontoaufrufe Daten zurück

Standardmäßig ruft Accounts v2 Rückgabewerte für bestimmte Eigenschaften und null für andere Eigenschaften auf, unabhängig von ihren tatsächlichen Werten. Um zusätzliche Eigenschaftswerte abzurufen, fordern Sie diese mit dem Parameter include an.

Im folgenden Beispiel wird ein Konto erstellt, ohne dass die einzuschließenden Rückgabeeigenschaften angegeben werden:

Die Antwort gibt nur Werte für Eigenschaften zurück, die standardmäßig zurückgegeben werden. Sie gibt null für andere Eigenschaften zurück, auch für diejenigen, denen die Anforderung Werte zugewiesen hat.

Response with no include
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer"
  ],
  "created": "2024-07-07T21:41:41.132Z",
  "display_name": "Furever",
  "configuration": null,
  "contact_email": "contact@test.com",
  "requirements": null,
  "identity": null,
  "defaults": null,
  "livemode": false
}

Um zusätzliche Eigenschaften in der Antwort anzugeben, geben Sie sie im Parameter include an. Bei Konfigurationen müssen Sie einzelne Konfigurationstypen explizit angeben. Jede Konfiguration, die nicht angefordert wird, gibt unabhängig von ihren Daten einen Nullwert zurück.

Im folgenden Beispiel werden die Konfigurationen customer und merchant zugewiesen, es wird jedoch nur die Konfiguration customer im Parameter include angefordert.

Die Antwort zeigt, wie durch Weglassen von configuration.merchant aus dem include-Array ein Null-Wert für die merchant-Konfiguration zurückgegeben wird, obwohl in der Anfrage Werte dafür angegeben sind. Der Wert null gibt nur an, dass der Parameter include der Anfrage diese Eigenschaft nicht angegeben hat.

Response with include but omitting merchant
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": {
    "customer": {
      "automatic_indirect_tax": {
        "exempt": "none",
        "ip_address": null,
        "location": null,
        "location_source": "identity_address"
      },
      "billing": {
        "default_payment_method": null,
        "invoice": {
          "custom_fields": [],
          "footer": null,
          "next_sequence": 1,
          "prefix": "KD5JNJLZ",
          "rendering": null
        }
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "requested": true,
          "status": "restricted",
          "status_details": [
            {
              "code": "requirements_past_due",
              "resolution": "provide_info"
            }
          ]
        }
      },
      "shipping": null,
      "test_clock": null
    },
    "merchant": null,
    "recipient": null
  },
  "requirements": "{...}"
}

Informationen zur Kontoerstellung in API v2

Wenn Sie ein Account-Objekt erstellen, müssen Sie identifizierende Informationen über die Einheit angeben, die es darstellt, und eine oder mehrere Konfigurationen definieren, die sein Verhalten steuern.

Identitätsangaben

Füllen Sie den identity-Hash mit Informationen über die Einzelperson oder das Unternehmen, die bzw. das durch das Account repräsentiert werden. Die spezifischen Parameter hängen von der Art der Entität ab.

Art der juristischen Person:

Für eine Person, die in ihrer eigenen Eigenschaft handelt, legen Sie entity_type auf individual fest und füllen Sie den Parameter individual aus. Wenn die Person ein Unternehmen besitzt und betreibt, ohne dass rechtlich zwischen ihr und dem Unternehmen unterschieden wird, legen Sie business_details.structure auch auf sole_proprietorship fest.

Sie können einem Account eine repräsentative Person hinzufügen, indem Sie ein zugehöriges Person-Objekt erstellen (siehe folgendes Beispiel).

Konfigurationen

Jedes Account verfügt über eine oder mehrere Konfigurationen, die verschiedene Personen im Unternehmen darstellen, wie z. B. Händler/innen oder Kundinnen und Kunden. Sie definieren, wie das Account mit Stripe-Produkten interagiert.

Jeder Konfigurationstyp enthält bestimmte Funktionen, die konfigurationsspezifische Funktionen aktivieren, wenn die zugehörigen Anforderungen erfüllt sind. Anstatt eine Funktion einfach zu aktivieren, fordern Sie sie an, wodurch die Erfassung der Anforderungen dieser Funktion ausgelöst wird. Die Funktion wird aktiviert, wenn Stripe überprüft, ob ihre Anforderungen erfüllt sind.

Füllen Sie den Parameter configuration des Account mit einem oder mehreren der folgenden Konfigurationstypen, je nachdem, welche Funktion Sie bereitstellen möchten.

Kunde/Kundin

Die customer-Konfiguration ermöglicht es einem verbundenen Konto, Zahlungen an Ihre Plattform zu leisten, und aktiviert Funktionen in Produkten wie Billing. Es enthält die Funktion automatic_indirect_tax und hilft Ihnen, die Informationen zu erfassen, die Sie zur Berechnung der Steuern auf die Rechnungen, Abonnements und Zahlungslinks des Account benötigen.

Händler/in

Die Konfiguration merchant erlaubt es der Steuerungsplattform, Zahlungen für das Account zu erstellen. Sie enthält die Funktion card_payments, die erforderlich ist, damit das Account Kartenzahlungen akzeptieren kann.

Empfänger/in

Die recipient-Konfiguration ermöglicht es einem Account, andere Gelder als Direktzahlungen zu erhalten, wie z. B. Auszahlungen von einer Connect-Plattform. Sie enthält die Funktion stripe_balance.stripe_transfers, mit der das Stripe-Guthaben des Account Geldtransfers empfangen kann und die für Funktionen wie Destination Charges erforderlich ist.

Funktionsweise von Funktionen

Um eine Funktion zu aktivieren, müssen Sie sie zuerst anfordern, indem Sie ihre Eigenschaft requested auf „true“ festlegen. Dies löst die Erfassung der Anforderungen der Funktion aus, die je nach den responsibilities-Eigenschaften des Account von Stripe oder Ihrer Plattform durchgeführt wird. Zu den Anforderungen können Identitäts- und Compliance-Dokumentationen sowie Risikodaten gehören. Wenn Stripe überprüft, ob die Anforderungen einer Funktion erfüllt sind, wird sie aktiv.

Anforderungen

Anforderungen beschreiben die Informationen, die Stripe benötigt, um eine Funktion für das Account zu aktivieren, und können Folgendes umfassen:

Die Art der Informationen
Warum Stripe die Informationen benötigt
Ob die Anforderung überfällig ist (die „Frist“ kann ein Datum oder eine andere Art von Schwellenwert sein, wie ein bestimmtes Zahlungsvolumen).
Konsequenzen, die Stripe bei Fristablauf verhängt, wenn wir die Informationen nicht mit akzeptablen Unterlagen verifizieren können, wie z. B. die Aussetzung bestimmter Funktionen oder die Einstellung von Auszahlungen vom Stripe-Guthaben von Account.
Wer muss Maßnahmen ergreifen?

Unternehmensvertreter/innen

Für einige Funktionen müssen Sie möglicherweise ein Person-Objekt für das Account erstellen, wobei relationship.representative auf „true“ festgelegt ist.

Zusätzlich zu den funktionsspezifischen Konsequenzen wird der status einer Funktion, wenn überfällige Anforderungen vorliegen, zurestricted, mit einem status_details.code von requirements_past_due.

Im folgenden Beispiel wird die Funktion stripe_balance.stripe_transfers angefordert, die zur recipient-Konfiguration gehört. Es wird davon ausgegangen, dass das Account bereits über die Konfiguration recipient verfügt.

To see all the requirements for an Account’s requested capabilities, retrieve the Account and specify both requirements and the assigned configuration types in the include parameter.

Das folgende Beispiel gibt den Status und die Anforderungen für Funktionen zurück, die zur recipient-Konfiguration gehören.

In der Beispielantwort wurde die Funktion stripe_balance.stripe_transfers angefordert, aber ihre Anforderungen sind überfällig. Da in der Anfrage nicht nach den Konfigurationen customer oder merchant gefragt wurde, werden NULL-Werte zurückgegeben, auch wenn diese in Account definiert sind.

Capability activation response showing requirements
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "recipient"
  ],
  "configuration": {
    "customer": null,
    "merchant": null,
    "recipient": {
      "capabilities": {
        ...
        "stripe_balance": {
          "payouts": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          },
          "stripe_transfers": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          }
        }
      },
      ...
    }
  },
  "contact_email": "furever_contact@example.com",
  "created": "2025-04-01T20:29:43.000Z",
  "dashboard": "full",
  "identity": null,
  "defaults": null,
  "display_name": "Furever",
  "metadata": {},
  "requirements": {
    "collector": "stripe",
    "entries": [
      {
        "awaiting_action_from": "user",
        "description": "identity.business_details.address.country",
        "errors": [],
        "impact": {
          "restricts_capabilities": [
            {
              "capability": "card_payments",
              "configuration": "merchant",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.stripe_transfers",
              "configuration": "recipient",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.payouts",
              "configuration": "recipient",
              "deadline": {
                "status": "past_due"
              }
            }
          ]
        },
        "minimum_deadline": {
          "status": "past_due"
        },
        "reference": null,
        "requested_reasons": [
          {
            "code": "routine_onboarding"
          }
        ]
      },
    ...
    ],
    "summary": {
      "minimum_deadline": {
        "status": "past_due",
        "time": null
      }
    }
  }
}

Die folgenden Variablen wirken sich auf die Anforderungen aus, die an ein Account gestellt werden:

Angeforderte Funktionen
Das Ursprungsland von Account
Der Entitätstyp von Account

impact einer Anforderung beschreibt, wie sich die Fähigkeiten verändern, wenn diese Anforderung überfällig ist. minimum_deadline.status ist der früheste Terminstatus für alle in seiner impact aufgeführten Funktionen. Um die Erfassung der Anforderungen zu priorisieren, überprüfen Sie den deadline.status für jede Auswirkung.

Die meisten Stripe-Nutzer/innen erfüllen die Anforderungen beim Konto-Onboarding. Unabhängig davon, welchen Onboarding-Ablauf Sie verwenden, können Sie zwischen zwei Strategien wählen:

Inkrementell: Sammeln Sie während des Onboardings nur die Mindestanforderungen, d. h. diejenigen mit dem Status currently_due oder past_due.
Im Voraus: Erfassen Sie alle Anforderungen während des Onboardings, unabhängig von ihrem Fälligkeitsstatus.

Aktualisierungen der Anforderungen überwachen

Da sich Gesetze und Vorschriften jederzeit ändern können, aktualisiert Stripe unsere Compliance- und Risikosysteme kontinuierlich. Dies kann sich auf die Anforderungen an die Funktionen Ihrer verbundenen Konten auswirken. Um Unterbrechungen ihrer Geschäftsabläufe zu vermeiden, müssen Sie ihre Fähigkeiten und Anforderungen kontinuierlich überwachen und Prozesse implementieren, um die Anforderungen bei Bedarf zu aktualisieren.

In v1-Anfragen auf Accounts v2-Objekte verweisen

Sie können in anderen Stripe-APIs entweder in einem account- oder in einem customer_account-Parameter auf eine v2 Konto-ID verweisen.

Eine Anfrage mit einem customer-Parameter kann die ID eines v2 Account akzeptieren, aber Sie müssen sie im customer_account-Parameter anstelle des customer-Parameters angeben. Das Account muss die Konfiguration customer haben.
Eine Anfrage mit einem account-Parameter kann die ID eines beliebigen v2 Account in diesem Parameter akzeptieren.

Informationen für Nutzer/innen von Accounts v1

Wenn Ihre Plattform derzeit Accounts v1 und Customers v1 verwendet, können Sie zusätzlich dazu Accounts v2 verwenden. Sie können jedoch API v2 nicht verwenden, um Account- und Customer-Objekte zu verwalten, die in API v1 erstellt wurden. Ihre Plattform muss v1- und v2-Objekte separat verarbeiten.

Preview considerations

Accounts v2 allows you to use a single, configurable account for each business on your platform that collects payments directly. The preview release doesn’t support Treasury, Issuing, or payment methods that are in preview. You can still use Treasury, Issuing, or payment methods in preview with Accounts v1.

Enable Accounts v2 for your Connect platform from your Dashboard.