Weiter zum Inhalt
Konto erstellen oder anmelden
Das Logo der Stripe-Dokumentation
/
Konto erstellenAnmelden
Übersicht
Kontoverwaltung
Zahlungsabwicklung
Plattformverwaltung

Testen der Kontobestätigung beim API-Onboarding

Eine exemplarische Vorgehensweise zum Testen verschiedener Verifizierungsstatus für verbundene Konten beim API-Onboarding mit Ihrem Test-API-Schlüssel.

In diesem Dokument wird davon ausgegangen, dass Sie mit dem API-Onboarding vertraut sind und wissen, wie Sie Konten aktualisieren und die Identitätsprüfung durchführen.

Testen Sie Ihre Verifizierungsabläufe, damit sie die Änderungen am Kontostatus handhaben können (z. B. wenn Sie Zahlungen aktivieren oder deaktivieren). Kontostatus ändern sich in der Regel, nachdem die Anforderungen erfüllt sind oder wenn Verarbeitungs- oder Zeitschwellenwerte erreicht werden. In den nachfolgenden Abschnitten werden diese Änderungen beschrieben, und es wird erläutert, wie Sie Ihre Verifizierungsabläufe testen können.

Ursprüngliche Anforderungen testen

Erstellen Sie zunächst ein neues verbundenes Konto in einer Sandbox, fügen Sie ein Bankkonto hinzu und weisen Sie nach, dass der Kontoinhaber/die Kontoinhaberin den Stripe-Rahmenvertrag akzeptiert hat. Stripe verlangt, dass das verbundene Konto den Rahmenvertrag von Stripe explizit akzeptiert, bevor Auszahlungen getätigt werden. In diesem Beispiel ist der identity.entity_type auf company festgelegt und external_account nutzt ein mit Token versehenes Stripe-Testkonto als Erinnerung, um zu vermeiden, dass sensible Informationen in den API-Aufrufen offengelegt werden.

Hinweis

Sie müssen einen Test-API-Schlüssel eines Stripe-Kontos, mit dem das Connect-Plattform-Onboarding begonnen hat. Der automatisch ausgefüllte Stripe-Test-API-Schlüssel führt dazu, dass diese Beispielanfragen fehlschlagen.

Wenn Sie das Account erstellen, müssen Sie das identity.country festlegen und die Funktionen card_payments und stripe_balance.stripe_transfers anfordern. Die folgenden Beispiele zeigen ein plattformgesteuertes Konto mit der Konfiguration merchant und recipient.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "identity": {
        "country": "US",
        "entity_type": "company",
        "attestations": {
            "terms_of_service": {
                "account": {
                    "date": "2019-01-19T19:51:13Z",
                    "ip": "172.18.80.19"
                }
            }
        }
    },
    "dashboard": "none",
    "defaults": {
        "responsibilities": {
            "losses_collector": "application",
            "fees_collector": "stripe"
        },
        "currency": "usd"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    }
  }'

Zu diesem Zeitpunkt ist das Konto erstellt, Zahlungen undAuszahlungen sind jedoch erst aktiviert, wenn Sie die Verifizierungsanforderungen erfüllen und eine Auszahlungsmethode beifügen. Überprüfen Sie das Array requirements.entries, um die Informationen zu ermitteln, die Sie erfassen müssen. Derzeit erforderliche Einträge haben den minimum_deadline.status currently_due.

{
  "id": "{% identifier type=\"connectedAccount\" quoteType=\"double\" /%}",
  "object": "account",
  "identity": {
    "country": "US",
    "entity_type": "company"
  },
  "dashboard": "none",
  "defaults": {
    "responsibilities": {
      "losses_collector": "application",
      "fees_collector": "stripe"
    },
    "currency": "usd"
  },
  "configuration": {
    "merchant": {
      "capabilities": {
        "card_payments": {
          "status": "restricted",
          "status_details": [
            {
              "code": "determining_status",
              "resolution": "provide_info"
            }
          ]
        }
      }
    },
    "recipient": {
      "capabilities": {
        "transfers": {
          "status": "restricted",
          "status_details": [
            {
              "code": "determining_status",
              "resolution": "provide_info"
            }
          ]
        }
      }
    }
  },
  "requirements": {
    "summary": {
      "minimum_deadline": { "time": 1700000000, "status": "currently_due" }
    },
    "entries": [
      { "id": "reqent_1", "description": "configuration.merchant.mcc", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_2", "description": "defaults.profile.business_url", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_3", "description": "identity.business_details.address.city", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_4", "description": "identity.business_details.address.line1", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_5", "description": "identity.business_details.address.postal_code", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_6", "description": "identity.business_details.address.state", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_7", "description": "identity.business_details.registered_name", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_8", "description": "identity.business_details.phone", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_9", "description": "identity.business_details.id_numbers.us_ein", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_10", "description": "relationship.representative", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_11", "description": "relationship.owner", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] }
    ]
  }
}

