Vollständig eingebettete Connect-Plattform-Integration

Im folgenden Beispiel wird ein Konto erstellt, für das Stripe die Risiken verwaltet, die Preisgestaltung sowie die Verantwortung für die Onboarding-Anforderungen übernimmt. Ihre Plattform verwendet eingebettete Komponenten und haftet nicht für negative Salden. Ihre verbundenen Konten haben keinen Zugriff auf von Stripe gehostete Dashboards.

Sie können nach dem Onboarding des Kontos zusätzliche Funktionen anfordern, zum Beispiel bestimmte Zahlungsmethoden.

Rufen Sie /v1/accounts mit den folgenden Parametern auf:

• country des Kontos
• controller.stripe_dashboard.type = none
• Funktionen card_payments und transfers anfordern

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d country=US \
  -d "controller[stripe_dashboard][type]"=none \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "controller": {
    "type": "application",
    "is_controller": true,
    "losses": {"payments": "stripe"},
    "fees": {"payer": "account"},
    "requirement_collection": "stripe",
    "stripe_dashboard": {
      "type": "none",
    },
  },
  "type": "none",
  ...
}

Verbundene Konten greifen direkt in Ihrer Plattform auf ihre Konten sowie auf die wichtigsten Zahlungsfunktionen zu und haben keinen Zugriff auf ein von Stripe gehostetes Dashboard. Daher müssen Sie den Zugriff über Ihre Website gewähren.

Ihre Integration muss die folgenden eingebetteten Komponenten enthalten:

• Komponente für Konto-Onboarding
• Kontoverwaltungskomponente
• Benachrichtigungsbanner-Komponente
• Dokument-Komponente (wenn Stripe Gebühren direkt von verbundenen Konten erhebt)

Für alle anderen optionalen Komponenten können Sie unsere eingebetteten Komponenten verwenden oder Ihre eigene Nutzeroberfläche erstellen.

Richten Sie unbedingt eingebettete Komponenten ein, bevor Sie das Onboarding von verbundenen Konten durchführen.

Stripe verwendet eine Kontositzung, um Ihre Absicht zum Ausdruck zu bringen, dem verbundenen Konto Zugriff auf eine eingebettete Komponente zu gewähren. Mithilfe einer Kontositzung erfasst die eingebettete Konto-Onboarding-Komponente alle erforderlichen Informationen basierend auf Ihren angeforderten Funktionen.

Konto vorab ausfüllen

Die eingebettete Konto-Onboarding-Komponente erfasst alle erforderlichen Informationen basierend auf Ihren angeforderten Funktionen.

Sie können den Onboarding-Ablauf für Ihre Nutzer/innen optimieren, indem Sie vor dem Erstellen der Kontositzung Kontofelder mit bekannten Informationen vorab ausfüllen. Füllen Sie so viele Kontodaten wie möglich aus, einschließlich Unternehmens-, Einzel- und externer Kontodaten, und folgen Sie diesen Schritten:

1. Überprüfen Sie die erforderlichen Verifizierungsinformationen, um mehr darüber zu erfahren, wie sich die Kombination von Ländern und Funktionen, die Sie für verbundene Konten auswählen, auf deren Anforderungen auswirkt.
2. Um die Informationen zu ermitteln, die Stripe von einem verbundenen Konto benötigt, rufen Sie die Eigenschaft Anforderungen des Kontos ab.
3. Vorab ausfüllbare Informationen erfassen.
4. Erfassen Sie die Informationen zum Konto, indem Sie Konto aktualisieren aufrufen.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d business_type=individual \
  --data-urlencode email="jenny.rosen@example.com" \
  -d "individual[first_name]"=Jenny \
  -d "individual[last_name]"=Rosen \
  --data-urlencode "individual[email]"="jenny.rosen@example.com" \
  -d "individual[address][line1]"="354 Oyster Point Blvd" \
  -d "individual[address][city]"="South San Francisco" \
  -d "individual[address][state]"=CA \
  -d "individual[address][postal_code]"=94080 \
  -d external_account=
{{BANK_ACCOUNT_TOKEN_ID}}

Nachdem das verbundene Konto das Onboarding über die eingebettete Komponente „Konto-Onboarding“ abgeschlossen hat, kann Ihre Plattform bestimmte Informationen wie Auszahlungskonten oder Informationen zur juristischen Person nicht mehr aktualisieren. Das verbundene Konto muss diese Informationen aktualisieren, da die Plattform nicht für Negativsalden verantwortlich ist.

