Abonnement-Integration erstellen

Installieren Sie den Stripe-Client Ihrer Wahl:

# Available as a gem
sudo gem install stripe

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

Installieren Sie dann die Stripe-CLI. Die CLI bietet Webhook-Tests, die Sie ausführen können, um API-Aufrufe an Stripe zu senden. In diesem Leitfaden wird in einem später folgenden Abschnitt gezeigt, wie Sie mithilfe der CLI ein Preismodell einrichten.

# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

Weitere Installationsoptionen finden Sie unter Mit der Stripe-CLI loslegen.

Erstellen Sie Ihre Produkte und die zugehörigen Preise im Dashboard oder mit der Stripe-CLI.

In diesem Beispiel wird ein Festpreisdienst mit zwei verschiedenen Service-Level-Optionen verwendet: Basic und Premium. Für jede Service-Level-Option müssen Sie ein Produkt und einen wiederkehrenden Preis erstellen. (Wenn Sie eine einmalige Gebühr, z. B. für die Einrichtung, hinzufügen möchten, erstellen Sie ein drittes Produkt mit einem einmaligen Preis. Der Einfachheit halber verzichtet dieses Beispiel auf eine einmalige Gebühr).

In diesem Beispiel wird jedes Produkt in monatlichen Intervallen abgerechnet. Der Preis für das Basic-Produkt beträgt 5 USD. Der Preis für das Premium-Produkt beträgt 15 USD.

Stripe benötigt für jedes Abonnement eine/n Kundin/Kunden. Erfassen Sie in Ihrem Anwendungsfrontend alle erforderlichen Informationen von Ihren Nutzerinnen und Nutzern und leiten Sie diese an das Backend weiter.

Wenn Sie Adressdaten erfassen müssen, können Sie mit dem Adresselement eine Liefer- oder Rechnungsadresse für Ihre Kundinnen und Kunden erfassen. Weitere Informationen zum Adresselement finden Sie auf der Seite Adresselement.

<form id="signup-form">
  <label>
    Email
    <input id="email" type="email" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>

const emailInput = document.querySelector('#email');

fetch('/create-customer', {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: emailInput.value,
  }),
}).then(r => r.json());

Erstellen Sie das Stripe Customer-Objekt auf dem Server.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}} \
  -d "shipping[address][city]"=Brothers \
  -d "shipping[address][country]"=US \
  -d "shipping[address][line1]"="27 Fredrick Ave" \
  -d "shipping[address][postal_code]"=97712 \
  -d "shipping[address][state]"=CA \
  -d "shipping[name]"={{CUSTOMER_NAME}} \
  -d "address[city]"=Brothers \
  -d "address[country]"=US \
  -d "address[line1]"="27 Fredrick Ave" \
  -d "address[postal_code]"=97712 \
  -d "address[state]"=CA

Lassen Sie Ihre/n neue/n Kund/in einen Plan auswählen und dann ein Abonnement erstellen. In diesem Leitfaden wählt die Kundin/der Kunde einen Basic- oder Premium-Plan aus.

Übergeben Sie im Frontend die ausgewählte Preis-ID und die ID des Kundendatensatzes an das Backend.

fetch('/create-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    priceId: priceId,
    customerId: customerId,
  }),
})

Erstellen Sie im Backend mithilfe von payment_behavior=default_incomplete das Abonnement mit dem Status incomplete. Geben Sie dann den client_secret aus dem ersten Payment Intent des Abonnements an das Frontend zurück, um die Zahlung abzuschließen, indem Sie den confirmation_secret auf der letzten Rechnung des Abonnements erweitern.

Um das verbesserte Aboverhalten zu aktivieren, setzen Sie billing_mode[type] auf flexible. Sie müssen die Stripe API Version 2025-06-30.basil oder höher verwenden.

Legen Sie save_default_payment_method auf on_subscription fest, um die Zahlungsmethode bei erfolgreicher Zahlung als Standard für ein Abonnement zu speichern. Das Speichern einer Standardzahlungsmethode erhöht die Erfolgsquote künftiger Abonnementzahlungen.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/create-subscription' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)
  customer_id = cookies[:customer]
  price_id = data['priceId']

  # Create the subscription. Note we're expanding the Subscription's
  # latest invoice and that invoice's confirmation_secret
  # so we can pass it to the front end to confirm the payment
  subscription = Stripe::Subscription.create(
    customer: customer_id,
    items: [{
      price: price_id,
    }],
    payment_behavior: 'default_incomplete',
    payment_settings: {save_default_payment_method: 'on_subscription'},
    billing_mode: {type: 'flexible'},
    expand: ['latest_invoice.confirmation_secret']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret }.to_json
end

An dieser Stelle ist das Abonnement inactive und wartet auf die Zahlung. Nachfolgend finden Sie eine Beispielantwort. Die zum Speichern erforderlichen Felder sind hervorgehoben. Sie sollten jedoch alle Felder speichern, auf die Ihre Anwendung häufig zugreift.

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,
    "enabled": false,
    "liability": "null"
  },
  "billing_cycle_anchor": 1623873347,

