Zahlungen einziehen und anschließend auszahlen

Installieren Sie die offiziellen Bibliotheken von Stripe für den Zugriff auf die Stripe-API über Ihre Anwendung:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Wenn sich Nutzer/innen (Verkäufer oder Dienstleister) auf Ihrer Plattform anmelden, erstellen Sie ein zugehöriges Nutzerkonto (auch verbundenes Konto genannt). Ohne ein verbundenes Konto können Sie keine Zahlungen einziehen oder Gelder an das Bankkonto Ihrer Nutzer/innen überweisen. Verbundene Konten stellen Ihre Nutzer/innen in der Stripe API dar und helfen, die für die Identitätsprüfung der Nutzer/innen erforderlichen Informationen zu erfassen. In unserem Beispiel mit der Wohnungsvermittlung ist das verbundene Konto die Wohnungseigentümerin bzw. der Wohnungseigentümer.

Verbundenes Konto erstellen und Informationen vorab ausfüllen

Verwenden Sie die /v1/accounts API, um ein verbundenes Konto zu erstellen. Sie können das verbundene Konto erstellen, indem Sie die Eigenschaften des verbundenen Kontos oder den Kontotyp angeben.

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

Falls Sie bereits Informationen für Ihre verbundenen Konten erfasst haben, können Sie diese im Account-Objekt vorab angeben. Sie können beliebige Kontoinformationen vorab ausfüllen, einschließlich der Unternehmens- oder Personendaten, externer Kontodaten 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 Account Links API mit den folgenden Parametern aufrufen:

• account
• refresh_url
• return_url
• type = account_onboarding

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding

Nutzer/innen an die Konto-Link-URL weiterleiten

Die Antwort auf Ihre Account Links-Anfrage enthält einen Wert für den Schlüssel url. Leiten Sie Ihre Nutzer/innen an diesen Link weiter, um sie an das Verfahren zu übergeben. URLs von der Account Links API 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. Führen Sie die Authentifizierung der Nutzer/innen in Ihrer Anwendung durch, bevor Sie sie an diese URL weiterleiten. Wenn Sie Informationen vorab ausfüllen 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.

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 an Ihre Plattform weitergeleitet werden. Es ist wichtig, dass Sie diese URLs korrekt implementieren, um Ihren Nutzerinnen/Nutzern die bestmögliche Erfahrung zu bieten.

return_url

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

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

• account.updated-Webhooks überwachen
• Rufen Sie die Accounts-API auf und prüfen 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.

Ihre refresh_url sollte eine Methode auf Ihrem Server auslösen, um Account Links erneut mit denselben Parametern aufzurufen und Nutzer/innen an das Connect Onboarding zurückzuleiten, damit ein nahtloses Erlebnis entsteht.

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

Wenn Nutzer/innen an Ihre return_url weitergeleitet werden, haben sie das Onboarding möglicherweise nicht abgeschlossen. Rufen Sie mithilfe des Endpoints /v1/accounts das Nutzerkonto auf und prüfen Sie den Wert für charges_enabled. Wenn das Onboarding für das Konto nicht komplett abgeschlossen wurde, geben Sie den Nutzerinnen/Nutzern mithilfe entsprechender Eingabeaufforderungen der Nutzeroberfläche die Möglichkeit, das Onboarding zu einem späteren Zeitpunkt fortzusetzen. Diese können ihre Konto-Aktivierung über einen neuen (von Ihrer Integration generierten) Link abschließen. Anhand des Status des Parameters details_submitted im Nutzerkonto können Sie überprüfen, ob das Onboarding abgeschlossen wurde.

Zeigen Sie die Einstellungen für Ihre Zahlungsmethoden an und aktivieren Sie die Zahlungsmethoden, die Sie unterstützen möchten. Kartenzahlungen, Google Pay und Apple Pay werden standardmäßig aktiviert, Sie können Zahlungsmethoden jedoch nach Bedarf aktivieren und deaktivieren.

Bevor das Zahlungsformular angezeigt wird, wertet Stripe die Währung, Einschränkungen für Zahlungsmethoden und andere Parameter aus, um die Liste der unterstützten Zahlungsmethoden zu ermitteln. Zahlungsmethoden, die die Konversion steigern und die für die Währung und den Standort der Kundin/des Kunden am relevantesten sind, erhalten Priorität. Zahlungsmethoden mit niedrigerer Priorität sind in einem Überlaufmenü verborgen.

Verwenden Sie Stripe Checkout, um Zahlungen anzunehmen. Checkout unterstützt zahlreiche Zahlungsmethoden und zeigt Ihren Kundinnen/Kunden automatisch die für sie relevantesten an. Zahlungen können Sie mit Checkout akzeptieren, indem Sie eine von Stripe gehostete Seite nutzen oder ein vorkonfiguriertes Zahlungsformular direkt in Ihre Website integrieren. Über einen benutzerdefinierten Ablauf können Sie (mit Payment Element) außerdem verschiedenste Zahlungsmethoden mit einer einzigen Frontend-Integration annehmen.

Von Stripe gehostete Seite

Eingebettetes Formular

Benutzerdefinierter Ablauf

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.

checkout.html

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

Command Line

cURL

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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.

Diese Sitzung erstellt eine Destination Charge. Wenn Sie Übertragungen terminieren oder Gelder aus einer Zahlung an mehrere Parteien senden möchten, nutzen Sie stattdessen separate Zahlungen und Überweisungen. Wenn Sie separate Zahlungen nutzen möchten, finden Sie weitere Informationen unter Anderen Unternehmen gestatten, Zahlungen direkt anzunehmen.

Mit Ereignissen nach der Zahlung umgehen Server-side

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:

Ereignis	Beschreibung	Nächste Schritte
checkout.session.completed	Der/die Kund/in hat die Zahlung nach der Übermittlung des Checkout-Formulars erfolgreich autorisiert.	Warten Sie, bis die Zahlung erfolgt ist oder fehlschlägt.
checkout.session.async_payment_succeeded	Die Kundenzahlung war erfolgreich.	Führen Sie die Bestellung der gekauften Waren oder Dienstleistungen aus.
checkout.session.async_payment_failed	Die Zahlung wurde abgelehnt oder ist aus einem anderen Grund fehlgeschlagen.	Kontaktieren Sie den/die Kund/in per E-Mail und fordern Sie eine neue Bestellung von ihm/ihr an.

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

Testen Sie Ihren Ablauf zur Kontoerstellung, indem Sie Konten erstellen und OAuth verwenden.

Hier finden Sie weitere Informationen zum Testen Ihrer Integration.