Onboarding-Lösungen für Custom-Konten

Stripe bietet mehrere Möglichkeiten für das Onboarding von verbundenen Custom-Konten. Sie entscheiden sich einfach für das Onboarding, das am besten zu Ihrem Unternehmen passt.

Von Stripe gehostetes Onboarding

Mit dem von Stripe gehosteten Onboarding leiten Sie Ihre Nutzer/innen zu Stripe weiter, wo diese das Onboarding in einer Umgebung mit Co-Branding abschließen können. Erstellen Sie einen Konto-Link und leiten Sie Ihre Nutzer/innen zum gehosteten Onboarding weiter. Über die return_url kann Stripe Ihre Nutzer/innen zu Ihrer Anwendung zurücksenden und das Onboarding für das verbundene Konto fortsetzen.

Um von Stripe gehostetes Onboarding zu integrieren, befolgen Sie unseren Leitfaden für von Stripe gehostetes Onboarding.

Eingebettetes Onboarding

Die Nutzeroberfläche des eingebetteten Onboardings hat nur wenig Stripe-Branding und kann perfekt an Ihre Marke angepasst werden. Nutzer/innen der verbundenen Konten interagieren mit der eingebetteten Komponente, ohne Ihre Anwendung verlassen zu müssen. Beim eingebetteten Onboarding wird die Accounts API verwendet, um Anforderungen zu ermitteln und ein Onboarding-Formular mit zuverlässiger Datenvalidierung zu generieren, das für alle von Stripe unterstützten Länder lokalisiert ist. Darüber hinaus übernimmt das eingebettete Onboarding Folgendes:

• Unternehmenstypen
• Konfigurationen der Unternehmensvertreter/innen
• Verifizierungsdokument wird hochgeladen
• Verifizierungs- und Statusangaben ermitteln
• Internationale Bankkonten
• Fehlerstatus

Sie können das eingebettete Onboarding mit wenigen Codezeilen integrieren, während Sie beim API-basierten Onboarding eine nutzerdefinierte Logik erstellen müssen. Um das eingebettete Onboarding zu integrieren, folgen Sie unserem Leitfaden für eingebettete Komponenten und integrieren Sie die eingebettete Konto-Onboarding-Komponente.

API-gestütztes Onboarding

Beim API-gestützten Onboarding werden alle Aspekte der Onboarding-Benutzeroberfläche Ihrer Website so erweitert, dass die entsprechenden Stripe-APIs aufgerufen werden. Ihre Integration muss alle Onboarding-Anforderungen von Stripe erfüllen.

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 business_type (zum Beispiel Einzelperson oder Unternehmen) und die company.structure (zum Beispiel public_corporation oder private_partnership)

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

// 〒150-0001 東京都渋谷区神宮前1-5-8 神宮前タワービルディング22F
{
  "country": "JP",
  "legal_entity": {
    "address_kana": {
      "country": "JP", // 2-letter country code
      "postal_code": "1500001", // Zip/Postal Code
      "state": "ﾄｳｷﾖｳﾄ", // Prefecture
      "city": "ｼﾌﾞﾔ", // City/Ward
      "town": "ｼﾞﾝｸﾞｳﾏｴ 1-", // Town/cho-me
      "line1": "5-8", // Block/Building number
      "line2": "ｼﾞﾝｸﾞｳﾏｴﾀﾜｰﾋﾞﾙﾃﾞｨﾝｸﾞ22F", // Building details (optional)
    },
    "address_kanji": {
      "country": "JP", // 2-letter country code
      "postal_code": "１５００００１", // Zip/Postal Code
      "state": "東京都", // Prefecture
      "city": "渋谷区", // City/Ward
      "town": "神宮前　１丁目", // Town/cho-me (no kanji numerals)
      "line1": "５－８", // Block/Building number
      "line2": "神宮前タワービルディング22F", // Building details (optional)
    }
  }
}

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=custom \
  -d country=JP \
  -d business_type=company \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true \
  -d "settings[payments][statement_descriptor]"="example descriptor" \
  -d "settings[payments][statement_descriptor_kanji]"="漢字明細" \
  -d "settings[payments][statement_descriptor_kana]"="カナメイサイ"

curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -F "purpose"="account_requirement" \
  -F "file"="@/path/to/a/file"

{
  "id": "file_5dtoJkOhAxrMWb",
  "created": 1403047735,
  "size": 4908
}

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "documents[proof_of_registration][files][]"=file_5dtoJkOhAxrMWb

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[ownership_declaration][date]"=1609798905 \
  -d "company[ownership_declaration][ip]"="8.8.8.8" \
  --data-urlencode "company[ownership_declaration][user_agent]"="Mozilla/5.0"

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[ownership_declaration][date]"=1609798905 \
  -d "company[ownership_declaration][ip]"="8.8.8.8" \
  --data-urlencode "company[ownership_declaration][user_agent]"="Mozilla/5.0"

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[ownership_declaration][date]"=1609798905 \
  -d "company[ownership_declaration][ip]"="8.8.8.8" \
  --data-urlencode "company[ownership_declaration][user_agent]"="Mozilla/5.0"

curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -F "purpose"="account_requirement" \
  -F "file"="@/path/to/a/file"

