Fügen Sie eine serverseitige Logik hinzu

Um Nutzer/innen über das Dashboard zu authentifizieren, benötigt das Backend eine Signatur mit dem gemeinsam genutzten Geheimschlüssel, das Konto und die Nutzer-ID der aktuellen, angemeldeten Dashboard-Nutzer/innen. Wenn Ihr/e Nutzer/in nicht befugt ist, die API aufzurufen, gibt Stripe einen Berechtigungs-Fehler zurück.

Bevor Sie loslegen

1. Achten Sie darauf, dass Ihr Backend-Dienst HTTP-Anfragen senden und empfangen kann. Wenn Sie noch keinen API-Server erstellt haben, sollten Sie den Interaktiven Webhook Endpoint Builder ausprobieren.

2. App hochladen und freigegebenen Geheimschlüssel erstellen:

   Command Line

   stripe apps upload

   Es ist kein Problem, wenn Sie die Entwicklung der aktuellen Version Ihrer App noch nicht abgeschlossen haben. Durch das Hochladen wird Ihre App im Live-Modus nicht aktualisiert.

3. Erhalten Sie den Geheimschlüssel Ihrer App, um die Signatur in Ihrem Backend zu verifizieren:

   a. Rufen Sie die Detailseite Ihrer Stripe-App auf, indem Sie Ihre App unter Apps auswählen.

   b. Um den Geheimschlüsseldialog zu öffnen, klicken Sie unter der Anwendungs-ID auf das Überlaufmenü () und dann auf Geheimschlüssel für Signatur.

   c. Nun klicken Sie auf das Clipboard , um den Geheimschlüssel aus dem Dialogfeld zu kopieren.

Eine signierte Anfrage senden

So senden Sie eine signierte Anfrage an das Backend der App:

1. Rufen Sie die aktuelle Signatur mit der asynchronen Funktion fetchStripeSignature ab.
2. Fügen Sie die Signatur dem Header Stripe-Signature hinzu.
3. Nehmen Sie die Objekte user_id und account_id in die Anfrage auf.
4. Überprüfen Sie im Backend der App, ob die Anfrage die Signatur, den Geheimschlüssel der App, user_id und account_id enthält.

Hier ist ein Beispiel für den Versand einer signierten Anfrage mit zusätzlichen Daten.

Eine Beispielanfrage von einer Stripe-App mit dem Header Stripe-Signature:

import {fetchStripeSignature} from '@stripe/ui-extension-sdk/utils';

const App = ({ userContext, environment }: ExtensionContextValue) => {
  const makeRequestToMyBackend = async (endpoint, requestData) => {
    // By default the signature is signed with user id and account id.
    const signaturePayload = {
      user_id: userContext?.id,
      account_id: userContext?.account.id,
    };
    return fetch(`https://example.com/${endpoint}/`, {
      method: 'POST',
      headers: {
        'Stripe-Signature': await fetchStripeSignature(),
        'Content-Type': 'application/json',
      },
      // Include the account ID and user ID in the body to verify on backend.
      body: JSON.stringify({
        ...requestData,
        ...signaturePayload,
      }),
    });
  };
  ...
}

Beispiel für ein Backend zur Überprüfung der Anfrage:

Bitte beachten Sie, dass die Reihenfolge und Benennung der Nutzlastfelder bei der Signaturüberprüfung wichtig ist. Die user_id steht vor der account_id, und das resultierende Objekt lautet wie folgt: { user_id, account_id }

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(process.env.STRIPE_API_KEY);
const express = require('express');

// Find your app's secret in your app settings page in the Developers Dashboard.
const appSecret = 'absec_...';

// This example uses Express.
const app = require('express')();
app.use(express.json());

// Match the raw body to content type application/json.
app.post('/do_secret_stuff', (request, response) => {
  const sig = request.headers['stripe-signature'];
  // Retrieve user id and account id from the request body
  const payload = JSON.stringify({
    user_id: request.body['user_id'],
    account_id: request.body['account_id']
  });
  try {
    // Verify the payload and signature from the request with the app secret.
    stripe.webhooks.signature.verifyHeader(payload, sig, appSecret);
  } catch (error) {
    response.status(400).send(error.message);
  }
  // Handle the request by returning a response
  // to acknowledge receipt of the event.
  response.json({ success: true });
});