Anschließend können Sie die in der Antwort angegebenen erforderlichen Informationen erfassen und dem Account-Objekt hinzufügen.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "defaults": {
        "profile": {
            "business_url": "https://bestcookieco.com"
        }
    },
    "identity": {
        "business_details": {
            "address": {
                "city": "Schenectady",
                "line1": "123 State St",
                "postal_code": "12345",
                "state": "NY"
            },
            "id_numbers": [
                {
                    "type": "us_ein",
                    "value": "000000000"
                }
            ],
            "phone": "8888675309",
            "registered_name": "The Best Cookie Co"
        }
    }
  }'

Nach dem Aktualisieren der Unternehmensdaten können sich die Anforderungseinträge ändern. Für Person-Anforderungen müssen Sie unter dem Account-Objekt Person-Objekte für die Personen erstellen und aktualisieren, die Vertreter/innen oder Inhaber/innen des Unternehmens sind.

Verwenden Sie die Persons-API, um ein Profil für die Person zu erstellen, die Inhaber/in oder Vertreter/in des Kontos ist. In diesem Beispiel erstellen wir ein Profil für Jenny Rosen und kennzeichnen sie als representative mit dem title CEO.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "relationship": {
        "representative": true,
        "title": "CEO"
    }
  }'

Hinweis

Bei Konten, deren business_type auf individual festgelegt ist, geben Sie mindestens eine individual-Eigenschaft an (zum Beispiel individual.first_name) und ein Person-Objekt wird automatisch erstellt. Wenn Sie dies nicht durchführen oder für Konten, deren business_type auf company festgelegt ist, müssen Sie jede Person für das Konto erstellen.

Wenn Sie eine Person erstellen, enthält die Antwort einen requirements.entries-Hash. Dieser führt die erforderlichen Verifizierungsinformationen für die jeweilige Person auf.

{
  "id": "person_abc",
  "object": "person",
  "requirements": {
    "entries": [
      { "id": "p_req_1", "description": "representative.address.city", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_2", "description": "representative.address.line1", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_3", "description": "representative.address.postal_code", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_3", "description": "representative.address.state", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
``
      { "id": "p_req_4", "description": "representative.date_of_birth.day", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_5", "description": "representative.date_of_birth.month", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_6", "description": "representative.date_of_birth.year", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_7", "description": "representative.phone", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_8", "description": "representative.email", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_9", "description": "identity.attestations.persons_provided.owners", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_10", "description": "representative.id_numbers. us_ssn_last_4", "minimum_deadline": { "status": "currently_due" }, "errors": [] }
    ]
  }
}

Nachdem Sie eine Person erstellt und die angeforderten Angaben zur Person gemacht haben, enthält requirements.entries des Kontos Beschreibungen, die auf die Personen-ID verweisen.

Aktualisieren Sie die Person, um die angeforderten Verifizierungsinformationen für Jenny Rosen bereitzustellen:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons/
{{PERSON_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "address": {
        "city": "Schenectady",
        "line1": "123 State St",
        "postal_code": "12345",
        "state": "NY"
    },
    "date_of_birth": {
        "day": 10,
        "month": 11,
        "year": 1980
    },
    "id_numbers": [
        {
            "type": "us_ssn_last_4",
            "value": "0000"
        }
    ],
    "phone": "8888675309",
    "email": "jenny@example.com",
    "relationship": {
        "executive": true
    }
  }'

Indem Sie relationship.executive als True festlegen, versichern Sie gegenüber Stripe, dass es der Vertreter/die Vertreterin eine maßgebliche Führungsrolle innerhalb der Organisation innehat. Unter für die USA erforderlichen Verifizierungsinformationen finden Sie weitere Informationen zu den Details zur Verifizierung von Unternehmensvertretern/-vertreterinnen für US-Unternehmen.

Um einen Inhaber/eine Inhaberin hinzuzufügen, erstellen Sie eine weitere Person und kennzeichnen Sie ihn/sie als owner des Kontos. In diesem Beispiel besitzt Kathleen Banks 80 % von The Best Cookie Co.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "given_name": "Kathleen",
    "surname": "Banks",
    "email": "kathleen@example.com",
    "relationship": {
        "owner": true,
        "percent_ownership": "80"
    }
  }'

Sie müssen alle Inhaber/innen hinzufügen, die mindestens 25 % des Unternehmens besitzen, und anschließend identity.attestations.persons_provided.owners auf True setzen.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "identity": {
        "attestations": {
            "persons_provided": {
                "owners": true
            }
        }
    }
  }'

