API-Onboarding

Erstellen Sie Ihren eigenen Onboarding-Ablauf mit den APIs von Stripe.

With API onboarding, you use the Accounts API to build an onboarding flow, reporting functionality, and communication channels for your users. Stripe can be completely invisible to the account holder. However, your platform is responsible for all interactions with your accounts and for collecting all the information needed to verify them.

Additional responsibilities

With API onboarding, your custom flow must meet all legal and regulatory requirements in the regions where you do business. You must also commit resources to track changes to those requirements and collect updated information on an ongoing basis, at least once every six months. If you want to implement a customized onboarding flow, Stripe strongly recommends that you use embedded onboarding.

Anforderungen festlegen

Die folgenden Faktoren wirken sich auf die Onboarding-Anforderungen für Ihre verbundenen Konten aus:

Das Ursprungsland der verbundenen Konten
Art des Rahmenvertrags, der für die verbundenen Konten gilt
Für die verbundenen Konten angeforderte Funktionen
Der Unternehmenstyp (zum Beispiel Einzelperson oder Unternehmen) und company.structure (zum Beispiel öffentliche Kapitalgesellschaft oder private Partnerschaft)

Verwenden Sie das interaktive Formular, um festzustellen, wie sich das Ändern dieser Faktoren auf die Anforderungen auswirkt.

Anforderungsformular

Formulare zum Erfassen von Informationen erstellen
Clientseitig

Als Best Practice empfiehlt es sich, die erforderlichen Parameter in Ihrem Onboarding-Prozess in logischen Gruppierungen oder Formularen zu organisieren. Sie können eine Zuordnung zwischen den Stripe-Parametern und den logischen Gruppierungen kodieren. Vorgeschlagene logische Gruppierungen für Parameter werden in der ersten Spalte der Beispielanforderungstabelle angezeigt.

Nachdem Sie die erforderlichen Parameter in Ihrer Anwendung kodiert haben, generieren Sie Nutzeroberflächen für die Parameter, die diesen Anforderungen entsprechen. Entwickeln Sie für jeden Parameter eine Nutzeroberfläche, die Folgendes enthält:

Parameterbezeichnung, lokalisiert für jedes unterstützte Land und jede unterstützte Sprache
Parameterbeschreibung, lokalisiert für jedes unterstützte Land und jede unterstützte Sprache
Parametereingabefelder mit Datenvalidierungslogik und Hochladen von Dokumenten (sofern erforderlich)

Wenn Sie Ihre Anwendungslogik entwickeln, sollten Sie auch mögliche zukünftige Parameter im Hinterkopf behalten. Es kann zum Beispiel sein, dass Stripe im Laufe der Zeit neue Parameter, neue Verifizierungen oder neue Schwellenwerte einführt, die Sie in Ihr eigenes Onboarding integrieren müssen.

Wenn Sie einen der Faktoren ändern, der die Anforderungen für Ihre verbundenen Konten bestimmt, müssen Sie auch Ihre Zahlungsformulare anpassen. Land und Art des Rahmenvertrags sind unveränderlich, wohingegen Funktionen und Unternehmenstyp geändert werden können.

Um ein unveränderliches Feld wie das Land oder den Typ des Rahmenvertrags zu ändern, erstellen Sie ein neues verbundenes Konto mit den neuen Werten. Dadurch entstehen neue Anforderungen, die Sie in Ihre Einzugsabläufe integrieren müssen.
Um ein veränderbares Feld, wie z. B. die Funktionen oder den Unternehmenstyp zu ändern, aktualisieren Sie das verbundene Konto. Dadurch entstehen neue Anforderungen, die Sie in Ihre Zahlungsabläufe integrieren müssen.

Allgemeine Geschäftsbedingungen von Stripe beifügen

Ihre verbundenen Konten müssen die allgemeinen Geschäftsbedingungen von Stripe akzeptieren, bevor die Konten aktiviert werden können. Sie können die allgemeinen Geschäftsbedingungen von Stripe in Ihre eigenen Bedingungen integrieren.

Verbundenes Konto erstellen
Serverseitig

Erstellen Sie ein verbundenes Konto, bei dem Ihre Plattform für negative Salden haftet, Stripe die Gebühren von Ihrem Plattformkonto einzieht und Ihre verbundenen Konten keinen Zugriff auf ein von Stripe gehostetes Dashboard haben. Fordern Sie alle Funktionen an, die Ihre verbundenen Konten benötigen. Geben Sie den Geschäftstyp und alle anderen Informationen an, die Ihren Anforderungen entsprechen, wenn Ihnen diese zum Vorausfüllen zur Verfügung stehen.