Nutzer/innen über die eingebettete Onboarding-Komponente zum Onboarding einladen

Verbundene Konten müssen das Onboarding durchlaufen und die erforderlichen Informationen angeben, um Zahlungen und Auszahlungen zu aktivieren. Um das Onboarding eines verbundenen Kontos durchzuführen, hosten Sie die eingebettete Onboarding-Komponente auf Ihrer Seite und leiten Sie neue Konten dort hin.

Kontositzung erstellen

Aktivieren Sie beim Erstellen einer Kontositzung die Kontoverwaltung, indem Sie account_onboarding im Parameter components angeben.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[account_onboarding][enabled]"=true \
  -d "components[account_onboarding][features][external_account_collection]"=true

Nachdem die Kontositzung erstellt und ConnectJS initialisiert wurde, können Sie die Komponente für Konto-Onboarding im Frontend darstellen:

// Include this element in your HTML
const accountOnboarding = stripeConnectInstance.create('account-onboarding');
accountOnboarding.setOnExit(() => {
  console.log('User exited the onboarding flow');
});
container.appendChild(accountOnboarding);

Präsentieren Sie den Onboarding-Ablauf dem/der Hauptinhaber/in des Kontos. Der/die Hauptinhaber/in richtet die Authentifizierung mit Stripe ein und ist der/die Nutzer/in, der/die die Kontodetails bearbeiten und auf Risikointerventionen reagieren kann. Das verbundene Konto verfügt nur über einen einzigen Satz von Authentifizierungsdaten bei Stripe. Der/die Nutzer/in, mit den Authentifizierungsdaten kann sich mittels einmaliger SMS-Codes authentifizieren, um sensiblere Aktionen wie die Aktualisierung von Bankkonten für Auszahlungsziele oder die Angabe aktualisierter Informationen zur juristischen Person durchzuführen.

Onboarding-Ereignisse überwachen

Wenn das Konto das Onboarding durchläuft, werden auch account.updated-Ereignisse an Ihre konfigurierten Connect-Webhooks gesendet. Wenn das Konto die Übermittlung seiner Daten abgeschlossen hat, ändert sich das Feld details_submitted im Konto auf „true“. Überprüfen Sie den Status, indem Sie im account.updated-Ereignistext in Ihrem Webhook-Handler nach details_submitted: true suchen oder das Konto abrufen. Wenn details_submitted „false“ ist, zeigen Sie die eingebettete Onboarding-Komponente erneut an. Wenn das Konto einige Informationen übermittelt hat, überspringt die eingebettete Onboarding-Komponente diese und erfasst nur die nicht übermittelten Anforderungen.

Wenn ein verbundenes Konto seine Details übermittelt und den Onboarding-Ablauf abschließt, ruft die eingebettete Onboarding-Komponente den onExit-Handler auf, den Sie beim Rendern der Komponente festgelegt haben. Verwenden Sie den Rückruf, um das Konto zur nächsten Aktion zu leiten. Wenn Sie keinen Exit-Handler festlegen oder innerhalb des Handlers keine Maßnahmen ergreifen, wird dem Konto eine Abschlussmeldung ohne einen eindeutigen nächsten Schritt angezeigt.

Da Stripe das Kredit- und Betrugsrisiko für Ihre verbundenen Konten verwaltet, müssen Ihre Konten in der Lage sein, Warnungen von Stripe zu sehen und darauf zu reagieren. Um dies zu erleichtern, muss Ihre Plattform die eingebetteten Komponenten „Benachrichtigungsbanner“ und „Kontoverwaltung“ integrieren. Weitere Informationen darüber, wie Stripe Ihre verbundenen Konten über diese Komponenten unterstützt, finden Sie unter Embedded Connect-Support.

Benachrichtigungsbanner einbetten

Stripe verwendet die eingebettete Benachrichtigungsbanner-Komponente, um verbundene Konten über ausstehende Compliance-Anforderungen oder andere Anfragen im Zusammenhang mit dem Risikomanagement zu informieren. Die Antwort auf diese Benachrichtigungen ermöglicht es einem Konto, die Konformität bei der Verarbeitung von Zahlungen und dem Empfang von Auszahlungen zu gewährleisten. Wenn keine Benachrichtigungen ausstehen, wird das eingebettete Benachrichtigungsbanner nicht angezeigt.

