Integrationsleitfaden für eingebettete Stripe-AppsPrivate Vorschau

Richten Sie Connect.js ein, 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.

Stripe unterstützt die folgenden App-Integrationen.

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 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 https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-06-30.basil; 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, können Sie die Installationskomponente der App im Frontend anzeigen:

const appInstall = stripeConnectInstance.create('app-install');
appInstall.setApp('{{APP_ID}}');
container.appendChild(appInstall);

Diese eingebettete Komponente unterstützt die folgenden Parameter:

Sie können ein nutzerdefiniertes Verhalten basierend auf dem aktuellen oder aktualisierten Status einer Installation konfigurieren.

// index.html
<div id="app-install-container"></div>

// 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);

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.

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:

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 (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

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

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.

const customer = await StripeClient.customers.create(
      {
        email: `jenny.rosen@example.com`,
        name: "Jenny Rosen",
	 address.city: "Brothers"
	 Address.state: "Oregon"
	 address.country: "USA"
	 address.line1: "27 Fredrick Ave"
	 address.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,
      },
    );

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.