Verwenden Sie Stripe Elements für die Erfassung von Zahlungsdetails und zum Aktivieren des Abonnements. Sie können Elements an das Erscheinungsbild Ihrer Anwendung anpassen.

Das Payment Element unterstützt die Zahlungsmethoden Link, Kreditkarten, SEPA-Lastschrift und BECS-Lastschriftverfahren für Abonnements. Es zeigt Ihre aktivierten Zahlungsmethoden an und erfasst die Zahlungsdetails sicher gemäß der Auswahl des Kunden/der Kundin.

Stripe Elements einrichten

Das Payment Element ist automatisch als Funktion von Stripe.js verfügbar. Binden Sie das Stripe.js-Skript auf Ihrer Zahlungsseite ein, indem Sie es in den head Ihrer HTML-Datei einfügen. Laden Sie Stripe.js stets direkt von js.stripe.com, um PCI-konform zu bleiben. Binden Sie das Skript nicht in ein Bundle ein und hosten Sie keine eigene Kopie.

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>
<body>
  <!-- content here -->
</body>

Erstellen Sie eine Instanz von Stripe mit dem folgenden JavaScript-Code auf Ihrer Zahlungsseite:

// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

Payment Element Ihrer Seite hinzufügen

Das Payment Element benötigt einen festen Platz auf Ihrer Zahlungsseite. Erstellen Sie einen leeren DOM-Knoten (Container) mit einer eindeutigen ID in Ihrem Zahlungsformular.

<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Subscribe</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Wenn das obige Formular geladen wurde, erstellen Sie eine Instanz des Payment Element und verbinden diese mit dem Container DOM-Knoten. Im Schritt Abonnement erstellen haben Sie den Wert client_secret an das Frontend übergeben. Übergeben Sie diesen Wert als Option beim Erstellen einer Instanz von Elements.

const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in payment form, passing the client secret obtained in step 5
const elements = stripe.elements(options);

const paymentElementOptions = {
  layout: "tabs",
};

// Create and mount the Payment Element
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Das Payment Element rendert ein dynamisches Formular, mit dem Ihr/e Kund/in eine Zahlungsmethode auswählen kann. Das Formular erfasst automatisch alle notwendigen Zahlungsdetails für die vom Kunden/von der Kundin ausgewählte Zahlungsmethode.

Optionale Konfigurationen für das Payment Element

• Passen Sie das Payment Element an das Design Ihrer Website an, indem Sie beim Erstellen einer Instanz von Elements das Erscheinungsbild-Objekt an options übergeben.
• Konfigurieren Sie die Apple Pay-Nutzeroberfläche so, dass ein Händler-Token zurückgegeben wird, um wiederkehrende und zurückgestellte Zahlungen sowie automatische Aufladungen zu unterstützen.

Zahlung abschließen

Verwenden Sie stripe.confirmPayment, um die Zahlung mit den Details aus dem Payment Element abzuschließen und das Abonnement zu aktivieren. Dadurch wird eine PaymentMethod erstellt und der erste PaymentIntent des unvollständigen Abonnements bestätigt, wodurch eine Gebühr entsteht. Wenn die Zahlung die starke Kundenauthentifizierung (SCA) erfordert, übernimmt das Payment Element den Authentifizierungsprozess, bevor der PaymentIntent bestätigt wird.

Geben Sie eine return_url für diese Funktion an, um anzugeben, wohin Stripe den/die Nutzer/in nach Abschluss der Zahlung weiterleitet. Ihre Nutzer/innen werden möglicherweise zuerst an eine Zwischenseite weitergeleitet, z. B. eine Bankautorisierungsseite, bevor sie zur return_url weitergeleitet werden. Kartenzahlungen werden bei erfolgreicher Zahlung sofort an die return_url weitergeleitet.

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: "https://example.com/order/123/complete",
    }
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

Wenn Ihr Kunde/Ihre Kundin eine Zahlung übermittelt, leitet Stripe ihn an die return_url weiter und fügt die folgenden URL-Abfrageparameter ein. Die Rückgabeseite kann diese nutzen, um den Status des PaymentIntent abzurufen, damit der Kunde/die Kundin den Zahlungsstatus anzeigen kann.

Wenn Sie die return_url angeben, können Sie auch Ihre eigenen Abfrageparameter für die Verwendung auf der Rückgabeseite anhängen.

Wenn Kundinnen und Kunden auf Ihre Seite weitergeleitet werden, können Sie payment_intent_client_secret nutzen, um den PaymentIntent abzufragen und Ihren Kundinnen und Kunden den Transaktionsstatus anzuzeigen.

Verwenden Sie einen der Abfrageparameter, um den PaymentIntent abzurufen. Überprüfen Sie den Status des PaymentIntent, um zu entscheiden, was Ihren Kund/innen angezeigt werden soll. Sie können bei der Angabe der return_url auch Ihre eigenen Abfrageparameter anhängen, die während des Weiterleitungsvorgangs erhalten bleiben.