Integrieren Sie das Benachrichtigungsbanner gut sichtbar und leicht zugänglich auf Ihrer Website. Sie können es beispielsweise oben auf Ihrer Zahlungsseite integrieren.

Kontositzung erstellen

Beim Erstellen einer Kontositzung aktivieren Sie das Benachrichtigungsbanner, indem Sie notification_banner im Parameter components angeben.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[notification_banner][enabled]"=true \
  -d "components[notification_banner][features][external_account_collection]"=true

Benachrichtigungsbanner-Komponente rendern

// Include this element in your HTML
const notificationBanner = stripeConnectInstance.create('notification-banner');
container.appendChild(notificationBanner);

// Optional:
// notificationBanner.setCollectionOptions({
//   fields: 'eventually_due',
//   futureRequirements: 'include',
// })

Um auf eine Bannerbenachrichtigung zu reagieren, kann das Konto auf eine Schaltfläche in der Benachrichtigung klicken. Sie müssen sie nicht an die eingebettete Kontoverwaltungskomponente weiterleiten.

Kontoverwaltung einbetten

Stripe benötigt die eingebettete Kontoverwaltungskomponente für das Risikomanagement. Integrieren Sie die Komponente in Ihre Website, dort, wo ein Konto seine Einstellungen oder sein Profil aktualisiert.

Kontositzung erstellen

Aktivieren Sie beim Erstellen einer Kontositzung die Kontoverwaltung, indem Sie account_management im Parameter components angeben.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[account_management][enabled]"=true \
  -d "components[account_management][features][external_account_collection]"=true

Kontoverwaltungskomponente rendern

// Include this element in your HTML
const accountManagement = stripeConnectInstance.create('account-management');
container.appendChild(accountManagement);

// Optional:
// accountManagement.setCollectionOptions({
//   fields: 'eventually_due',
//   futureRequirements: 'include',
// })

Mit dieser Komponente kann ein Konto seine Kontodetails aktualisieren, auf neue Konformitätsanforderungen reagieren und ihre Authentifizierungsdaten aktualisieren.

Richten Sie die Zahlungsintegration ein, nachdem Sie die erforderlichen eingebetteten Komponenten integriert haben. Sie können Ihrer Plattform integrierte Zahlungs- und Auszahlungskomponenten hinzufügen oder Ihre eigenen Arbeitsabläufe erstellen.

Konfigurieren Sie Connect-Webhooks und überwachen Sie das Ereignis account.updated. Ein verbundenes Konto ist zum Empfang von Zahlungen bereit, wenn die Eigenschaft charges_enabled auf „true“ festgelegt ist.

Integration eingebetteter Zahlungen und Auszahlungen

Fügen Sie Ihrer Plattform die eingebettete Komponenten für Zahlungen und Auszahlungen hinzu, bevor Sie Ihre Zahlungsintegration erstellen. So kann ein Konto problemlos auf seine wichtigsten Zahlungsabläufe zugreifen und diese verwalten.

Die Zahlungskomponente zeigt die Liste der Zahlungen des verbundenen Kontos an und enthält Filter und individuelle Zahlungsdetailansichten. Konten können mit dieser Komponente mit Nachweisen zu einzelnen Zahlungen Rückerstattungen ausstellen und auf angefochtene Zahlungen reagieren.

Kontositzung erstellen

Aktivieren Sie beim Erstellen einer Kontositzung die eingebettete Zahlungskomponente, indem Sie im components-Parameter payments angeben. Sie können einzelne Funktionen der Zahlungsdetails-Komponente aktivieren oder deaktivieren, indem Sie unter payments den features-Parameter festlegen:

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[payments][enabled]"=true \
  -d "components[payments][features][refund_management]"=true \
  -d "components[payments][features][dispute_management]"=true \
  -d "components[payments][features][capture_payments]"=true \
  -d "components[payments][features][destination_on_behalf_of_charge_management]"=false

Bei direkten Abbuchungen können Ihre verbundenen Konten die vollständigen Informationen einsehen. Sie können auch Rückerstattungen und Zahlungsanfechtungen verwalten und Zahlungen erfassen, wenn Sie die entsprechenden Funktionen beim Erstellen einer Kontositzung aktivieren.

Die Zahlungskomponente rendern

Nachdem die Kontositzung erstellt und ConnectJS initialisiert wurde, können Sie die Zahlungskomponente im Frontend anzeigen:

// Include this element in your HTML
const payments = stripeConnectInstance.create('payments');
container.appendChild(payments);

// Optional: specify filters to apply on load
// payments.setDefaultFilters({
//   amount: {greaterThan: 100},
//   date: {before: new Date(2024, 0, 1)},
//   status: ['partially_refunded', 'refund_pending', 'refunded'],
//   paymentMethod: 'card',});

Die Auszahlungskomponente zeigt die letzten Auszahlungen des verbundenen Kontos, das aktuelle Guthaben und den Zeitpunkt der Verfügbarkeit von Geldern an.

Aktivieren Sie beim Erstellen einer Kontositzung die eingebettete Auszahlungskomponente, indem Sie payouts im Parameter components angeben. Sie können einzelne Funktionen der Auszahlungskomponente aktivieren oder deaktivieren, indem Sie den Parameter features unter payouts angeben:

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[payouts][enabled]"=true \
  -d "components[payouts][features][instant_payouts]"=true \
  -d "components[payouts][features][standard_payouts]"=true \
  -d "components[payouts][features][edit_payout_schedule]"=true \
  -d "components[payouts][features][external_account_collection]"=true

Nachdem die Kontositzung erstellt und ConnectJS initialisiert wurde, können Sie die Auszahlungskomponente im Frontend anzeigen:

// Include this element in your HTML
const payouts = stripeConnectInstance.create('payouts');
container.appendChild(payouts);

Eine ausführliche Anleitung zur Implementierung eingebetteter Komponenten finden Sie im Schnellstart für die Integration eingebetteter Connect-Komponenten.

Zahlung annehmen

Wenn Ihre verbundenen Konten direkt mit Kunden/Kundinnen Transaktionen durchführen, empfiehlt Stripe dringend, Direct Charges zu verwenden.

Stripe berechnet Ihrer Plattform Transaktionsgebühren für Zahlungen, wenn controller.fees.payer für das Konto nicht auf account gesetzt sind. Sie sind dafür verantwortlich, Ihren verbundenen Konten Gebühren für die Zahlungsabwicklung in Rechnung zu stellen. Sie können bei jeder Zahlung verwenden, um automatisch Gebühren von verbundenen Konten zu erheben, ohne dies in Ihre Integration aufnehmen zu müssen.

Wir empfehlen Ihnen, Stripe Checkout zu verwenden, eine vorkonfigurierte von Stripe gehostete Seite zum Empfang von Zahlungen. Checkout unterstützt mehrere Zahlungsmethoden und zeigt Ihrem/Ihrer Kund/in automatisch die für ihn/sie relevantesten an.

Sie können auch das Payment Element verwenden, eine vorgefertigte Nutzeroberfläche, die Sie einbetten können, um mit einer einzigen Integration zusätzliche Zahlungsmethoden zu akzeptieren.

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Pay</button>
    </form>
  </body>
</html>

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Stripe kommuniziert in Ihrem Auftrag mit Ihren verbundenen Konten, um Risiken zu verwalten und stets Compliance zu gewährleisten. Sie können diese E-Mail-Nachrichten anpassen und mit Ihrer eigenen E-Mail-Domain und Ihrem Plattform-Branding versehen.

Stripe sendet die folgenden E-Mails an Ihre verbundenen Konten:

• Konto-E-Mails verifizieren Kontoinformationen, wie z. B. hinzugefügte oder geänderte E-Mail-Adressen, Telefonnummern oder Bankkonten.
• ** Compliance-E-Mails** benachrichtigen Konten, damit sie die erforderlichen Informationen zur Verfügung stellen. Stripe muss häufig weitere Informationen erfassen, um die Compliance mit unseren Finanzpartnern aufrechtzuerhalten.
• Risiko-E-Mails benachrichtigen Konten, wenn sie einer Risikoprüfung unterzogen werden. Diese E-Mails enthalten häufig Anweisungen dazu, wie Informationen zur Behebung von Risikomaßnahme eingereicht werden können, z. B. zur Aufhebung einer Auszahlungspause.
• Steuer-E-Mails (nur, wenn Stripe die Gebühren direkt von verbundenen Konten einzieht) benachrichtigen Nutzer/innen, wenn ihre Steuerrechnungen oder 1099-Formulare zum Download bereit sind.

