Connect und die Accounts v2 API

Als Connect-Plattform ermöglichen Sie Ihren verbundenen Konten, Zahlungen zu akzeptieren. Sie können auch Zahlungen von Ihren verbundenen Konten akzeptieren, wenn sie Produkte kaufen oder Ihre Dienste abonnieren. In der Accounts v1 API erfordert die Verknüpfung dieser Käufe und Abos mit Ihrem verbundenen Konto ein separates Customer-Objekt, das Sie manuell mit dem Account-Objekt des verbundenen Kontos verknüpfen.

Mit der Accounts v2 API können Sie ein Account-Objekt erstellen, das alle Interaktionen mit Ihrem verbundenen Konto unterstützt, sodass Sie keine separaten Customer-Objekte erstellen und verfolgen müssen.

Accounts v2 API

Die Accounts v2 API bietet:

• Flexible Kontokonfigurationen: Sie können die Funktionen und die Kompatibilität eines verbundenen Kontos mit den Stripe-Funktionen aktivieren oder ändern, indem Sie seine Account-Konfigurationen ändern. Jede Funktion gehört zu einer bestimmten Konfiguration.
• Zentrale Identitätsdaten: Wenn Sie einem bestehenden Account-Objekt eine Konfiguration hinzufügen, um zusätzliche Funktionen zu aktivieren, müssen Sie Anforderungen nicht erneut erfassen, die sie bereits bereitgestellt haben.
• Eine einzige API für verbundene Konten und Kundenkonten: In den meisten Fällen können Sie jedes Kundenkonto mit einem Account-Objekt darstellen. So können Sie die Accounts v2 API verwenden, um sowohl verbundene Konten als auch Kundenkonten zu verwalten. Sie müssen die Customers API überhaupt nicht mehr verwenden.

Verbundene Konten mit Accounts v2 darstellen

In der Accounts v2 API weisen Sie einem Konto eine oder mehrere Konfigurationen zu, um verschiedene Funktionalitäten zu aktivieren. Zum Beispiel:

• Weisen Sie die merchant-Konfiguration zu, damit das Konto Zahlungen von Kunden/Kundinnen annehmen kann. Die merchant-Konfiguration umfasst die Funktionen card_payments und stripe_balance.payouts (ersetzt payouts in v1).
• Weisen Sie die customer-Konfiguration zu, damit das Konto als Kunde belastet werden kann. Sie können beim Erstellen eines Abos ein Konto mit der Konfiguration customer erstellen anstatt eines Kundenobjekts.
• Weisen Sie die recipient-Konfiguration zu, damit das Konto Überweisungen empfangen kann. Die recipient-Konfiguration enthält die Funktion stripe_balance.stripe_transfers (ersetzt die v1-Funktion transfers), die für die Verwendung indirekter Zahlungen erforderlich ist.

Im folgenden Beispiel wird ein Account-Objekt mit API v2 erstellt. Beachten Sie, dass sich die Struktur des Account-Objekts von der Struktur eines Account-Objekts in API v1 unterscheidet.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "dashboard": "full",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        },
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        }
    },
    "defaults": {
        "currency": "usd",
        "responsibilities": {
            "fees_collector": "stripe",
            "losses_collector": "stripe"
        },
        "locales": [
            "en-US"
        ]
    },
    "include": [
        "configuration.customer",
        "configuration.merchant",
        "identity",
        "requirements"
    ]
  }'

In der v1 API müssen Sie ein Account-Objekt erstellen, damit ein verbundenes Konto Zahlungen akzeptieren kann, und ein separates Customer-Objekt, um dieses Unternehmen Zahlungen zuzuordnen, die auf Ihrer Plattform vorgenommen werden. Accounts v1 und Customers v1 haben keine explizite Beziehung zueinander, daher müssen Sie diese Objekte separat verwalten und die Zuordnung der Account IDs zu den Customer IDs aufbewahren.

Konto erstellen

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d country=US \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[stripe_dashboard][type]"=express

Kundin/Kunden erstellen

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Jenny Rosen" \
  --data-urlencode email="jenny.rosen@example.com" \
  -d "metadata[account_id]]"=acct_1234

Konten mit Kundenkonfiguration verwenden

Jede API, die einen customer-Parameter akzeptiert, akzeptiert auch einen constumer_account-Parameter, über den Sie eine ID für ein Konto mit Kundenkonfiguration übergeben können.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-09-30.preview" \
  -d customer_account=acct_123 \
  -d "payment_method_types[]"=stripe_balance \
  -d confirm=true \
  -d usage=off_session \
  -d "payment_method_data[type]"=stripe_balance

Erfahren Sie mehr über die Verwendung von Konten als Kundinnen/Kunden.

Plattformen mit Accounts v1 und Customers v1 verbinden

Stripe unterstützt weiterhin die Accounts v1 API und die Customers v1 API. Sie können jedoch die Accounts v2 API verwenden, um Konten zu verwalten, die mit der Accounts v1 API erstellt wurden, einschließlich der Zuweisung der Customer-Konfiguration.

Überlegungen

Stripe rät davon ab, beide Versionen der Accounts API gleichzeitig auf unbestimmte Zeit zu behalten. Wenn für Ihre Plattform Folgendes gilt, sollten Sie weiterhin die v1 APIs verwenden:

• Verwendet OAuth, um sich für verbundene Konten zu authentifizieren
• Verwendet grenzüberschreitende Auszahlungen