# Integrationsleitfaden für eingebettete Stripe-Apps Verwenden Sie eingebettete Komponenten für Stripe-Apps, damit Ihre Kundinnen/Kunden Zahlungsdaten in Anwendungen von Drittanbietern verwalten können. Kundinnen/Kunden erwarten, dass ihre Zahlungsdaten in den Tools, die sie bereits verwenden, um ihre Geschäftsabläufe durchzuführen, unkompliziert zugänglich sind. Eingebettete Komponenten für Apps ermöglichen es Ihren Kundinnen/Kunden, Anwendungen von Drittanbietern in Stripe zu verwenden. Mit eingebetteten Komponenten für Apps können Sie Integrationen, die für Stripe entwickelt wurden, in Ihre Plattform einbetten und Ihren Kundinnen und Kunden ermöglichen, ihre bevorzugten Drittanbieteranwendungen zu verwenden, ohne Stripe zu verlassen. Verwenden Sie vorgefertigte Komponenten der Nutzeroberfläche, die Daten direkt mit Anwendungen wie QuickBooks und Xero synchronisieren. ## Integration mit den in Connect eingebetteten Komponenten [Richten Sie Connect.js ein](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), um die Möglichkeit zu schaffen, die Dashboard-Funktionalität für verbundene Konten zu Ihrer Website hinzuzufügen. Eingebettete Stripe Apps verwendet private Vorschaukomponenten, die die Nutzung von Vorschauversionen der Stripe-SDKs erfordern. Erfahren Sie mehr über [Komponenten privater Vorschauen](https://docs.stripe.com/connect/supported-embedded-components.md#preview-components). ## Wählen Sie die App aus, die integriert werden soll Stripe unterstützt die folgenden App-Integrationen. | App-Integration | App-ID | | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- | | [QuickBooks Sync von Acodei](https://docs.stripe.com/stripe-apps/embedded-apps/accounting-integrations.md#quickbooks-sync-by-acodei) | com.example.acodeistripeapp | | [Xero-Synchronisation durch Xero](https://docs.stripe.com/stripe-apps/embedded-apps/accounting-integrations.md#xero) | com.xero.stripeapp | | [Mailchimp](https://docs.stripe.com/stripe-apps/embedded-apps/marketing-integrations.md#mailchimp) | mailchimp | ## App-Installation einrichten Rendern Sie die eingebettete App-Installationskomponente für die ausgewählte App. Die App-Installation erteilt der Drittanbieter-App die Berechtigung, auf die Stripe-Daten Ihrer Nutzer/innen zuzugreifen und eine Verbindung zwischen Ihrer Plattform, Stripe und der Drittanbieter-App herzustellen. Die Komponente hat zwei Zustände: `uninstalled` und `installed`. Überwachen Sie die Installation von Ereignisauslösern, um Ihren nutzerdefinierten UX-Ablauf zu erstellen oder Aktualisierungen in Ihrem eigenen Backend vorzunehmen. Aktivieren Sie beim [Erstellen einer Kontositzung](https://docs.stripe.com/api/account_sessions/create.md) die App-Installation und das Rendering, indem Sie `app_install` und `app_viewport` im Parameter `components` angeben. Sie müssen die App, die Sie anzeigen möchten, aktivieren, indem Sie den Parameter `features` unter `allowed_apps` angeben. ```curl curl https://api.stripe.com/v1/account_sessions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview; embedded_connect_beta=v2;" \ -d account={{CONNECTED_ACCOUNT_ID}} \ -d "components[app_install][enabled]=true" \ -d "components[app_install][features][allowed_apps][]=APP_ID" \ -d "components[app_viewport][enabled]=true" \ -d "components[app_viewport][features][allowed_apps][]=APP_ID" ``` Nachdem Sie die Kontositzung erstellt und [ConnectJS initiiert haben](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), können Sie die Installationskomponente der App im Frontend anzeigen: #### JavaScript ```js const appInstall = stripeConnectInstance.create('app-install'); appInstall.setApp('{{APP_ID}}'); container.appendChild(appInstall); ``` Diese eingebettete Komponente unterstützt die folgenden Parameter: #### HTML + JS | Methode | Typ | Beschreibung | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setApp` | `string` | Legt die ID der App fest, die Ihr verbundenes Konto installieren kann. Siehe die Liste der [verfügbaren Apps](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select). | #### React | React-Eigenschaft | Typ | Beschreibung | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `app` | `string` | Die ID der App, die Ihre verbundenen Konten installieren können. Siehe die Liste der [verfügbaren Apps](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select). | Sie können ein nutzerdefiniertes Verhalten basierend auf dem aktuellen oder aktualisierten Status einer Installation konfigurieren. #### JavaScript ```js // index.html
// index.js // Do something when install state fetched on render const handleAppInstallFetched = (response) => { console.log(`Install state fetched for app ${response.appId} to ${response.state}`); }; // Do something when install state changes const handleAppInstallChanged = (response) => { console.log(`Install state changed for app ${response.appId} to ${response.state}`); }; const container = document.getElementById('app-install-container'); const appInstall = stripeConnectInstance.create('app-install'); appInstall.setApp('{{APP_ID}}'); appInstall.setOnAppInstallStateFetched(handleAppInstallFetched); appInstall.setOnAppInstallStateChanged(handleAppInstallChanged); container.appendChild(appInstall); ``` #### HTML + JS | Methode | Beschreibung | Variablen | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `setOnAppInstallStateFetched` | Ermöglicht Nutzerinnen/Nutzern, nutzerdefiniertes Verhalten in einer Rückruffunktion beim Installationsabruf anzugeben. | - `response.appId`: Die installierte App - `response.state`: Der Status der Installation `INSTALLED | UNINSTALLED` | | `setOnAppInstallStateChanged` | Ermöglicht Nutzerinnen/Nutzern, nutzerdefiniertes Verhalten in einer Rückruffunktion anzugeben, wenn sich der Installationsstatus geändert hat. | - `response.appId`: Die installierte App - `response.state`: Der Status der Installation `INSTALLED | UNINSTALLED` | #### React | React-Eigenschaft | Beschreibung | Variablen | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `onAppInstallStateFetched` | Ermöglicht Nutzerinnen/Nutzern, nutzerdefiniertes Verhalten in einer Rückruffunktion beim Installationsabruf anzugeben. | - `response.appId`: Die installierte App - `response.state`: Der Status der Installation `INSTALLED | UNINSTALLED` | | `onAppInstallStateChanged` | Ermöglicht Nutzerinnen/Nutzern, nutzerdefiniertes Verhalten in einer Rückruffunktion anzugeben, wenn sich der Installationsstatus geändert hat. | - `response.appId`: Die installierte App - `response.state`: Der Status der Installation `INSTALLED | UNINSTALLED` | ## App-Einstellungen einrichten Rendern Sie die eingebettete Komponente des App-Darstellungsfelds für Ihre ausgewählte App, um die Kernfunktionalität der App zu aktivieren. Dies umfasst auch die Verbindung mit dem Konto der Software der App mit OAuth, Onboarding, Einstellungen sowie die Konfiguration des Diensts und Synchronisierungsstatus von Transaktionen. Übergeben Sie die `user_id` (auf Ihrer Plattform dargestelltes Unternehmen) als optionales HTML-Attribut, mit dem Apps von Drittanbietern eine dynamische URL erstellen können. Nach dem OAuth-Vorgangwird dadurch eine Weiterleitung zum Nutzer-Dashboard vorgenommen. #### JavaScript ```js const appViewport = stripeConnectInstance.create('app-viewport'); appViewport.setApp('{{APP_ID}}'); appViewport.setAppData({userId: '{{PLATFORM_USER_ID}}'}); container.appendChild(appViewport); ``` Diese eingebettete Komponente unterstützt die folgenden Parameter: #### HTML + JS | Methode | Typ | Beschreibung | | ------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setApp` | `string` | Legt die ID der App fest, die Ihr verbundenes Konto darstellen kann. Verfügbare Apps finden Sie im [Integrationsleitfaden für eingebettete Stripe-Apps](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select). | | `setAppData` | `Record` | Legt Daten fest, die sich auf Ihre Plattform beziehen und von der App genutzt werden. | #### React | React-Eigenschaft | Typ | Beschreibung | | ----------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `app` | `string` | Die ID der App, die Ihre verbundenen Konten darstellen können. Siehe [verfügbare Apps](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select). | | `appData` | `Record` | Daten, die sich auf Ihre Plattform beziehen und von der App genutzt werden. | ## Für Connect-Ziel im Auftrag von (OBO) anpassen Um sicherzustellen, dass Ihre ausgewählte App die Transaktionsdaten ordnungsgemäß verarbeitet, müssen Sie die Destination Charge für das verbundene Konto mithilfe des standardisierten Datenschemas aktualisieren. Es ist wichtig, dass Ihre Plattform bei jedem Zahlungsereignis mindestens ein [Kundenobjekt](https://docs.stripe.com/api/customers/object.md) (insbesondere die Kunden-ID) übermittelt. Diese Anforderung ist wichtig, da das Ereignis `charge.updated` für eine einzelne Transaktion möglicherweise mehrmals gesendet wird. Die Drittanbieter-App liest und verarbeitet jedoch nur Ereignisse, die eine Kunden-ID enthalten. Fügen Sie immer die Kunden-ID in die Nutzlast ein, um zu bestätigen, dass die App die entsprechende Transaktion verarbeitet. Es gibt drei Szenarien, bei denen Sie Ihre Destination Charge aktualisieren müssen: - Einmalige Zahlung abgeschlossen - Wiederkehrende Zahlung abgeschlossen - Zahlung zurückerstattet #### Buchhaltung | Feld- oder Schlüsselname | Format (es gelten die Standard-CSV-Regeln) | Beschreibung | Pflichtfeld | | ---------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | [charges.customer](https://docs.stripe.com/api/charges/object.md#charge_object-customer) | Zeichenfolge (ID) | Stripe-Kunden-ID (die zum verbundenen Konto gehört) mit einem Ziel-`Charge`-Objekt verknüpft ist. Transaktionen werden nicht mit Apps wie Xero und QBO synchronisiert, wenn dieses Feld nicht vorhanden ist. | Pflichtfeld | | [customer.name](https://docs.stripe.com/api/customers/object.md#customer_object-name) | Zeichenfolge | Vollständiger Name des Kunden/der Kundin | | | [customer.email](https://docs.stripe.com/api/customers/object.md#customer_object-email) | Zeichenfolge | E-Mail-Adresse des Kunden/der Kundin | | | [customer.address.<>](https://docs.stripe.com/api/customers/object.md#customer_object-address) | Zeichenfolge (mehrere Felder) | Physische Adresse des Kunden/der Kundin (kann sowohl für die Rechnungsstellung als auch für den Versand verwendet werden) | | | `charges.metadata.[refund_amount]` | Zeichenfolge (Cent-Ganzzahl) | [charges.amount_refunded](https://docs.stripe.com/api/charges/object.md#charge_object-amount_refunded) in Basiswährungseinheiten spiegeln (‘350’ = 3,50 USD) | Erforderlich für die Quickbooks Online-Synchronisierung von Acodei | | `charges.metadata.[refund_reason]` | Zeichenfolge | Grund für die Rückerstattung | | | `charges.metadata.[currency_converted]` | `true` | `false` | `null` | Auf `true` setzen, wenn die Währung umgerechnet wurde, z. B. wenn die Transaktionswährung von der Abrechnungswährung abweicht | Erforderlich für die Quickbooks Online-Synchronisierung durch Acodei bei Verwendung von fees_names-Metadaten | | `customer.metadata.[platform_customer_ID]` | Zeichenfolge | Kunden-ID, wie im System der Plattform erfasst* | | | `charges.metadata.[platform_product_ID]` | Zeichenfolge, CSV, mehrere Produkte | Produkt-IDs, wie im System der Plattform erfasst | | | `charges.metadata.[platform_product_name]` | Zeichenfolge, CSV, mehrere Produkte | Produktname, wie im System der Plattform erfasst | | | `charges.metadata.[platform_product_quantity]` | Zeichenfolge, CSV, mehrere Produkte | Menge jedes Produkts, das dem Array der ID und dem Namen entspricht | | | `charges.metadata.[platform_product_value]` | Ganzzahl, CSV, mehrere Produkte | Der individuelle Produktwert (Preis oder Kosten), der der Produkt-ID und dem Produktnamen entspricht. Untereinheiten der Basiswährung (‘350’ = 3,50 USD) | | | `charges.metadata.[platform_product_tag]` | Zeichenfolge, CSV, mehrere Produkte | Produkt-Tag oder -Kategorie, die dem Array der ID und dem Namen entspricht | | | `charges.metadata.[platform_order_ID]` | Zeichenfolge | Auftrags-ID, wie im System der Plattform erfasst | | | `charges.metadata.[platform_charge_ID]` | Zeichenfolge | Zahlungs- oder Transaktions-ID, wie im System der Plattform erfasst und für das Unternehmen sichtbar | | | `charges.metadata.[fees_names]` | Zeichenfolge, CSV, mehrere Gebühren | Name der Gebühren, die der/die Nutzer/in im Zusammenhang mit der Transaktion zahlt (Kosten), die nicht in der Gebühr erfasst werden (z. B. Bearbeitungsgebühr oder Plattformgebühr) *Wenn dieses Feld ausgefüllt ist, wird die charges.application\_fee ignoriert.* | | | `charges.metadata.[fees_values]` | Ganzzahl, CSV, mehrere Gebühren | Wert der Gebühren, die der/die Nutzer/in im Zusammenhang mit der Transaktion zahlt (Kosten), die nicht in der Zahlung erfasst werden, z. B. Kreditkartenbearbeitungsgebühr oder Plattformgebühr. Untereinheiten der Basiswährung (‘350’ = 350 USD) | | | `charges.metadata.[revenues_names]` | Zeichenfolge, CSV, mehrere Einnahmen | Gebühren (Einnahmen), die das Unternehmen im Zusammenhang mit dieser Transaktion (Gebühr) erhebt und die nicht in der Gebühr erfasst werden (zum Beispiel Gebühren für Bedarfsartikel oder Trinkgelder) | | | `charges.metadata.[revenues_values]` | Ganzzahl, CSV, mehrere Einnahmen | Werte der vom Unternehmen im Zusammenhang mit dieser Transaktion (Zahlung) erhobenen Gebühren (Einnahmen). Untereinheiten der Basiswährung (‘350’ = 3,50 USD) | | | `charges.metadata.[total_tax]` | Ganzzahl | Steuern insgesamt im Zusammenhang mit dieser Transaktion (Zahlung). Untereinheiten der Basiswährung (‘350’ = 3,50 USD) | | | `charges.metadata.[tax_names]` | Zeichenfolge, CSV, mehrere Steuern | Einer Transaktion zugewiesene Namen von Steuerarten, die mehrere Steuerarten mithilfe eines Arrays ermöglichen (z. B. ‘GST’ oder ‘sales’) | | | `charges.metadata.[tax_rates]` | Gleitkomma, CSV, mehrere Steuern | Steuersätze, die prozentual auf eine Transaktion angewendet werden, die bestimmten Steuerarten entspricht (Beispiel ‘3’ oder ‘1.5’ entspricht 3 % GST und 1,5 % Sales Tax) | | | `charges.metadata.[tax_values]` | Zeichenfolge, CSV, mehrere Steuern | Steuerwerte, die auf eine Transaktion angewendet werden, die bestimmten Steuertypen entspricht. Untereinheiten der Basiswährung (‘350’ = 3,50 USD) | | QuickBooks Sync by Acodei erfordert auch Zahlungsaktualisierungen mit Rückerstattungsbeträgen, die in Metadaten geschrieben werden. #### Marketing | Feld- oder Schlüsselname | Format (es gelten die Standard-CSV-Regeln) | Beschreibung | Pflichtfeld | | ---------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | [charges.customer](https://docs.stripe.com/api/charges/object.md#charge_object-customer) | Zeichenfolge (ID) | Stripe-Kunden-ID (die zum verbundenen Konto gehört) mit einem Ziel-`Charge`-Objekt verknüpft ist. Transaktionen werden nicht mit Apps wie Xero und QBO synchronisiert, wenn dieses Feld nicht vorhanden ist. | Pflichtfeld | | [customer.name](https://docs.stripe.com/api/customers/object.md#customer_object-name) | Zeichenfolge | Vollständiger Name des Kunden/der Kundin | | | [customer.email](https://docs.stripe.com/api/customers/object.md#customer_object-email) | Zeichenfolge | E-Mail-Adresse des Kunden/der Kundin | | | [customer.address.<>](https://docs.stripe.com/api/customers/object.md#customer_object-address) | Zeichenfolge (mehrere Felder) | Physische Adresse des Kunden/der Kundin (kann sowohl für die Rechnungsstellung als auch für den Versand verwendet werden) | | | `charges.metadata.[refund_amount]` | Zeichenfolge (Cent-Ganzzahl) | Spiegelung von [charges.amount_refunded](https://docs.stripe.com/api/charges/object.md#charge_object-amount_refunded) | | | `charges.metadata.[refund_reason]` | Zeichenfolge | Grund für die Rückerstattung | | | `customer.metadata.[platform_customer_ID]` | Zeichenfolge | Kunden-ID, wie im System der Plattform erfasst* | | | `charges.metadata.[platform_product_ID]` | Zeichenfolge, CSV, mehrere Produkte | Produkt-IDs, wie im System der Plattform erfasst | | | `charges.metadata.[platform_product_name]` | Zeichenfolge, CSV, mehrere Produkte | Produktname, wie im System der Plattform erfasst | | | `charges.metadata.[platform_product_quantity]` | Zeichenfolge, CSV, mehrere Produkte | Menge jedes Produkts, das dem Array der ID und dem Namen entspricht | | | `charges.metadata.[platform_product_value]` | Zeichenfolge, CSV, mehrere Produkte | Der individuelle Produktwert (Preis und Kosten), der der Produkt-ID und dem Produktnamen entspricht | | | `charges.metadata.[total_tax]` | Zeichenfolge | Gesamtsteuern im Zusammenhang mit dieser Transaktion (Gebühr) | | Der folgende Codeausschnitt geht zur zielseitigen Destination Charge über und zeigt, wie pro Schema aktualisiert werden kann. 1. Rückverfolgung von der Transaktion bis zur Destination Charge #### javascript ```jsx const paymentOnPlatform = await StripeClient.paymentIntents.retrieve( "pi_3N6JL7LirQdaQn8E1Lpn7Dui", ); const latestCharge = await StripeClient.charges.retrieve( paymentOnPlatform.latest_charge as string, ); const transfer = await StripeClient.transfers.retrieve( latestCharge.transfer as string, ); const payment = await StripeClient.charges.retrieve( transfer.destination_payment as string, undefined, { stripeAccount: transfer.destination as string, }, ); ``` 1. Erstellen Sie einen Kunden/eine Kundin und aktualisieren Sie dann die Abbuchung mit der entsprechenden Kunden-ID und den Metadaten. Der Kunde/die Kundin muss dem verbundenen Konto angehören und nicht der Plattform für die Weitergabe der Daten und die Synchronisierung der Apps. #### javascript ```jsx const customer = await StripeClient.customers.create( { email: `jenny.rosen@example.com`, name: "Jenny Rosen", address: { city: "Brothers", state: "Oregon", country: "USA", line1: "27 Fredrick Ave", postal_code: "97712" }, metadata: { platform_customer_ID: "K-123456" }, }, { stripeAccount: accountId, }, ); const payment = await StripeClient.charges.update( id, { customer: customer.id, metadata: { product_name: "Creative writing course for PMs", platform_product_ID: "P-123456", platform_order_ID: "O-123456" }, }, { stripeAccount: accountId, }, ); ``` ## Direct Charges Die eingebetteten Integrationen greifen auf alle bei Stripe gespeicherten Zahlungs-, Kunden- und Produktdaten zu. Sie können optionale plattformspezifische Daten mithilfe des folgenden Metadatenschemas an die App übergeben. | Feld- oder Schlüsselname | Format (es gelten die Standard-CSV-Regeln) | Beschreibung | | ------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.metadata.[platform_customer_ID]` | Zeichenfolge | Kunden-ID, wie im System der Plattform erfasst | | `payment.metadata.[platform_product_ID]` | Zeichenfolge, CSV, mehrere Produkte | Produkt-IDs, die im System der Plattformen erfasst sind und sich auf diese Transaktion beziehen (falls abweichend von der Stripe-Produkt-ID) | | `payment.metadata.[platform_product_name]` | Zeichenfolge, CSV, mehrere Produkte | Produkt- oder Dienstleistungsnamen, die im System der Plattformen erfasst sind und sich auf diese Transaktion beziehen (falls abweichend vom Stripe-Produktnamen) | | `payment.metadata.[platform_product_value]` | Zeichenfolge, CSV, mehrere Produkte | Der individuelle Produktwert (Preis oder Kosten), der dem ID- und Namens-Array entspricht (falls abweichend vom Stripe-Produktwert) | | `payment.metadata.[platform_order_ID]` | Zeichenfolge | Auftrags-ID, wie im System der Plattform erfasst, im Zusammenhang mit dieser Transaktion (Zahlung) | | `payment.metadata.[platform_charge_ID]` | Zeichenfolge | Zahlungs- oder Transaktions-ID, wie auf der Plattform erfasst und für den/die Nutzer/in sichtbar (falls abweichend von der Stripe-Zahlungs-ID) |