{
  "id": "file_5dtoJkOhAxrMWb",
  "created": 1403047735,
  "size": 4908
}

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "documents[proof_of_registration][files][]"=file_5dtoJkOhAxrMWb

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[ownership_declaration][date]"=1609798905 \
  -d "company[ownership_declaration][ip]"="8.8.8.8" \
  --data-urlencode "company[ownership_declaration][user_agent]"="Mozilla/5.0"

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "alternatives": [
      {
        "original_fields_due": [
          "documents.proof_of_ultimate_beneficial_ownership.files",
        ],
        "alternative_fields_due": [
          "company.ownership_exemption_reason",
        ]
      }
    ],
    "errors": [
      {
        "code": "verification_rejected_ownership_exemption_reason",
        "reason": "The ownership exemption reason was rejected.",
        "requirement": "company.ownership_exemption_reason"
      }
    ],
    ...
  },
  ...
}

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "errors": [
      {
        "code": "verification_missing_owners",
        "requirement": "documents.proof_of_ultimate_beneficial_ownership.files",
        "reason": "..."
      },
      ...
    ],
    ...
  },
  ...
}

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "errors": [
      {
        "code": "verification_document_directors_mismatch",
        "requirement": "documents.proof_of_ultimate_beneficial_ownership.files",
        "reason": "..."
      },
      ...
    ],
    ...
  },
  ...
}

Formulare erstellen, um Informationen zu erfassen

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 die Art der Rahmenvereinbarung zu ändern, erstellen Sie ein neues verbundenes Konto mit den neuen Werten. Dadurch entstehen neue Anforderungen, die Sie in Ihre Zahlungsablä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

Verwenden Sie die API zum Erstellen von Konten, um ein verbundenes Konto mit Land, Vereinbarung über die Art der Dienstleistung, den gewünschten Funktionen, dem Unternehmenstyp und allen anderen Informationen zu erstellen, die Ihren Anforderungen entsprechen. Sie müssen mindestens die Parameter capabilities und type angeben. Wenn Sie keine anderen Parameter angeben, werden ihnen die folgenden Standardwerte zugewiesen:

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

Mit dem folgenden Codebeispiel wird ein verbundenes Custom-Konto mit card_payments und transfers im Rahmen eines umfassenden Rahmenvertrags für eine Einzelperson erstellt.

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

Führen Sie Ihr Konto durch den Onboarding-Ablauf

Sie können verbundene Konten auf zwei Arten aktivieren:

• Inkrementelle Onboarding-Strategie: Erforderliche Informationen im Voraus einholen und den Rest später einholen
• Onboarding-Strategie im Voraus: Informationen im Voraus einholen

Beim inkrementellen Onboarding läuft das anfängliche Onboarding selbst schneller ab, zu einem späteren Zeitpunkt sind jedoch zusätzliche Informationen erforderlich. Wenn Sie sich für das Onboarding im Voraus entscheiden, kommt es während des gesamten Lebenszyklus des Kontos kaum zu Unterbrechungen, das Antragsverfahren ist jedoch umfangreicher. Sie können selbst entscheiden, welche Strategie besser zu Ihren Anwendungsszenarien passt.

Um Ihre Onboarding-Strategie umzusetzen, prüfen Sie den Anforderungs-Hash des von Ihnen erstellten verbundenen Kontos. Der Anforderungs-Hash enthält eine vollständige Liste der Parameter, die Sie erfassen müssen, um das verbundene Konto zu aktivieren.

• Wenn Sie sich für die inkrementelle Onboarding-Strategie entscheiden, prüfen Sie das Feld currently_due im Anforderungs-Hash und erstellen ein Onboarding, das nur die aufgeführten Parameter erfasst.
• Wenn Sie sich für die Onboarding-Strategie im Voraus entscheiden, prüfen Sie das Feld eventually_due im Anforderungs-Hash und erstellen ein Onboarding, das alle aufgeführten Parameter erfasst.

{
  ...
  "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

Aktualisieren Sie neue Informationen des verbundenen Account-Objekts, während dieses Ihr Onboarding durchläuft. Führen Sie einen Kontoaktualisierungs-Aufruf durch und ermitteln Sie das verbundene Konto anhand des zuvor gespeicherten id-Wertes.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode "business_profile[url]"="https://furever.dev" \
  -d "tos_acceptance[date]"=1609798905 \
  -d "tos_acceptance[ip]"="8.8.8.8"

Stripe validiert jede Aktualisierung eines verbundenen Kontos. Aktualisieren Sie das Konto bei jedem Onboarding-Schritt, damit Stripe die Informationen überprüfen kann, sobald sie hinzugefügt werden. Ihre Nutzer/innen können währenddessen mit dem Onboarding fortfahren. 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.

Beim Aktualisieren eines verbundenen Kontos müssen Sie alle Verifizierungsfehler oder HTTP-Fehlercodes, die von der Accounts API zurückgegeben werden, handhaben.

Verifizierungsabwicklung

Nachdem die Daten des verbundenen Kontos übermittelt wurden, verifiziert Stripe diese. Dieser Vorgang kann je nach Art der Verifizierung Minuten oder Stunden dauern. Während der Ausführung dieses Vorgangs befinden sich die angeforderten Funktionen im status pending.

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, wird eine Funktion active und steht dem verbundenen Konto zur Verfügung. 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.

# 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_BQokikJOvBiI2HlWgH4olfQ2'

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

Umgang mit Verifizierungsfehlern

Gehen Sie je nach Onboarding-Prozess unterschiedlich mit fehlgeschlagenen Verifizierungen um.