Installationslinks verwendenÖffentliche Vorschau

Legen Sie Ihre allowed_redirect_uris in Ihrem App-Manifest fest. Dies sind die URLs, an die Nutzer/innen nach der Installation Ihrer App weitergeleitet werden. Sie müssen alle Weiterleitungs-URLs in Ihren App-Einstellungen angeben.

Nachdem Sie allowed_redirect_uris eingestellt haben, laden Sie eine neue Version Ihrer App hoch.

{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [],
  "app_backend": {},
  "ui_extension": {},
  "allowed_redirect_uris": [
    "https://example.com/callback/stripe"
  ]
}

Sie können externe Tests mit den folgenden Schritten durchführen, um den Installationslink zu testen, bevor Sie ihn zur Überprüfung übermitteln:

1. Erstellen Sie einen externen Test für Ihre App unter Verwendung der im App-Manifest definierten Version mit allowed_redirect_uris. Sie können die Testversion auf die gewünschte Version aktualisieren, wenn bereits ein Test existiert.
2. Die Registerkarte Externer Test enthält einen Test-Installationslink, und die zulässigen Weiterleitungen werden in einer Tabelle angezeigt.
3. Wenn Sie zur Veröffentlichung bereit sind, müssen Sie unbedingt eine neue Version hochladen, in der alle Test-URIs und -Werte durch die Werte ersetzt sind, die Sie in der Produktion verwenden möchten.

Wenn Sie die Tests abgeschlossen haben, können Sie sie mit den folgenden Schritten für alle Nutzer/innen verfügbar machen:

1. Veröffentlichen Sie eine neue Version Ihrer App, die allowed_redirect_uris definiert.
2. Klicken Sie auf die Registerkarte Einstellungen. Hier wird der Installationslink angezeigt. Diesen können sie kopieren. Der Link sieht wie folgt aus: https://marketplace.stripe.com/apps/install/link/{id}?redirect_uri=https://example.com.
3. Recommended Um CSRF-Angriffe zu verhindern, können Sie den empfohlenen Parameter state hinzufügen und ein eindeutiges Token als Wert übergeben. Wir fügen den von Ihnen angegebenen state hinzu, wenn Nutzer/innen auf Ihre Website weitergeleitet werden. Ihre Website kann bestätigen, dass der Parameter state nicht geändert wurde.
4. Nach dem Klick auf den Installationslink öffnet Stripe die folgende Seite. Auf dieser wählen die Nutzer/innen ein Konto aus, überprüfen die App-Details und können mit der Installation fortfahren.

Auswahl des Installationslinks für das Konto

Nachdem die Nutzer/innen Ihre App installiert haben, werden sie an den URL-Parameter redirect_uri weitergeleitet, der einer in allowed_redirect_uris definierten Weiterleitung in Ihrem App-Manifest entspricht.

Erfolgreiche Installation

Bei erfolgreichen Installationen enthält die URL Folgendes:

• Der Wert user_id. Die ID des Stripe Nutzers/der Stripe-Nutzerin, der/die die Installation initiiert hat.
• Der Wert account_id. Die ID des Stripe-Konto , das Ihre App installiert hat.
• Der Wert state, falls angegeben
• Der Wert install_signature. Dies ist ein Hash der obigen Werte, der mit dem Signaturgeheimnis Ihrer App generiert wurde.
• Wenn die App im Test-Modus oder in einer Sandbox-Umgebung installiert ist, wird der Wert livemode=false an die Weiterleitungs-URL angehängt.

Ein Beispiel für eine Weiterleitung im Live-Modus:

https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}

Ein Beispiel für eine Weiterleitung in den Test-Modus und eine Sandbox-Umgebung:

https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}&livemode=false

Installationsfehler

Wenn ein Nutzer/eine Nutzerin die Installation abbricht, wird er/sie trotzdem zu Ihrer Website weitergeleitet, aber die URL enthält stattdessen einen Fehler:

https://example.com/callback/stripe?error=access_denied&error_description=The%20user%20denied%20your%20request

Der/die Nutzer/in ist jetzt mit Ihrer App verbunden. Speichern Sie die stripe_user_id in Ihrer Datenbank. Dies ist die nuzterseitige Stripe-Konto-ID. Verwenden Sie diesen Wert, um sich als verbundenes Konto zu authentifizieren, indem Sie ihn in Anfragen im Stripe-Account-Header übergeben.

Überprüfen Sie die App-Installationen mit install_signature Recommended

Es ist wichtig zu überprüfen, ob der/die Nutzer/in Ihrer App autorisiert wurde, die App für das in der Umleitungs-URL angegebene Konto zu installieren. Aus diesem Grund ist eine install_signature enthalten. Diese Signatur wird aus dem Signaturgeheimnis Ihrer App und der user_id und account_id generiert, mit denen die Installation abgeschlossen wurde. Die Signatur enthält auch den übergebenen state, falls angegeben. Die Signatur kann nicht ohne Zugriff auf das Signaturgeheimnis repliziert werden, das nur intern für Stripe und das Backend Ihrer App verfügbar ist. Aus diesem Grund können böswillige Akteure den Hash nicht replizieren, wenn sie versuchen würden, die Umleitungs-URL zu fälschen. Durch Verifizieren der App-Signatur können Sie sicher sein, dass das Konto mit Ihrem/Ihrer App-Nutzer/in verbunden ist.

Um die Signatur zu verifizieren, befolgen Sie diese Schritte:

1. Erstellen Sie das Signaturgeheimnis Ihrer App, falls noch nicht geschehen.
2. Richten Sie ein App-Backend ein, um die install_signature zu verifizieren.

Beispiel für ein Backend zur Bestätigung der Installation:

Die Reihenfolge und Benennung der Nutzlastfelder ist bei der Signaturüberprüfung wichtig. Der state geht der user_id voraus und diese wiederum der account_id. Das resultierende Objekt sollte { state, user_id, account_id } lauten.

require 'stripe'
require 'sinatra'
require 'json'

Stripe.api_key = 'API_KEY'

get '/' do
  'Install Links verification example'
end

get '/verify' do
  user_id = params[:user_id]
  account_id = params[:account_id]
  state = params[:state]
  install_signature = params[:install_signature]

  payload = JSON.dump({
    state: state,
    user_id: user_id,
    account_id: account_id
  })

  begin
    Stripe::Webhook::Signature.verify_header(
      payload,
      install_signature,
      'STRIPE_APP_SECRET'
    )
  rescue Stripe::SignatureVerificationError => e
    return e.message, 400
  end

  { success: true }.to_json
end

set :port, 3000

Nach der Verifizierung können Sie für das installierte Konto API-Aufrufe durchführen.

Für serverseitige API-Aufrufe können Sie Anfragen als verbundene Konten stellen, indem Sie den speziellen Header Stripe-Account mit der Stripe-Kontokennung (sie beginnt mit dem Präfix acct_) Ihres Plattformnutzers/Ihrer Plattformnutzrin verwenden. Das folgende Beispiel zeigt, wie Sie mit dem geheimen API-Schlüssel Ihrer Plattform und der Konto-ID Ihres Nutzers/Ihrer Nutzerin einen PaymentIntent erstellen.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]"=card

Das Stripe-Account-Header-Verfahren wird in jeder API-Anfrage impliziert, die die Stripe-Konto-ID in der URL enthält. Das folgende Beispiel zeigt, wie Sie mit der Konto-ID Ihres/Ihrer Nutzers/in in der URL ein Konto abrufen.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Hier finden Sie weitere Beispiele dafür, wie Sie eine authentifizierte Anfrage durchführen.