Alternativ können Sie ein verbundenes Konto erstellen, dessen type auf custom und die gewünschten Funktionen festgelegt ist.

Wenn Sie das Land und den Typ des Rahmenvertrags nicht angeben, werden ihnen die folgenden Standardwerte zugewiesen:

Das Land für country ist standardmäßig das gleiche wie das Ihrer Plattform.
Der Typ des Rahmenvertrags (tos_acceptance.service_agreement) ist standardmäßig auf full festgelegt.

Die zu erfassenden Informationen bestimmen
Serverseitig

Sie als Plattform müssen entscheiden, ob die erforderlichen Informationen von den verbundenen Konten vorab oder inkrementell erfasst werden sollen. Beim Onboarding im Voraus werden die eventually_due Anforderungen für das Konto erfasst, während beim inkrementellen Onboarding nur die currently_due Anforderungen erfasst werden.

	Onboarding im Voraus	Inkrementelles Onboarding
Vorteile	Es erfolgt (in der Regel) eine einzige Informationsanfrage. Beim Empfang von Auszahlungen und bei Zahlungsabwicklungen treten weniger Probleme auf. Potenzielle Betrüger oder verbundene Konten, die erforderliche Informationen verweigern, werden erkannt.	Das Onboarding von verbundenen Konten erfolgt schnell. Die Onboarding-Raten sind höher.
Nachteile	Onboarding verbundener Konten kann länger dauern. Einige legitime neue verbundene Konten könnten sich aufgrund der Menge an Informationen, die vor Abschluss des Onboarding-Vorgangs erforderlich sind, abwenden.	Die Wahrscheinlichkeit einer Geschäftsunterbrechung bei einem bestehenden verbundenen Konto ist höher.

Um zu bestimmen, ob Sie das Onboarding im Voraus oder inkrementelles Onboarding nutzen möchten, lesen Sie die erforderlichen Informationen für die Länder, in denen sich Ihre verbundenen Konten befinden, um die Anforderungen zu verstehen, die letztendlich fällig werden. Auch wenn Stripe versucht, etwaige Auswirkungen auf verbundene Konten zu minimieren, können sich Anforderungen im Laufe der Zeit ändern.

For connected accounts where you’re responsible for requirement collection, you can customize the behavior of future requirements using the collection_options parameter. Set collection_options.future_requirements to include to collect the account’s future requirements.

Um Ihre Onboarding-Strategie umzusetzen, überprüfen Sie den Anforderungs-Hash des verbundenen Kontos, das Sie erstellt haben. Der Anforderungs-Hash bietet eine vollständige Liste der Parameter, die Sie erfassen müssen, um das verbundene Konto zu aktivieren.

Überprüfen Sie für das inkrementelle Onboarding das Feld currently_due im Anforderungs-Hash und erstellen Sie einen Onboarding-Ablauf, bei dem nur die aufgeführten Parameter erfasst werden.
Überprüfen Sie für das Onboarding im Voraus das Feld eventually_due im Anforderungs-Hash und erstellen einen Onboarding-Ablauf, bei dem alle aufgeführten Parameter erfasst werden.

{
  ...
  "requirements": {
    "alternatives": [],
    "current_deadline": null,
    "currently_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "disabled_reason": "requirements.past_due",
    "errors": [],
    "eventually_due": [
      "business_profile.product_description",
      "business_profile.support_phone",
      "business_profile.url",
      "external_account",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ],
    "past_due": [],
    "pending_verification": []
  },
  ...
}

Verbundenes Konto aktualisieren
Serverseitig

Aktualisieren Sie das Objekt des verbundenen Kontos mit neuen Informationen, während Ihre Nutzer/innen die einzelnen Schritte des Onboarding-Ablaufs durchlaufen, um es Stripe zu ermöglichen, die Informationen zu validieren, sobald sie hinzugefügt werden. Nachdem Stripe die Annahme unserer allgemeinen Geschäftsbedingungen bestätigt hat, lösen alle Änderungen am verbundenen Konto eine erneute Verifizierung aus. Wenn Sie beispielsweise den Namen oder die ID-Nummer des verbundenen Kontos ändern, führt Stripe die Verifizierungen erneut durch.

Bei der Aktualisierung eines verbundenen Kontos müssen Sie alle Verifizierungsfehler oder HTTP-Fehlercodes bearbeiten.

Umgang mit Verifizierungsfehlern
Serverseitig

