Connect-Integration migrieren, um Controller-Eigenschaften anstelle von Kontotypen zu verwenden

Erfahren Sie, wie Sie mit den Eigenschaften der Konto-Controller arbeiten, anstatt Kontotypen anzugeben.

Sie können verbundene Konten mithilfe von Konto-Controller-Eigenschaften konfigurieren, anstatt Konten als „Standard“, „Express“ oder „Custom“ zu definieren. Mit diesen Controller-Eigenschaften können Sie diskretes Kontoverhalten angeben, z. B. den Zugriff auf ein von Stripe gehostetes Dashboard und ob Stripe Gebühren vom Konto oder von der Plattform erhebt. Diese Modularität ermöglicht flexiblere Konfigurationsmöglichkeiten.

Durch die Verwendung der Controller-Eigenschaften für die Konten müssen Sie Ihre API-Version nicht zwingend aktualisieren. Die Migration Ihrer Integration zur Verwendung der Controller-Eigenschaften ist optional. Wenn Sie nur einen Typ verbundener Konten verwenden und nicht daran interessiert sind, eine neue Konfiguration zu verwenden, müssen Sie Ihre Integration nicht aktualisieren.

Wir empfehlen Ihnen, Ihre Integration zu aktualisieren. So können Sie von der verbesserten Modularität und den neuen verfügbaren Konfigurationen profitieren. Die neuen Eigenschaften sind vollständig abwärtskompatibel, sodass Sie Ihre Integration schrittweise migrieren können, während Sie weiterhin mit den Kontotypen arbeiten.

Jeder Kontotyp wird einem Satz von Controller-Eigenschaften zugeordnet. Wir legen diese Eigenschaften automatisch für Ihre bestehenden verbundenen Konten und für alle Konten fest, die Sie in Zukunft mit Kontotypen erstellen. Wenn Sie Ihre Integration aktualisieren, um mit Controller-Eigenschaften zu arbeiten, müssen Sie keines Ihrer verbundenen Konten aktualisieren.

Notiz

Sie können Funktionen, wie z. B. eingebettete Komponenten verwenden, ohne die Änderungen in diesem Leitfaden vorzunehmen.

Bevor Sie beginnen

Erfahren Sie, wie Controller-Eigenschaften funktionieren und wie sie Ihren bestehenden verbundenen Konten zugeordnet werden.
Bestimmen Sie, welche der neuen Kontokonfigurationen für Ihre Integration sinnvoll sind.

Die Aktualisierung Ihrer Integration umfasst Folgendes:

Suchen Sie nach dem Code in Ihrer Integration, der auf den Kontotyp verweist. Aktualisieren Sie diesen so, dass er stattdessen auf die entsprechenden Controller-Eigenschaften verweist.
Aktualisieren Sie den Ablauf Ihren Kontoerstellung, um Controller-Eigenschaften anstelle von type anzugeben. Die Angabe des type ist nicht mehr erforderlich.

Eigenschaften des Konto-Controllers

Sie können Werte für die Controller-Eigenschaften angeben, wenn Sie ein verbundenes Konto mit der Accounts API erstellen. Jede Eigenschaft, die Sie nicht angeben, ist auf einen Standardwert mit den am wenigsten komplexen Integrationsanforderungen festgelegt.

Wenn Sie eine neue Integration erstellen, können Sie eine Konfigurationsempfehlung erhalten, indem Sie das Connect-Onboarding für Plattformen abschließen.

