Die Accounts v2 API in Ihrer vorhandenen Integration verwenden

Befolgen Sie diesen Leitfaden, wenn Sie die Integration Ihrer Accounts v1- und Customers v1 Connect-Plattformintegration aktualisieren möchten, um Zugriff auf die folgenden Accounts v2-Funktionen zu erhalten:

• Verknüpfen Sie Ihre verbundenen Konten mit Zahlungen, die sie an Ihre Plattform leisten, ohne Customer-Objekte zu erstellen.
• Vermeiden Sie Netzwerkkosten, indem Sie verbundenen Konten erlauben, Ihre Plattform mit ihrem Stripe-Guthaben zu bezahlen.
• Aktivieren Sie in Ihren verbundenen Konten, dass sie Gelder auf Ihrer Plattform mit v2 Financial Accounts halten dürfen.

Wenn Sie keine Accounts v2-Funktionen benötigen, können Sie weiterhin Ihre Accounts v1 und Customers v1-Plattformintegration verwenden.

v2-Endpoints für alle Ihre Konten verwenden

Sie können die Accounts v2 API mit Ihren bestehenden v1-Accounts verwenden, ohne diese zu ändern.

Kundenkonfiguration hinzufügen

Durch Hinzufügen der customer-Konfiguration zu einem Account-Objekt können Sie die Account ID in jeder API-Anfrage angeben, die eine Customer ID akzeptiert, z. B. beim Erstellen eines Abos. Anstatt eine Customer ID im Parameter customer anzugeben, geben Sie die Account ID im Parameter customer_account an.

Im folgenden Beispiel wird die Accounts v2 API verwendet, um die customer-Konfiguration zu einem bestehenden v1 Account hinzuzufügen, und dann ein bestehendes Abo zur Abbuchung vom Konto über das Stripe-Guthaben aktualisiert.

1. Aktualisieren Sie das Account-Objekt, um die customer-Konfiguration hinzuzufügen.

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'

1. Retrieve the connected account to confirm it has the card_payments capability in the merchant configuration. This capability must be active in order to use the Stripe balance as a payment method.

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "include": [
        "configuration.merchant",
        "identity",
        "defaults"
    ]
  }'

1. Add the connected account’s Stripe balance as a payment method.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer_account=acct_1abc \
  -d "payment_method_types[]"=stripe_balance \
  -d confirm=true \
  -d usage=off_session \
  -d "payment_method_data[type]"=stripe_balance

1. Create a subscription that charges the connected account using its Stripe balance.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer_account=acct_1abc \
  -d payment_behavior=default_incomplete \
  -d "items[0][price]"={{PRICE_ID}} \
  -d "payment_settings[save_default_payment_method]"=on_subscription

Sie müssen kein separates Customer-Objekt mehr führen, um Abozahlungen von diesem verbundenen Konto zu akzeptieren.

Ihre Integration schrittweise umstellen

Da Sie sowohl die Accounts v1 API als auch die v2 API mit Ihren Accounts verwenden können, können Sie Ihre Integration in dem Tempo aktualisieren, wie es für Ihr Unternehmen passt. Beispielsweise können Sie:

• Rufen Sie /v2/core/accounts-Endpoints für Accounts auf, die mit API v1 erstellt wurden.
• Rufen Sie /v1/accounts-Endpoints für Accounts auf, die mit API v2 erstellt wurden.
• Rufen Sie /v1/customers-Endpoints für Accounts mit der Kundenkonfiguration auf.
• Verwenden Sie die Events API v2, um auf Änderungen an Objekten zu warten, die mit einer der beiden API-Versionen erstellt wurden.

Mit diesen Kompatibilitäten können Sie Ihre Integration schrittweise aktualisieren, ohne mehrere Versionen gleichzeitig in der Produktion beizubehalten oder Ihre gesamte Integration auf einmal zu aktualisieren.

Wir empfehlen, Ihre Integration in dieser Reihenfolge zu aktualisieren:

1. Richten Sie einen neuen Endpoint ein, um auf v2-Ereignisse zu warten.
2. Ändern Sie Ihre create-Aufrufe für Account und Customer, um Accounts mit Kundenkonfiguration unter Verwendung von /v2/core/accounts zu erstellen.
3. Ändern Sie Ihre update-Aufrufe für Account und Customer, um /v2/core/accounts zu verwenden.
4. Ändern Sie Ihre retrieve-Aufrufe für Account und Customer, um /v2/core/accounts zu verwenden.