// Initialize Stripe.js using your publishable key
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` status.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

Um die Integration abzuschließen, müssen Sie die von Stripe gesendeten Webhooks verarbeiten. Diese Ereignisse werden immer dann ausgelöst, wenn sich der Status in Stripe ändert, z.B. wenn für Abonnements neue Rechnungen erstellt werden. Richten Sie in Ihrer Anwendung einen HTTP-Handler ein, der eine POST-Anfrage akzeptiert, die das Webhook-Ereignis enthält, und überprüfen Sie die Signatur des Ereignisses:

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/webhook' do
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events check out https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

Verwenden Sie während der Entwicklung die Stripe-CLI, um Webhooks zu beobachten und an Ihre Anwendung weiterzuleiten. Führen Sie Folgendes in einem neuen Datenterminal aus, während Ihre Entwicklungs-App ausgeführt wird:

stripe listen --forward-to localhost:4242/webhook

Für die Produktionsphase können Sie einen Webhook-Endpoint in Workbench oder mit der Webhook Endpoints API einrichten.

Sie müssen auf einige Ereignisse achten, um die verbleibenden Schritte in diesem Leitfaden abzuschließen. Weitere Informationen zu abonnementbezogenen Webhooks finden Sie unter Abonnement-Ereignisse.

Nachdem das Abonnement nun aktiv ist, gewähren Sie Ihren Nutzer/innen Zugriff auf Ihre Dienstleistung. Beobachten Sie dazu die Ereignisse customer.subscription.created, customer.subscription.updated und customer.subscription.deleted. Diese Ereignisse übergeben ein Abonnementobjekt, das ein status-Feld enthält, welches anzeigt, ob das Abonnement aktiv oder überfällig ist oder gekündigt wurde. Eine vollständige Statusliste finden Sie unter Abonnementlebenszyklus.

In Ihrem Webhook-Handler:

1. Überprüfen Sie den Abonnementstatus. Wenn es active ist, hat Ihr/e Nutzer/in für Ihr Produkt bezahlt.
2. Prüfen Sie das Produkt, auf das die Kundin/der Kunde ein Abo abgeschlossen hat und gewähren Sie Zugang zu Ihrem Dienst. Das Überprüfen des Produkts anstelle des Preises gibt Ihnen mehr Flexibilität, falls Sie die Preisgestaltung oder den Rechnungsstellungszeitraum ändern müssen.
3. Speichern Sie die product.id, subscription.id und den subscription.status in Ihrer Datenbank zusammen mit der bereits gespeicherten customer.id. Überprüfen Sie diesen Datensatz, wenn Sie entscheiden, welche Funktionen für die Nutzer/innen Ihrer Anwendung aktiviert werden sollen.

The status of a subscription might change at any point during its lifetime, even if your application doesn’t directly make any calls to Stripe. For example, a renewal might fail due to an expired credit card, which puts the subscription into a past due status. Or, if you implement the customer portal, a user might cancel their subscription without directly visiting your application. Implementing your handler correctly keeps your application status in sync with Stripe.

Es ist gängige Praxis, dass Kundinnen/Kunden ihr Abonnement selbst kündigen können. In diesem Beispiel wird zur Seite mit den Kontoeinstellungen eine Kündigungsoption hinzugefügt.

Kontoeinstellungen mit der Option, das Abonnement zu kündigen

function cancelSubscription(subscriptionId) {
  return fetch('/cancel-subscription', {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(cancelSubscriptionResponse => {
      // Display to the user that the subscription has been canceled.
    });
}

Definieren Sie im Backend den Endpoint für den Aufruf durch Ihr Frontend.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

Ihre Anwendung erhält ein Ereignis vom Typ customer.subscription.deleted.

Aktualisieren Sie nach der Kündigung des Abonnements Ihre Datenbank, um die zuvor gespeicherte Stripe-Abonnement-ID zu entfernen, und schränken Sie den Zugang zu Ihrer Dienstleistung ein.

Wenn ein Abonnement gekündigt wurde, kann es nicht reaktiviert werden. Sie müssen stattdessen die aktualisierten Rechnungsinformationen von Ihrer Kundinnen/Kunden erfassen, deren Standard-Zahlungsmethode aktualisieren und ein neues Abonnement für den bestehenden Kundendatensatz erstellen.

Zahlungsmethoden testen

Verwenden Sie die folgende Tabelle, um verschiedene Zahlungsmethoden und -szenarien zu testen.

Ereignisse überwachen

Richten Sie Webhooks ein, um Abonnementänderungsereignisse wie Upgrades und Kündigungen zu überwachen. Erfahren Sie mehr über Abonnement-Webhooks. Sie können Ereignisse im Dashboard oder mit der Stripe-CLI anzeigen.

Weitere Informationen finden Sie unter Billing-Integration testen.