app.listen(3000, () => console.log('Running on port 3000'));

Eine signierte Anfrage mit zusätzlichen Daten senden

Die Nutzerauthentifizierung kann auch durch Übermittlung einer signierten Anfrage mit einer Nutzlast (zusätzliche Daten) erfolgen. Wenn Sie die Funktion fetchStripeSignature mit einer Anfrage für eine zusätzliche Nutzlast aufrufen, erstellen Sie eine Signatur mit user_id, account_id und der zusätzlichen Nutzlast, die Sie in die Funktion übergeben haben. Standardmäßig verwenden Stripe-Apps user_id und account_id zum Generieren der Signaturzeichenfolge.

Beispiel für das Generieren eines Geheimschlüssels mit zusätzlicher Nutzlast:

// A valid payload object has keys of type string
// and values of type string, number, or boolean.
const payload = {
  "transaction_id": 'ipi_1KRmFUFRwUQjTSJEjRnCCPyV',
  "amount": 100,
  "livemode": false,
};

fetch(`https://example.com/do_more_secret_stuff/`, {
  method: 'POST',
  headers: {
    'Stripe-Signature': await fetchStripeSignature(payload),
    'Content-Type': 'application/json',
  },
  // Append the account ID and user ID in the body to verify on backend.
  body: JSON.stringify({
    ...payload,
    user_id: 'usr_K6yd2CbXLO9A5G',
    account_id: 'acct_1JSkf6FRwUQjTSJE',
  }),
});

Beispiel für ein Backend, das die mit zusätzlicher Nutzlast generierte Signatur verifiziert:

// Match the raw body to content type application/json.
app.post('/do_more_secret_stuff', (request, response) => {
  try {
    // Verify the signature from the header and the request body that
    // contains the additional data, user ID, and account ID with the app secret.
    stripe.webhooks.signature.verifyHeader(request.body, sig, appSecret);
  } catch (error) {
    response.status(400).send(error.message);
  }
  // Handle the request by returning a response
  // to acknowledge receipt of the event.
  response.json({ success: true });
});

Nutzerrollen verifizieren (optional)

Sie können die einer bestimmten user_id zugewiesenen Nutzerrollen überprüfen, indem Sie den Schlüssel stripe_roles in die Nutzlast aufnehmen. Geben Sie userContext?.roles an. Dadurch wird eine Liste mit RoleDefinitions zurückgegeben. Wenn eine der Rollen in der Nutzlast keiner user_id zugewiesen ist, gibt fetchStripeSignature einen ungültigen Anfragefehler (400) zurück.

// Provide this special key in the same way you'd
// provide any other key to the additional payload.
const payload = {
  "stripe_roles": userContext?.roles,
};

fetch(`https://example.com/do_more_secret_stuff/`, {
  method: 'POST',
  headers: {
    'Stripe-Signature': await fetchStripeSignature(payload),
    'Content-Type': 'application/json',
  },
  // Append the account ID and user ID in the body to verify on backend.
  body: JSON.stringify({
    ...payload,
    user_id: 'usr_K6yd2CbXLO9A5G',
    account_id: 'acct_1JSkf6FRwUQjTSJE',
  }),
});

Geheimschlüssel ablaufen lassen und erstellen

Wenn Ihr Geheimschlüssel kompromittiert wird, können Sie den Geheimschlüssel Ihrer aktuellen App sofort bis zu 24 Stunden lang ablaufen lassen, um den App-Geheimschlüssel in Ihrem Backend zu aktualisieren. Während dieser Zeit sind zwei Geheimschlüssel für den Endpoint aktiv, der kompromittierte Geheimschlüssel sowie der neu erstellte. Stripe generiert bis zum Ablauf eine Signatur pro Geheimschlüssel.

Einen App-Geheimschlüssel ablaufen lassen und erstellen:

1. Rufen Sie die Detailseite Ihrer Stripe-App auf, indem Sie Ihre App unter Apps auswählen.
2. Klicken Sie in der Kopfzeile der Seite unter der Anwendungs-ID auf das Überlaufmenü () und dann auf Geheimschlüssel für Signatur.
3. Klicken Sie auf Geheimschlüssel ablaufen lassen, um das entsprechende Dialogfeld aufzurufen.
4. Wählen Sie eine Ablaufdauer für Ihren aktuellen App-Geheimschlüssel aus.
5. Klicken Sie auf Geheimschlüssel ablaufen lassen.