Nachdem die Daten des verbundenen Kontos übermittelt wurden, verifiziert Stripe diese. Dieser Vorgang kann je nach Art der erforderlichen Verifizierung einige Minuten oder Stunden dauern. Während der Verifizierung befinden sich die angeforderten Funktionen im Status ausstehend.

Status prüfen

Sie können den Status der Funktionen Ihres verbundenen Kontos wie folgt abrufen:

Der Funktions-Hash des Account-Objekts wird auf die relevante Funktion hin geprüft.
Funktionen werden direkt von der Capabilities API angefordert und der Status der relevanten Funktion wird überprüft.
Ereignisse des Typs account.updated werden in Ihrem Webhook-Endpoint überwacht und der Hash capabilities wird auf die entsprechende Funktion überprüft.

Nachdem die Verifizierungen abgeschlossen sind, nimmt die Funktion den Status active an und kann vom verbundenen Konto genutzt werden. Kontoverifizierungen werden kontinuierlich durchgeführt, und wenn eine zukünftige Verifizierung fehlschlägt, kann eine Funktion aus dem Status active heraus wechseln. Überwachen Sie account.updated-Ereignisse, um Änderungen am Funktionsstatus zu erkennen.

Bestätigen Sie, dass Ihre Connect-Integration konform und betriebsbereit ist, indem Sie überprüfen, ob charges_enabled und payouts_enabled für das Konto beide „true“ sind. Sie können die API verwenden oder Ereignisse des Typs account.updated überwachen. Details zu anderen relevanten Feldern finden Sie im Hash Anforderungen des Kontos. Sie können die Integration nicht anhand eines einzelnen Werts bestätigen, da die Status je nach Anwendung und verwandten Richtlinien variieren können.

charges_enabled bestätigt, dass Ihr vollständiger Zahlungspfad, einschließlich Zahlung und Überweisung, korrekt funktioniert, und prüft, ob die Funktionen card_payments oder transfers aktiv sind.
payouts_enabled gibt Auskunft darüber, ob Ihr verbundenes Konto Auszahlungen an ein externes Konto vornehmen kann. Je nach Ihren Risikorichtlinien können Sie zulassen, dass Ihr verbundenes Konto Transaktionen ausführt, auch wenn es noch keine Auszahlungen aktiviert hat. Sie müssen die Auszahlungen jedoch zu einem späteren Zeitpunkt aktivieren, um Gelder an Ihre verbundenen Konten auszahlen.

Sie können die folgende Logik als Ausgangspunkt für die Definition einer Statusübersicht verwenden, die Ihrem verbundenen Konto angezeigt wird.

Ruby
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'


def account_state(account)
  reqs = account.requirements

  if reqs.disabled_reason && reqs.disabled_reason.include?("rejected")
    "rejected"
  elsif account.payouts_enabled && account.charges_enabled
    if reqs.pending_verification
      "pending enablement"
    elsif !reqs.disabled_reason && !reqs.currently_due
      if !reqs.eventually_due
        "complete"
      else
        "enabled"
      end
    else
      "restricted"
    end
  elsif !account.payouts_enabled && account.charges_enabled
    "restricted (payouts disabled)"
  elsif !account.charges_enabled && account.payouts_enabled
    "restricted (charges disabled)"
  elsif reqs.past_due
    "restricted (past due)"
  elsif reqs.pending_verification
    "pending (disabled)"
  else
    "restricted"
  end
end

accounts = Stripe::Account.list(limit: 10)

accounts.each do |account|
    puts "#{account.id} has state: #{account_state(account)}"
end

Notiz

Sie können die API nicht verwenden, um auf Stripe-Risikoprüfungen zu antworten. Sie können Ihre verbundenen Konten aktivieren, damit diese über eingebettete Komponenten, von Stripe gehostetes Onboarding oder Sanierungslinks reagieren können. Außerdem können Sie im Auftrag Ihrer verbundenen Konten über das Dashboard auf Risikoprüfungen antworten.

Überwachen Sie das Ereignis account.updated. Wenn das Konto zum Zeitpunkt der current_deadline Felder mit der Bezeichnung currently_due enthält, wird die entsprechende Funktion deaktiviert und diese Felder werden zu past_due hinzugefügt.

Erstellen Sie ein Formular mit klaren Anweisungen, die das Konto verwenden kann, um die Angaben zu korrigieren. Benachrichtigen Sie das Konto und übermitteln Sie die korrigierten Angaben mithilfe der Accounts API.

Wenn Sie alle Ihre Verifizierungsfehler mit benutzerdefinierten Abläufen beheben möchten:

Überprüfen Sie die Details zu allen möglichen Verifizierungsfehlern und deren Handhabung.
Verifizierungsstatus testen