Wenn Sie weitere zahlungsbezogene E-Mails an Ihre verbundenen Konten senden möchten, müssen Sie dies selbst tun. Wenn Sie beispielsweise E-Mails bezüglich neuer Zahlungsanfechtungen senden möchten, beobachten Sie das Ereignis charge.dispute.created in einem verbundenen Konto. Wenn dieses Ereignis eintritt, verwenden Sie die Disputes API, um die Details abzurufen und per E-Mail an das Konto zu senden.

Sie müssen Ihre Connect-Einstellungen mit den URLs aktualisieren Ihrer Zahlungen und Kontoabläufe aktualisieren, damit die Kommunikation von Stripe Links einfügen kann, über die Ihre Konten antworten können.

Weiterleitungen über E-Mail-Links handhaben

Von Stripe gesendete E-Mails, die eine Handlungsaufforderung enthalten, müssen einen Link zu dieser Handlung enthalten. Wenn wir zum Beispiel eine E-Mail an ein verbundenes Konto senden, muss sie einen Link zu Ihrer Kontoverwaltungskomponente enthalten.

Bevor Sie eine Kontositzung im Live-Modus erstellen können, müssen Sie die URLs angeben, unter denen Sie die eingebetteten Komponenten in Ihre Website integriert haben. Konfigurieren Sie die Sende-E-Mail-Domain und die eingebetteten Komponenten-URLs im Abschnitt Website-Links in den Connect-Einstellungen Ihrer Plattform.

Wählen Sie für eingebettete Komponenten, die in Ihre Website integriert sind, Ja aus und geben Sie die URL der Seite ein, auf der die Komponente gehostet wird. Wählen Sie für alle Aktionen, die nicht von einer eingebetteten Komponente verarbeitet werden, Nein aus und geben Sie die URL der Seite auf Ihrer Website ein, auf der das Konto die Aktion ausführen kann. Nachdem Sie die URLs eingegeben haben, testen Sie sie, um sicherzustellen, dass sie die richtigen Seiten öffnen.

Sie müssen URLs für Folgendes festlegen:

• Benachrichtigungsbanner
• Kontoverwaltung
• Zahlungen
• Auszahlungen
• Salden
• Dokumente (wenn Stripe Gebühren direkt von verbundenen Konten erhebt)

Beim Senden einer E-Mail hängt Stripe die jeweilige ID des verbundenen Kontos als Parameter stripe_account_id an die Weiterleitungs-URL an. Mit diesem Parameter können Sie das Konto identifizieren und so die Authentifizierung gewährleisten. Richten Sie die Route auf Ihrem Server so ein, dass die Parameter gelesen und die korrekte eingebettete Komponente angezeigt wird.

Weitere Informationen zum Konfigurieren von Stripe-E-Mails für Ihre verbundenen Konten finden Sie unter E-Mail-Kommunikation in eingebetteten Connect-Integrationen.

E-Mail-Branding und Einstellungen konfigurieren

Stripe kann E-Mails mit den Markeneinstellungen Ihrer Plattform von Ihrer eigenen E-Mail-Domain an Ihre verbundenen Konten senden. Um Stripe-E-Mails für Ihre verbundenen Konten zu konfigurieren, rufen Sie E-Mails in Ihrem Plattform-Dashboard auf.

Zu diesem Zeitpunkt haben Sie Ihre Plattformintegration wie folgt konfiguriert:

• Verbundene Konten in der richtigen Konfiguration erstellt
• Eingebettete Komponenten integriert, damit verbundene Konten über Ihre Website zum Onboarding eingeladen werden können, ihre Konten verwalten können und auf Risikomaßnahmen reagieren können
• Zahlungen per Direct Charges mit Plattformgebühr einrichten
• Richten Sie eine markengeschützte E-Mail-Kommunikation ein, damit Stripe mit Ihren Nutzer/innen im Hinblick auf Compliance, Risikenmaßnahmen und erforderliche Dokumente kommunizieren kann

Integration testen

Testen Sie Ihren Kontoerstellungsablauf, indem Sie das in Ihre Plattform integrierte Konto-Onboarding verwenden. Testen Sie Ihre Zahlungsmethodeneinstellungen für Ihre verbundenen Konten, indem Sie sich bei einem Ihrer Testkonten anmelden und zu den Einstellungen für Zahlungsmethoden navigieren. Testen Sie Ihren Bezahlvorgang mit Ihren Testschlüsseln und einem Testkonto. Sie können unsere Testkarten verwenden, um Ihre Zahlungsabläufe zu testen und verschiedene Zahlungsergebnisse zu simulieren.