Marktplatz erstellen

Nutzen Sie die API /v2/core/accounts, um ein verbundenes Konto zu erstellen, indem Sie das Dashboard und die Zuständigkeiten des verbundenen Kontos angeben.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'

Falls Sie bereits Informationen für Ihre verbundenen Konten erfasst haben, können Sie diese im Account-Objekt vorab angeben. Sie können alle Kontoinformationen vorab ausfüllen, einschließlich persönlicher und geschäftlicher Informationen, externer Kontoinformationen usw.

Connect Onboarding fragt keine vorab ausgefüllten Informationen ab. Kontoinhaber/innen müssen vorausgefüllte Informationen jedoch bestätigen, bevor sie den Connect-Rahmenvertrag akzeptieren können.

Füllen Sie beim Testen Ihrer Integration die Kontoinformationen vorab mit Testdaten aus.

Konto-Link erstellen

Sie können einen Konto-Link erstellen, indem Sie die API Account Links v2 mit den folgenden Parametern aufrufen:

• account
• refresh_url
• return_url
• type = account_onboarding
• Konfigurationen =Empfänger/in und Händler/in

curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": 
"{{CONNECTED_ACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'

Nutzer/innen an die Konto-Link-URL weiterleiten

Die Antwort zum Erstellen eines Konto-Links enthält einen Werturl. Nachdem Sie die Nutzerin oder den Nutzer Ihrer Anwendung authentifiziert haben, leiten Sie sie/ihn zu dieser URL weiter, um sie/ihn an das Verfahren zu übergeben. Konto-Link-URLs sind temporär und können nur einmal verwendet werden, da sie Zugang zu den persönlichen Daten der Inhaber/innen der verbundenen Konten gewähren. Wenn Sie Informationen vorab angeben möchten, müssen Sie dies vor der Erstellung des Konto-Links tun. Nach der Erstellung des Konto-Links können Informationen für das verbundene Konto weder angezeigt noch geändert werden.

import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

Umgang mit Nutzerinnen/Nutzern, die zu Ihrer Plattform zurückkehren

Connect Onboarding verlangt, dass Sie sowohl eine return_url als auch eine refresh_url übergeben, um alle Fälle steuern zu können, in denen die Nutzer/innen der Konten an Ihre Plattform zurückgeleitet werden.

return_url

Stripe löst eine Weiterleitung zu dieser URL aus, wenn der/die Nutzer/in des verbundenen Kontos das Onboarding abschließt. Das heißt nicht, dass alle Informationen erfasst wurden oder keine offenen Anforderungen für das Konto bestehen. Es bedeutet lediglich, dass das Verfahren ordnungsgemäß durchlaufen und beendet wurde.

Über diese URL wird kein Status übergeben. Nachdem Nutzer/innen zu Ihrer return_url weitergeleitet wurden, überprüfen Sie den Status der Anforderungen für ihr Konto, indem Sie eine der folgenden Aktionen ausführen:

• Achten Sie auf v2.core.account[requirements].updated-Webhooks.
• Rufen Sie die API Accounts v2 auf und untersuchen Sie das zurückgegebene Objekt.

refresh_url

Stripe leitet Ihre Nutzer/innen in den folgenden Fällen an die refresh_url weiter:

• Der Link ist abgelaufen (seit Erstellung des Links sind ein paar Minuten vergangen).
• Die Nutzerin/der Nutzer hat die URL bereits aufgerufen (sie/er hat die Seite aktualisiert oder auf die Zurück/Vorwärts-Schaltfläche im Browser geklickt).
• Ihre Plattform hat keinen Zugang mehr zu diesem Konto.
• Das Konto wurde abgelehnt.

Konfigurieren Sie Ihre Seite refresh_url, um eine Methode auf Ihrem Server aufzulösen, durch die Account Links v2 erneut mit den gleichen Parametern aufgerufen und der/die Nutzer/in auf den neuen Link umgeleitet wird.

Umgang mit Nutzerinnen/Nutzern, die das Onboarding nicht abgeschlossen haben

Ein/e Nutzer/in, der/die an Ihre return_url weitergeleitet wird, hat das Onboarding möglicherweise nicht abgeschlossen. Verwenden Sie den Endpoint /v2/core/accounts, um das Konto des Nutzers/der Nutzerin abzurufen und zu prüfen, obconfiguration.recipient.capabilities.stripe_balance.stripe_transfers.status aktiv ist. Wenn der Status nicht aktiv ist undconfiguration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code requirements_past_due ist, geben Sie auf der Nutzeroberfläche Eingabeaufforderungen an, damit der/die Nutzer/in das Onboarding über einen neuen Konto-Link fortsetzen kann. Behandeln Sie andere Codes nach Bedarf.