Umgang mit Cross-Origin Resource Sharing (CORS)

Cross-Origin Resource Sharing (CORS) ist ein wichtiger Bestandteil, um Apps vor Site-übergreifenden Skriptangriffen (XSS) zu schützen. Da Nutzeroberflächen-Erweiterungen für Stripe-Apps zwangsläufig einen Cross-Ursprung haben und in einer Sandbox ausgeführt werden, müssen Sie ein bestimmtes Verfahren für den Umgang mit Cross-Origin-Anfrage-Headern anwenden.

Damit Ihre Nutzeroberflächen-Erweiterung Daten von Ihrem Backend-Dienst abrufen kann, müssen Sie diesen wie folgt konfigurieren:

• Anfragen mit der Options-Methode zulassen.
• Um Anfragen von null-Ursprüngen zuzulassen, setzen Sie Access-Control-Allow-Origin auf *.

Viele Backend-Frameworks verfügen über Bibliotheken und Anleitungen, die Ihnen beim Umgang mit CORS helfen. Genauere Anleitungen finden Sie in der Dokumentation zu Ihrem Framework.

Informationen dazu, wie Sie authentifizieren, dass eine Anfrage von Stripe im Namen eines/einer bestimmten Nutzers/in oder eines bestimmten Kontos stammt, finden Sie unter Authentifizieren von Nutzer/innen von Ihrer Nutzeroberfläche bei Ihrem Backend.

Für die Interaktion mit Stripe können Sie Ihre Anfragen an die Stripe-API verwenden und authentifizieren.

Authentifizierungsanfragen

Um Ihre Anfragen zu authentifizieren, verwenden Sie Ihren bestehenden Händlerkonto-API-Schlüssel, um mit Stripe zu interagieren, und geben Sie die stripeAccountId des Nutzers/der Nutzerin an.

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:"

Alle serverseitigen Bibliotheken von Stripe unterstützen zudem diese anfragenbasierte Vorgehensweise, wie das folgende Beispiel zeigt:

Stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
Stripe::Customer.create(
  {email: 'person@example.edu'},
  {stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
)

# Fetching an account just needs the ID as a parameter
Stripe::Account.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}')

Selbst gehostetes Backend über Ihre Erweiterung der Nutzeroberfläche aufrufen

Wenn Sie Anfragen von Ihrer Erweiterung der Nutzeroberfläche an Ihr Backend stellen, senden Sie eine Signatur mit Ihrer Anfrage, um die Rechtmäßigkeit der Anfragen zu überprüfen. Übergeben Sie von der Erweiterung der Nutzeroberfläche aus die stripeAccountId für den aktuellen Nutzer/die aktuelle Nutzerin, damit Sie Backend-Anfragen im Namen dieses Nutzers/dieser Nutzerin durchführen können.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(
'sk_test_4eC39HqLyjWDarjtT1zdp7dc');
const express = require("express");
const app = express();

app.use(express.static("public"));
app.use(express.json());

app.post("/api/data", async (req, res) => {
  const { stripeAccountId } = req.body;

  const customer = await stripe.customers.create({
    description: 'My First Test Customer (created for API docs)',
  }, {
    stripeAccount: stripeAccountId,
  });

  res.send({
    data: []
  });
});

app.listen(3000, () => console.log("Node server listening on port 3000!"));

Über Ihr selbst gehostetes Backend können Sie jede API aufrufen – Ihre eigene oder eine von anderen Entwickler/innen oder Unternehmen.

Um mehr zu erfahren, machen Sie sich am besten mit dem Speichern geheimer Anmeldedaten und Token vertraut.

Wenn Sie Nutzerinformationen von Stripe an einen anderen Dienst übergeben müssen, verwenden Sie die von der Erweiterung der Nutzeroberfläche übergebene stripeAccountId.

const express = require('express');
const fetch = require('isomorphic-fetch');
const app = express();

app.use(express.static('public'));
app.use(express.json());

app.get('/api/time', async (req, res) => {
  fetch('http://worldclockapi.com/api/json/est/now')
    .then((response) => response.json())
    .then((data) => {
      res.send({
        data: data,
      });
    });
});