Eigenschaft	Standardwert	Beschreibung
controller.losses.payments	`stripe`	Mögliche Werte: `application`: Ihre Plattform haftet für negative Kontostände und verwaltet Kredit- und Betrugsrisiken des verbundenen Kontos. Sie müssen daher Ihre Verantwortlichkeiten im Dashboard überprüfen und anerkennen `stripe`: Stripe haftet, wenn dieses Konto negative Beträge aus Zahlungen nicht zurückzahlen kann. Ihre Plattform haftet weiterhin für einen negativen Saldo auf Ihrem Plattformkonto.
controller.fees.payer	`account`	Mögliche Werte: `account`: Das verbundene Konto zahlt alle Stripe-Gebühren direkt an Stripe, einschließlich der Zahlungsverarbeitungsgebühren `application`: Die Connect-Plattform zahlt alle Stripe-Gebühren, einschließlich der Gebühren für die Zahlungsabwicklung `application_custom`: Das Konto wurde mit type=custom erstellt. `application_express`: Das Konto wurde mit type=express erstellt. Wenn Sie ein Konto erstellen, können Sie nur entweder `application` oder `account` angeben. `application_express` und `application_custom` sind keine gültigen Erstellungsparameter. Eine umfassende Beschreibung der Zahlungsmodelle für Stripe finden Sie in der Dokumentation zum Gebührenverhalten.
controller.requirement_collection	`stripe`	Mögliche Werte: `application`: Ihre Plattform ist dafür verantwortlich, aktualisierte Informationen zu erfassen, wenn Anforderungen fällig sind oder sich ändern `stripe`: Stripe ist dafür verantwortlich, aktualisierte Informationen zu erfassen, wenn Anforderungen fällig sind oder sich ändern Ein Wert von `application` bedeutet, dass Ihre Plattform vollständig auf die KYC-Eigenschaften des Kontos zugreifen und bestätigen kann, dass das Konto die Dienstleistungsvereinbarung von Stripe über die API gesehen und akzeptiert hat.
controller.stripe_dashboard.type	`full`	Mögliche Werte: `express`: Das verbundene Konto kann auf das Express-Dashboard zugreifen. `full`: Das verknüpfte Konto kann auf das gesamte Stripe-Dashboard zugreifen `none`: Das Konto kann nicht auf das Express- oder Stripe-Dashboard zugreifen.
Typ	Siehe Beschreibung	Mögliche Werte: `custom`: Das Konto wurde als verbundenes Custom-Konto erstellt `express`: Das Konto wurde als verbundenes Express-Konto erstellt `standard`: Das Konto wurde als verbundenes Standard-Konto oder mit Controller-Eigenschaften erstellt, die mit denen eines Standard-Kontos übereinstimmen. `none`: Das Konto wurde ohne Typwert erstellt und seine Controller-Eigenschaften stimmen mit keinem der drei Kontotypen überein. Die Angabe des `type` ist optional. Wenn Sie ein Konto mit `type` erstellen, können Sie nur `custom`, `express` oder `standard` angeben. `none` ist kein gültiger Parameter für die Kontoerstellung.

Zuordnung von Kontotypen zu Controller-Parametern

Jeder der drei Kontotypen entspricht Werten im controller-Hash von v1/accounts zugeordnet, die dem Verhalten dieses Typs entsprechen.

Standard

Wenn Sie ein Konto erstellen und dabei keine Controller-Eigenschaften angeben, entsprechen die Standardwerte dem Verhalten eines Standard-Konto. Sie können auch das Äquivalent eines Standard-Kontos erstellen, indem Sie die Werte angeben, die dem Verhalten des Standard-Konto entsprechen.

Diese Werte können dem Verhalten eines Standard-Kontos zugordnet werden:

losses.payments: stripe
fees.payer: account
requirement_collection: stripe
stripe_dashboard.type: full

Anfrage (unter Verwendung von Standardwerten für alle Eigenschaften):

Antwort:

{
  controller: {
    type: "application",
    is_controller: true,
    losses: {
      payments: "stripe"
    },
    requirement_collection: "stripe",
    fees: {
      payer: "account",
    },
    stripe_dashboard: {
      type: "full"
    }
  },
  type: "standard"
}

Express

Diese Werte können dem Verhalten eines Express-Kontos zugordnet werden:

losses.payments: application
fees.payer: application (siehe Hinweis)
requirement_collection: stripe
stripe_dashboard.type: express

Notiz

Wenn Sie ein Express-Konto mit type erstellen, wird die Eigenschaft controller.fees.payer auf application_express anstelle von application festgelegt. Wenn Ihre Plattform Direct Charges verwenden, wird durch diesen Unterschied eine Änderung am Abrechnungsverhalten für die Stripe-Gebühren aufgezeigt.

Anfrage:

Antwort:

{
  controller: {
    type: "application",
    is_controller: true,
    losses: {
      payments: "application"
    },
    requirement_collection: "stripe",
    fees: {
      payer: "application",
    },
    stripe_dashboard: {
      type: "express"
    }
  },
  type: "none"
}

Custom

Diese Werte können dem Verhalten eines Custom-Kontos zugordnet werden:

losses.payments: application
fees.payer: application (siehe Hinweis)
requirement_collection: application
stripe_dashboard.type: none

Beim Erstellen eines Custom-Kontos müssen Sie auch das Kontoland angeben sowie die Funktionen card_payments and transfers anfordern.

Notiz

Wenn Sie ein Custom-Konto mit type erstellen, wird die Eigenschaft controller.fees.payer auf application_custom anstelle von application festgelegt. Wenn Ihre Plattform Direct Charges verwenden, wird durch diesen Unterschied eine Änderung am Abrechnungsverhalten für die Stripe-Gebühren aufgezeigt.

Anfrage:

Antwort:

{
  controller: {
    type: "application",
    is_controller: true,
    losses: {
      payments: "application"
    },
    requirement_collection: "application",
    fees: {
      payer: "application",
    },
    stripe_dashboard: {
      type: "none"
    }
  },
  type: "none"
}

Code migrieren, um Controller-Eigenschaften zu verwenden

Um Controller-Eigenschaften zu verwenden, aktualisieren Sie zusätzlich zur Aktualisierung Ihres Ablaufs für Kontoerstellungen auch Ihre Integration, indem Sie Ihren Code überprüfen und nach Verweisen auf Kontotypen suchen.

Bestimmen Sie für jeden Verweis auf einen Kontotyp, welche Controller-Eigenschaft(en) relevant sind, und aktualisieren Sie Ihren Code entsprechend.

Angenommen, Ihr Code enthält eine bedingte Anweisung, die für Express- und Custom-Konten gilt, da sie sich darauf bezieht, dass Ihre Plattform für negative Salden haftet. Aktualisieren Sie diese Logik von if type == express oder if type == custom auf if controller.losses.payments == application.

Wenn Sie verbundene Konten erstellen, die mit keinem Kontotyp übereinstimmen, sollten Sie bei der Aktualisierung Ihres Codes auch deren Controller-Eigenschaften berücksichtigen. Die Logik für die Verwaltung dieser Konten kann von Ihrer bestehenden Logik, die auf dem Kontotyp basiert, abweichen.

Sie können diese Tabelle verwenden, um die Controller-Eigenschaften zu bestimmen, die jedem Kontotyp zugeordnet sind:

Kontotyp	losses.payments	fees.payer	requirement_collection	stripe_dashboard.type
Custom	`application`	`application_custom`	`application`	`none`
Express	`application`	`application_express`	`stripe`	`express`
Standard	`stripe`	`account`	`stripe`	`full`

Notiz

Bedenken Sie, dass Express- und Custom-Konten einen anderen Wert für fees.payer haben als ähnliche Konten, die mit Controller-Eigenschaften erstellt wurden. Bei der Aktualisierung Ihres Codes im Zusammenhang mit der Erhebung von Gebühren müssen Sie die unterschiedlichen Verhaltensweisen berücksichtigen.

Nicht unterstützte Konfigurationen

Beim Erstellen von Konten mit Controller-Eigenschaften werden die folgenden Kombinationen nicht unterstützt:

controller.requirement_collection = application ist mit keinem der folgenden Werte kompatibel:

controller.losses.payments = stripe
controller.fees.payer = account
controller.stripe_dashboard.type = express
controller.stripe_dashboard.type = full

controller.stripe_dashboard.type = express ist mit keinem der folgenden Werte kompatibel:

controller.losses.payments = stripe
controller.fees.payer = account
controller.requirement_collection = application

controller.stripe_dashboard.type = full ist mit keinem der folgenden Werte kompatibel:

controller.losses.payments = application
controller.fees.payer = application
controller.requirement_collection = application

controller.stripe_dashboard.type = none wird nicht unterstützt, wenn beide der folgenden Werte eingestellt sind (es wird jedoch unterstützt, wenn nur einer eingestellt ist):

controller.requirement_collection = stripe
controller.losses.payments = application