Checkout-Sitzung erstellen Client and Server

Über eine Checkout-Sitzung wird gesteuert, was die Kundinnen/Kunden auf der von Stripe gehosteten Zahlungsseite sehen, z. B. Positionen, Bestellbetrag und Währung sowie die akzeptierten Zahlungsmethoden.

Fügen Sie Ihrer Website eine Schaltfläche zum Bezahlen hinzu, die einen serverseitigen Endpoint aufruft, um eine Checkout-Sitzung zu erstellen.

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

Führen Sie auf Ihrem Server den folgenden Aufruf der Stripe API durch. Leiten Sie Ihre Kundinnen/Kunden nach dem Erstellen einer Checkout-Sitzung zu der in der Antwort zurückgegebenen URL weiter.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=payment \
  -d "line_items[0][price]"=
"{{PRICE_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  -d "payment_intent_data[transfer_data][destination]"=
"{{CONNECTED_ACCOUNT_ID}}" \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

• line_items - Dieses Argument steht für Artikel, die Kundinnen/Kunden kaufen. Die Artikel werden in der von Stripe gehosteten Nutzeroberfläche angezeigt.
• success_url - Dieses Argument leitet Nutzer/innen weiter, nachdem sie eine Zahlung abgeschlossen haben.
• cancel_url - Dieses Argument leitet Nutzer/innen weiter, nachdem sie auf „Abbrechen“ geklickt haben.
• payment_intent_data[application_fee_amount] - Dieses Argument bestimmt den Betrag, den Ihre Plattform von der Transaktion abziehen will. Der vollständige Zahlungsbetrag wird sofort von der Plattform auf das mit transfer_data[destination] angegebene Konto übertragen, nachdem die Zahlung erfasst wurde. Anschließend wird der application_fee_amount zurück auf die Plattform übertragen und die Stripe-Gebühr wird vom Guthaben der Plattform abgezogen.
• payment_intent_data[transfer_data][destination]: Dieses Argument gibt an, dass es sich um eine Destination Charge handelt. Bei einer Destination Charge wird die Zahlung über die Plattform abgewickelt und alle Gelder werden sofort und automatisch in das ausstehende Guthaben des verbundenen Kontos übertragen. In unserem Beispiel für Wohnungsvermittlung sollen Kundinnen/Kunden über die Plattform bezahlen. Anschließend erhalten die Wohnungseigentümer entsprechende Auszahlungen von der Plattform.

Checkout verwendet die Markeneinstellungen Ihres Plattformkontos für Destination Charges. Weitere Informationen finden Sie unter Branding anpassen.

This Session creates a destination charge. If you need to control the timing of transfers or need to transfer funds from a single payment to multiple parties, use separate charges and transfers instead.

Mit Ereignissen nach der Zahlung umgehen Serverseitig

Stripe übermittelt ein checkout.session.completed-Ereignis, wenn die Zahlung abgeschlossen ist. Verwenden Sie einen Webhook, um diese Ereignisse zu empfangen und Aktionen auszuführen (Versenden einer Bestellbestätigung per E-Mail an die Kundinnen/Kunden, Erfassen des Verkaufs in einer Datenbank oder Einleiten des Versandablaufs).

Überwachen Sie diese Ereignisse, anstatt auf einen Callback vom Client zu warten. Auf dem Client könnten die Kund/innen das Browserfenster schließen oder die App beenden, bevor der Callback erfolgt ist. Einige Zahlungsmethoden benötigen auch 2 bis 14 Tage bis zur Zahlungsbestätigung. Wenn Sie Ihre Integration so einrichten, dass sie asynchrone Ereignisse überwacht, können Sie mehrere Zahlungsmethoden mit einer einzelnen Integration akzeptieren.

Neben der Abwicklung des Ereignisses checkout.session.completed empfehlen wir die Abwicklung von zwei weiteren Ereignissen, wenn Sie Zahlungen mit Checkout erfassen:

Diese Ereignisse beinhalten das Checkout-Sitzungsobjekt. Nach erfolgreicher Zahlung ändert sich der Status des zugrunde liegenden PaymentIntent von processing zu succeeded.