v2-Account-Objekte in v1-Endpoints verwenden

Wenn Sie in v1-Endpoints auf v2-Objekte verweisen, gibt die Antwort die v2-Daten in der v1-Objektstruktur zurück. Beispiel:

• Durch Verweisen auf ein v2-Account-Objekt in einem Endpoint /v1/accounts werden die Daten in der Struktur eines v1-Account-Objekts zurückgegeben.
• Durch Verweisen auf ein v2-Account-Objekt in einem Endpoint /v1/customers werden die Daten in der Struktur eines v1-Customer-Objekts zurückgegeben, die sowohl die customer ID als auch die customer_account ID enthält.

curl https://api.stripe.com/v1/customers/acct_1abc \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d business_name="Furever Plus"

Sie können Account-Objekte mit Kundenkonfiguration in der Customers v1 API verwenden, aber Sie können in der Accounts v2 API nicht auf v1-Customer-Objekte verweisen. Sie müssen Kundendaten entweder in ein neues Account-Objekt mit Kundenkonfiguration migrieren oder ein bestehendes verbundenes Konto aktualisieren, um die customer-Konfiguration hinzuzufügen.

Webhook-Ereignisse

Accounts senden sowohl v1-Ereignisse (Snapshot) als auch v2-Ereignisse (Thin). Wir empfehlen, einen neuen Endpoint einzurichten, um Accounts v2-Ereignisse zu überwachen.

1. Öffnen Sie in Ihrem Stripe-Dashboard das Menü „Entwickler/innen“, indem Sie in der Fußzeile des Navigationsmenüs auf Entwickler/innen klicken und dann Webhooks auswählen.
2. Klicken Sie auf + Ziel hinzufügen.
3. Wählen Sie im Abschnitt Ereignisse aus die Option Verbundene Konten aus.
4. Wählen Sie Erweiterte Optionen anzeigen aus. Wählen Sie im Abschnitt „Nutzlast-Stil“ die Option Thin aus.
5. Wählen Sie im Feld „Ereignisse“ ein oder mehrere Ereignisse aus, die der Version des Account-Objekts entsprechen:
   • Geben Sie für v1 „v1“ ein, um nach v1-Objektereignistypen zu suchen. Wählen Sie v1.account.updated aus.
   • Geben Sie für v2 „v2“ ein, um nach v2-Objektereignistypen zu suchen. Wählen Sie v2.core.account.updated oder ein anderes v2.core.account[*].updated-Ereignis aus.
6. Fahren Sie mit der Einrichtung Ihres Ereignisziels fort, indem Sie dem interaktiven Webhook-Endpoint-Generator folgen.

Beispielsweise kann bei der Aktualisierung eines Account-Objekts einer der Versionen Folgendes gesendet werden:

• Ein v1-Ereignis account.updated
• Ein v2-Ereignis v1.account.updated
• Ein v2-Ereignis v2.core.account.updated

Unterschiede der Account-Version in der Events v2 API

Die meisten Ereignistypen von v2.core.account entsprechen nicht direkt den Ereignistypen von v1.account. Wenn Sie beispielsweise eine Eigenschaft für ein Account ändern, wird das Ereignis v1.account.updated ausgelöst. Dieselbe Aktion kann jedoch eigenschaftenspezifische Ereignisse für v2 auslösen, wie z. B. v2.core.account[identity].updated oder v2.core.account[configuration.recipient].updated.

Wir senden das Ereignis v2.core.account.updated nur für Aktualisierungen von Top-Level-Eigenschaften wie dashboard oder display_name, die keines der spezifischeren Aktualisierungsereignisse auslösen.

Einschränkungen der Accounts API v2

In den folgenden Fällen müssen Sie Accounts v1 verwenden:

• Mit OAuth verbundene Konten
• Konten, für die ein Rahmenvertrag für Empfänger/innen unterzeichnet wurde
• Zur Anfrage oder Verwaltung der folgenden Funktionen:
  • treasury
  • card_issuing_*
  • eingestellte Funktionen wie legacy_payments
  • eingestellte Zahlungsmethoden
  • Zahlungsmethoden in der öffentlichen oder privaten Vorschau