# Darstellung von Kunden/Kundinnen mit Account-Objekten Verwalten Sie Ihre Kundschaft mit der Accounts v2 API anstelle der Customers API. Die Accounts v2 API verwendet *Konfigurationen* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient), um die Funktionalität für `Account`-Objekte zu aktivieren. Wenn Sie die v2 API verwenden, können Sie eine Kundin/einen Kunden darstellen, die/der ein `Account`-Objekt anstelle eines `Customer`-Objekts verwendet, indem Sie dem `Account` die [Kundenkonfiguration](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) zuweisen. Wenn Sie eine Anfrage stellen, die eine `Customer`-ID als Argument für den Parameter `customer` akzeptiert, geben Sie stattdessen die `Account`-ID als Argument für den Parameter `customer_account` an. Im folgenden Beispiel wird ein `Account` mit der Konfiguration `customer` erstellt und die allgemeine Funktion `automatic_indirect_tax` angefordert, die Teil der `customer`-Konfiguration ist. Die Anforderung der Funktion ist optional. Sie können die Konfiguration einfach hinzufügen, indem die `configuration.customer` festlegen. ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: $latestPreviewApiVersion" \ --json '{ "contact_email": "jenny.rosen@example.com", "display_name": "Jenny Rosen", "identity": { "country": "us", "individual": { "given_name": "Jenny Rosen" } }, "configuration": { "customer": { "capabilities": { "automatic_indirect_tax": { "requested": true } } } }, "include": [ "configuration.customer", "identity" ] }' ``` Wenn Sie die Accounts v2 API aktivieren, erstellen Ihre von Stripe gehosteten Integrationen, wie Checkout, `Accounts` mit der `customer`-Konfiguration anstelle von `Customer`-Objekten. Wenn Ihr Code auf `Customer`-Objekte verweist, empfehlen wir, ihn stattdessen auf kundenkonfigurierte `Account`-Objekte umzustellen. | Zweck | v1-Referenz | v2-Referenz | | -------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Kundenreferenz | `customer` | `customer_account` | | Kundenidentifikation | `cus_xxxxx` | `acct_xxxxx` | | Rechnungsadresse festlegen | [address](https://docs.stripe.com/api/customers/create.md#create_customer-address) | - [identity.individual.address](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-identity-individual-address), wenn der Entitätstyp `individual` ist. - [identity.business_details.address](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-identity-business_details-address), wenn der Entitätstyp ein anderer als `individual` ist. | | Versandadresse festlegen | [shipping](https://docs.stripe.com/api/customers/create.md#create_customer-shipping) | [configuration.customer.shipping](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-shipping) | ## Konto als Kunde/Kundin angeben API-Anfragen wie `Subscriptions` und `SetupIntents` erfordern die Angabe einer Kundin/eines Kunden. Diese Anfragen akzeptieren entweder den Parameter `customer` oder `customer_account`. Im folgenden Beispiel wird ein Abonnement erstellt, das die Kundin/den Kunden angibt, indem es eine `Account`-ID als `customer_account` übergibt. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: $latestPreviewApiVersion" \ -d customer_account=acct_xxxxx \ -d "items[0][price]=price_CBb6IXqvTLXp3f" \ -d "items[0][quantity]=5" ``` ## Referenzkonten in Customers v1-Integrationen Eine Anfrage, die `customer_account` angibt, gibt sowohl die Eigenschaften `customer` als auch `customer_account` mit entsprechend formatierten Werten zurück. Dadurch wird die Kompatibilität mit bestehenden Billing- und Payments-Integrationen gewahrt. ```javascript { "id": "sub_1Mow234", . . . "customer": "cus_xxxxx", "customer_account": "acct_xxxxx" } ``` Sie können von Kundinnen/Kunden konfigurierte Konten auch über den Endpoint `/v1/customers` abrufen oder aktualisieren. ```curl curl -X POST https://api.stripe.com/v1/customers/acct_1234 \ -u "<>:" ``` ## Accounts v2-Webhooks Webhooks für Accounts v2 senden [Thin-Ereignisse](https://docs.stripe.com/event-destinations.md#thin-events). | Aktion | v1-Event | v2-Event | | ----------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Kunde/Kundin wurde erstellt | `customer.created` | Accounts v2 sendet separate Ereignisse, die die Kontoerstellung und die Kundenkonfiguration angeben: - `v2.core.account.created` - `v2.core.account[configuration.customer].updated` | | Rechnungsadresse aktualisiert | `customer.updated` | `v2.core.account[identity].updated` | | Abonnement-Aktionen | `customer.subscription.[action]` | Keine; v1-Ereignis verwenden | | Kunde/Kundin gelöscht | `customer.deleted` | `v2.core.account.closed` | ## Eigenschaften der Kundenrechnungen | Datenwert | Eigenschaft Customers v1 | Accounts v2-Eigenschaft | | ---------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Gespeichertes Kundenguthaben | `invoice_credit_balance` | Keine; Weitere Informationen finden Sie unter [Auf eine Accounts v2-ID in einem v1/customers-Pfadparameter verweisen](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md#reference-accounts-v2-in-v1-customers-path) | | Rechnungspräfix für Kundinnen und Kunden | `invoice_prefix` | [configuration.customer.billing.invoice.prefix](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-prefix) | | Nutzerdefinierte Einstellungen | `invoice_settings.custom_fields` | [configuration.customer.billing.invoice.custom_fields](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-custom_fields) | | Standard-Zahlungsmethode | `invoice_settings.default_payment_method` | [configuration.customer.billing.default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-response-configuration-customer-billing-default_payment_method) | | Fußzeile der Rechnung | `invoice_settings.footer` | [configuration.customer.billing.invoice.footer](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer-billing-invoice-footer) | | Optionen für die Rechnungsdarstellung | `invoice_settings.rendering_options` | [configuration.customer.billing.invoice.rendering.template](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer-billing-invoice-rendering-template) | ## Referenzieren einer Account-ID mit einem Customers-Endpoint Die Accounts v2 API verfügt nicht über Endpoints für alle Kundenfunktionen. Um die folgenden Aktionen für ein `Account`-Objekt auszuführen, verwenden Sie den Endpoint `v1/customers` und übergeben Sie die `Account`-ID (`acct_xxxxx`) als Pfadparameter. | Anwendungsszenario | v1-Endpoint mit Konto-ID | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Barguthaben verwalten | - `v1/customers/acct_xxxxx/cash_balances` - `v1/customers/acct_xxxxx/cash_balances/:id` | | Barguthaben-Transaktionen verwalten | - `GET v1/customers/acct_xxxxx/cash_balance_transactions` - `GET v1/customers/acct_xxxxx/cash_balance_transactions/:id` - `POST v1/test_helpers/customers/acct_xxxxx/fund_cash_balance` - `POST v1/customers/acct_xxxxx/funding_instructions` - `GET v1/customers/acct_xxxxx/funding_instructions` | | Rechnungsguthaben verwalten Bei `Account`-Objekten entspricht das [ending_balance](https://docs.stripe.com/api/invoices/object.md?api-version=preview#invoice_object-ending_balance) der zuletzt finalisierten Rechnung des Kontos der `invoice_credit_balance` des `Customer`-Objekts. | - `POST v1/customers/acct_xxxxx/balance_transactions` - `POST v1/customers/acct_xxxxx/balance_transactions/:id` - `GET v1/customers/acct_xxxxx/balance_transactions/:id` - `GET v1/customers/acct_xxxxx/balance_transactions` | ## Eigentumskarte der Customer-Account-Eigenschaft In der folgenden Tabelle wird beschrieben, wie die Eigenschaften der `Customer`-Objekte den Eigenschaften von kundenkonfigurierten `Account`-Objekten entsprechen. Sofern nicht anders angegeben, kopiert Stripe die zugeordneten Werte, wenn ein `Account` erstellt wird, das einer/einem bestehenden `Customer` entspricht. Zugeordnete Werte bleiben synchronisiert. Wenn Sie beispielsweise `identity.country` für ein `Account` festlegen, enthält das zurückgegebene `country` denselben Wert, wenn Sie dieses `Account` als `customer_account` an einen v1-Endpoint übergeben. | Eigenschaft Customers v1 | Accounts v2-Eigenschaft | Hinweise | | ------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | {alle Eigenschaften} | `identity.business_details.address` oder `identity.individual.address` | Wenn Stripe eine/n v1-`Customer` mit einem v2-`Account` verknüpft, wird die `address` nur dann aufgenommen, wenn sie die Validierung besteht. `address.country` (Zeichenfolge in v1 und Enum in v2) wird nur aufgenommen, wenn es entweder mit einer gültigen Enumeration oder einem Ländernamen übereinstimmt, wobei Groß-/Kleinschreibung und etwaige Sonderzeichen ignoriert werden. | | `country` | `identity.country` | Wenn Stripe eine/n v1-`Customer` mit einem v2-`Account` verknüpft, wird `address.country` (Zeichenfolge) nur dann in `identity.country` (enum) kopiert, wenn es entweder mit einer gültigen Enumeration oder einem Ländernamen übereinstimmt, wobei Groß-/Kleinschreibung und etwaige Sonderzeichen ignoriert werden. | | `business_name` | `identity.business_details.registered_name` | | | `created` | {nicht abgebildet} | Wenn Stripe eine/n v1 `Customer` einem v2 `Account` zuordnet, spiegelt die `created` Eigenschaft des `Account`s den Zeitstempel wider, zu dem das `Account` erstellt wurde, nicht die/den ursprüngliche/n `Customer`. | | `currency` | {nicht abgebildet} | Die `defaults.currency`-Eigenschaft des v2 `Account`s ist nicht auf die `customer`-Konfiguration anwendbar. | | `customer_account` | `id` | Wenn Stripe eine/n v1 `Customer` mit einem v2 `Account` verknüpft, enthält die Eigenschaft `customer_account` des/der `Customer` die ID dieses `Accounts`. Die `Customer`-ID ist im `Account` nicht verfügbar. Nutzer/innen, die v2 `Accounts` erstellen, die Kundinnen und Kunden darstellen, müssen keine v1 `Customer`-ID verwenden. | | `description` | {nicht abgebildet} | Die `description` v1 `Customer` ist für das v2 `Account` nicht verfügbar. Sie wird jedoch (schreibgeschützt) auf der Seite der Kundendaten im Dashboard angezeigt. | | `email` | `contact_email` | | | `id` | {nicht abgebildet} | Die ID der/des v1 `Customer` ist im v2 `Account` nicht verfügbar. Nutzer/innen, die v2 `Accounts` erstellen, die Kundinnen/Kunden repräsentieren, müssen keine v1 `Customer`-ID verwenden. | | `individual_name` | `display_name` | Wenn Stripe eine/n v1 `Customer` mit einem v2 `Account` verknüpft, wird `individual_name` nur kopiert, wenn der `Customer`-`name` Null ist. | | `invoice_prefix` | `configuration.customer.billing.invoice.prefix` | | | `invoice_settings` | `custom_fields` | `configuration.customer.billing.invoice.custom_fields` | Das Array `Account` ist auf 4 Elemente beschränkt. | | `default_payment_method` | `configuration.customer.billing.invoice.default_payment_method` | | | `footer` | `configuration.customer.billing.invoice.footer` | | | `rendering_options` | `configuration.customer.billing.invoice.rendering` | Wenn Stripe eine/n v1 `Customer` mit einem v2 `Account` verknüpft, wird `invoice_settings.rendering_options.amount_tax_display` (Zeichenfolge) nur in `configuration.customer.billing.invoice.rendering.amount_tax_display` (enum) kopiert, wenn sie mit einem Enumerationswert übereinstimmt (`include_inclusive_tax` oder `exclude_tax`). | | `livemode` | `livemode` | | | `metadata` | `metadata` | | | `name` | `display_name` | Wenn Stripe eine/n v1- `Customer` mit einem v2- `Account` verknüpft, wird der `individual_name` der/des `Customer` in `display_name` kopiert, wenn der `name` Null ist. | | `next_invoice_sequence` | `configuration.customer.billing.invoice.next_sequence` | | | `phone` | `identity.business_details.phone or identity.individual.phone` | | | `preferred_locales` | `defaults.locales` | Bei der `Customer`-Eigenschaft `preferred_locales` handelt es sich um ein nullfähiges Array von Zeichenfolgen, und bei der `Account`-Eigenschaft `defaults.locales` handelt es sich um ein nullfähiges Array aus Enumerationen. Wenn Stripe eine/n v1 `Customer` einem v2 `Account` zuordnet, wird eine bestimmte Zeichenfolge `preferred_locales` nur dann aufgenommen, wenn sie mit dem Enum-Wert `defaults.locales` übereinstimmt, wobei Groß- und Kleinschreibung und etwaige Sonderzeichen ignoriert werden. | | `shipping` | `configuration.customer.shipping` | | | `subscriptions` | {nicht abgebildet} | Das v2 `Account`-Objekt enthält kein Array aus Abonnements. Um die Abonnements einer Kundin/eines Kunden abzurufen, verwenden Sie die Subscriptions API und filtern Sie nach `customer` oder `customer_account`. | | `tax` | `automatic_tax` | `configuration.customer.capabilities.automatic_indirect_tax.status` {Wert nicht synchronisiert} | Die `Account`-Eigenschaft ist nur verfügbar, nachdem die Funktion „Automatische indirekte Steuern“ angefordert wurde. Sie verfügt auch über keine Entsprechung für den Wert `not_collecting` der `Customer`-Eigenschaft. Sie gibt nur den Status der Funktion an. | | `ip_address` | `configuration.customer.automatic_indirect_tax.ip_address` | | | `location` | `configuration.customer.automatic_indirect_tax.location` {Wert nicht synchronisiert} | Wenn Stripe eine/n v1 `Customer` mit einem v2 `Account` verknüpft, ist der `tax.location` nicht automatisch enthalten. Sie müssen die Funktion „Automatische indirekte Steuern“ anfordern, um `configuration.customer.automatic_indirect_tax.location` festzulegen. | | `provider` | {nicht abgebildet} | Wenn ein/e `Customer` mit einem Drittanbieter für Steuern verbunden ist, verknüpft Stripe diese/n `Customer` nicht automatisch mit einem `Account`. | | `tax_exempt` | `configuration.customer.automatic_indirect_tax.exempt` | | | `tax_ids` | {nicht abgebildet} | Das v2 `Account`-Objekt enthält kein Array mit Steueridentifikationsnummern. Um die Steueridentifikationsnummer eines Kunden/einer Kundin abzurufen, verwenden Sie die Tax IDs API und filtern Sie nach `owner.customer` oder `owner.customer_account`. | | `test_clock` | `configuration.customer.test_clock` | | ## Accounts v2-Vorschau aktivieren Zuvor war die Accounts v2 API nur für Connect-Plattformen verfügbar. Jetzt steht sie allen Stripe-Nutzerinnen und -Nutzern in der Vorschau zur Verfügung. Accounts v2 bietet eine einheitliche Möglichkeit, Ihre Nutzer/innen über verschiedene Stripe-Produkte hinweg abzubilden. Anstelle von `Customer`-Objekten, die hauptsächlich zum Speichern von Zahlungsmethoden und für wiederkehrende Zahlungen dienen, können Sie `Account`-Objekte verwenden. Diese bieten durch den Einsatz von Konfigurationen deutlich mehr Flexibilität, wenn zusätzliche Funktionalitäten benötigt werden. So aktivieren Sie die Vorschau: 1. Gehen Sie in Ihrem Dashboard zu [Kontovorschau und Funktionen](https://dashboard.stripe.com/settings/features/product-previews). 1. Aktivieren Sie den Schalter **Wiederverwendbare Zahlungsmethoden für globale Auszahlungen**. Falls der Schalter nicht angezeigt wird, beantragen Sie bitte über das Formular oben auf dieser Seite Zugriff. Wenn Sie sich für die Vorschau anmelden, werden Ihre bestehenden `Customer`-Objekte automatisch mit entsprechenden, kundenseitig konfigurierten `Account`-Objekten (v2) synchronisiert. Wenn Sie im Dashboard eine/n neue/n Kundin/Kunden erstellen, wird ein kundenseitig konfiguriertes `Account`-Objekt erzeugt und kein `Customer`-Objekt. Diese `Accounts` können Sie in den [meisten Integrationen verwenden, die auf Kundenobjekte](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md#reference-accounts-in-customers-v1-integrations) verweisen. Durch das Aktivieren der Accounts v2-Vorschau werden auch [wiederverwendbare Zahlungsdaten für Global Payouts](https://docs.stripe.com/global-payouts/credential-reuse.md) aktiviert. Damit können Sie Zahlungsmethoden speichern und über Global-Payouts-Transaktionen hinweg wiederverwenden. ## Einschränkungen und Deaktivierung Die Accounts v2-Vorschau unterstützt derzeit folgende Funktionen nicht: - [Klonen von Kundinnen und Kunden](https://docs.stripe.com/get-started/data-migrations/pan-copy-self-serve.md) - [Teilen von Kundinnen und Kunden sowie Zahlungsmethoden innerhalb einer Organisation](https://docs.stripe.com/get-started/account/orgs/sharing/customers-payment-methods.md) - Drittanbieter-Steuerintegrationen (Stripe Tax wird unterstützt) Um diese Funktion zu deaktivieren, schalten Sie den Schalter unter [Konto-Vorschau und Funktionen](https://dashboard.stripe.com/settings/features/product-previews) aus. Durch die Deaktivierung werden bestehende `Customer`-Objekte, die bereits mit v2-`Account`-Objekte verknüpft sind, nicht zurückgesetzt. Wenn Sie für diese Kundinnen und Kunden nicht unterstützte Funktionen benötigen, müssen Sie für sie neue `Customer`-Objekte anlegen.