Ein erfolgreiches Onboarding Ihres verbundenes Konto in dieser Phase bedeutet:

  • Sie haben alle erforderlichen Informationen angegeben (requirements.summary.minimum_deadline=null).
  • Zahlungen für das Konto (charges_enabled=true) aktiviert werden.
  • Sie haben ein v2.core.account.updated webhook-Ereignis von Stripe erhalten.

Testschwellen

Unabhängig davon, ob Sie Upfront-Onboarding oder inkrementelles Onboarding verwenden, kann Stripe weitere Informationen über verbundene Konten anfordern, sobald bestimmte Schwellenwerte erreicht sind. Beispielsweise können nach einem Transaktionsvolumen in Höhe von 1.500 USD oder 30 Tagen nach der Kontoerstellung weitere Informationen erforderlich sein. Um herauszufinden, welche Informationen möglicherweise später erforderlich werden, sobald ein Konto einen Schwellenwert erreicht, überprüfen Sie das Array requirements.entries auf Anforderungen mit minimum_deadline.status eventually_due.

Wenn Sie die erforderlichen Informationen nicht bis zu einem bestimmten Datum bereitstellen, werden Zahlungen und Auszahlungen möglicherweise deaktiviert. Sie können diese Szenarien zu Testzwecken auslösen.

Auslöseschwellen

Sie können mit dem Verifizierungs-Token (tok_visa_triggerVerification) eine Zahlung erstellen, um einen allgemeinen Verifizierungsgrenzwert auszulösen. Dadurch werden weder Zahlungen noch Auszahlungen blockiert, jedoch wird die Anforderung zusätzlicher Informationen ausgelöst. Wenn Sie das Webhook-Ereignis v2.core.account[requirements].updated beobachten, können Sie Folgendes prüfen:

  • requirements.entries für Einträge, deren minimum_deadline.status currently_due ist
  • requirements.summary.minimum_deadline.time, um die früheste Frist für diese Einträge zu ermitteln

Um Szenarien zu testen, in denen die erforderlichen Informationen nicht fristgerecht bereitgestellt werden, finden Sie in den Abschnitten Zahlungen und Auszahlungen blockieren weiter unten.

Sie können auch spezifischere Verifizierungsauslöser auslösen, wie z. B. Identität stimmt nicht überein oder OFAC-Schwelle. Das Testen dieser Szenarien ist sinnvoll, da sie häufig auftreten, wenn die Verifizierung fehlschlägt.

Blockierte Zahlungen testen

Sie können Zahlungen blockieren, indem Sie mit dem Token Zahlung blockieren (tok_visa_triggerChargeBlock) eine Testzahlung erstellen. Anschließend sollten Sie das Webhook-Ereignis v2.core.account[requirements].updated erhalten, das Folgendes anzeigt:

  • Der Status der relevanten Funktion für Kartenzahlungen ist nicht aktiv (zum Beispiel ist configuration.merchant.capabilities.card_payments.status nicht aktiv)
  • Erforderliche Informationen im Array requirements.entries (mit minimum_deadline.status und currently_due)
  • Alle Einträge, die noch nicht erforderlich sind, werden als minimum_deadline.status und eventually_due angezeigt

Sie können dann das Konto aktualisieren und die neuen Informationen hinzufügen. Dadurch wird ein weiteres Webhook-Ereignis ausgelöst, das anzeigt, dass Zahlungen aktiviert sind und derzeit keine fälligen oder irgendwann fälligen Anforderungen vorliegen.

Blockierte Auszahlungen testen

Sie können Auszahlungen blockieren, indem Sie eine Testzahlung mit dem block transfer-Token (tok_visa_triggerTransferBlock) erstellen. Anschließend sollten Sie das Webhook-Ereignis v2.core.account.updated erhalten, das Folgendes anzeigt:

  • capabilities.stripe_balance.payouts.status in der Konfiguration Händler/in oder Empfänger/in ist nicht aktiv
  • Derzeit erforderliche Informationen im Array requirements.entries mit minimum_deadline.status von currently_due
  • Schließlich erforderliche Anforderungen im Array requirements.entries mit minimum_deadline.status von eventually_due

Sie können das Konto mit neuen Informationen aktualisieren. Dadurch wird ein weiteres Webhook-Ereignis ausgelöst, das signalisiert, dass Auszahlungen aktiviert sind und dass die Arrays requirements.summary and requirements.summary.minimum_deadline leer sind.