app.listen(3000, () => console.log('Node server listening on port 3000!'));

Sie können auch eine Drittanbieter-API über die Erweiterung Ihrer Nutzeroberfläche aufrufen.

Überwachen Sie Ihre Stripe-App mithilfe eingehender Webhooks auf Ereignisse (z. B. Installationen oder Deinstallationen durch Nutzer/innen), damit Ihre Integration automatisch Reaktionen in Ihrem Backend auslösen kann, wie z. B.:

• Nutzerkonten erstellen
• Berechtigungen aktualisieren
• Konto eines/einer Nutzers/in deaktivieren und Daten entfernen

Ereignisse empfangen

Sie können Ereignisse von Stripe für eine App empfangen, die nur für Ihr Konto bestimmt ist, oder für eine App, die im App-Marktplatz aufgeführt ist:

Wenn ein Händler ein Ereignis auslöst, stellt Stripe das folgende Event-Objekt bereit. Dieses Ereignis enthält die Eigenschaft account, die die Konto-ID des Händlers angibt, der das Ereignis auslöst:

{
  "id": "evt_lKSCF1Kw7pdlaC",
  "livemode": true,
  "object": "event",
  "type": "account.application.authorized",
  "account": "acct_Km4OFRqGGGX1R4",
  "pending_webhooks": 2,
  "created": 1349654313,
  "data": {...}
}

Mit dem Attribut account können Sie Folgendes durchführen:

• Überwachen Sie, wie viele Händler Ihre App installieren und deinstallieren.
• Führen Sie mit Stripe Connect API-Aufrufe im Auftrag von Nutzer/innen durch.

Ereignisse für Stripe-Apps

Zusätzlich zu den Ereignistypen, die Stripe unterstützt, unterstützt Stripe Apps auch die folgenden Ereignisse:

Event behavior depends on install mode

Your users can install in live mode, test mode, or both. Set webhooks according to the following guidelines:

• If the app is installed in live mode only, live mode events are sent to the live mode endpoint.
• If the app is installed in test mode only, test mode events are sent to the test mode endpoint.
• If the app is installed in both modes, test mode events are sent to both the test mode and live mode endpoints, and live mode events are sent to the live mode endpoint.

Configure the Connect /webhook for live and test modes, then use the following snippet for both modes of the app. See the webhooks doc for a full endpoint example.

require 'sinatra'
require 'json'

post '/webhook' do
  event = JSON.parse(request.body.read)

  if event['livemode']
    puts "Handling live event: #{event}"
    # Handle live events
    handle_live_event(event)
  else
    puts "Handling test event: #{event}"
    # Handle test events
    handle_test_event(event)
  end

  status 200
  body 'Event received'
end

Troubleshooting

If you don’t receive expected events, review your configuration for the following common oversights:

• Make sure live mode webhooks use live mode keys and test mode webhooks use test mode keys.
• For live mode events, make sure the installing account is activated.
• Make sure that your app can handle both live mode & test mode events.
• Triggering test events doesn’t replicate live event behavior unless explicitly set up in the app configuration.

Webhooks lokal testen

Sie können Ihre Webhooks lokal auf Folgendes testen:

• Eine App, die nur für Ihre Nutzer/innen verfügbar ist und Ihre Kontoereignisse überwacht
• Eine App, die auf dem Stripe App Marketplace verfügbar ist und Ereignisse auf Konten überwacht, auf denen Ihre App installiert ist

So testen Sie Webhooks lokal:

1. Installieren Sie die Stripe-CLI.

2. Authentifizieren Sie Ihr Konto:

   Command Line

   stripe login

3. Öffnen Sie zwei Terminal-Fenster:

   • In einem Terminal-Fenster können Sie die Ereignisweiterleitung einrichten:

     Nur für Ihr Konto

     Öffentlicher Eintrag im App Marketplace

     Command Line

     stripe listen --forward-to localhost:{{PORT}}/webhook

   • In dem anderen Terminal-Fenster können Sie Ereignisse zum Testen Ihrer Webhooks-Integration auslösen:

     Nur für Ihr Konto

     Öffentlicher Eintrag im App Marketplace

     Command Line

     stripe trigger {{EVENT_NAME}}

Weitere Informationen finden Sie in unserer Dokumentation zum Testen eines Webhook-Endpoints.