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. Mit der Stripe-CLI können Sie Webhooks testen und Stripe-APIs aufrufen. In einem späteren Abschnitt dieses Leitfadens wird erklärt, wie Sie mithilfe der CLI ein Preismodell einrichten können.

# 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

Erlauben Sie Ihren Kund/innen, einen Tarif auszuwählen und dann das Abo zu erstellen. Im Beispiel in diesem Leitfaden wählt der Kunde zwischen einem Basis-Tarif oder einem Aufpreis-Tarif.

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

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

Erstellen Sie im Backend das Abo mit einem unvollständigen Status mit payment_behavior=default_incomplete. Geben Sie dann das client_secret vom ersten PaymentIntent des Abos an das Frontend zurück, um die Zahlung abzuschließen. Erweitern Sie dazu das confirmation_secret auf der neuesten Rechnung des Abos.

Um ein verbessertes Aboverhalten zu ermöglichen, legen Sie billing_mode[type] auf flexible fest. 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 Abo zu speichern. Das Speichern einer Standardzahlungsmethode erhöht die Erfolgsquote künftiger Abo-Zahlungen.

# 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

Das Abo ist jetzt inaktiv und wartet auf Zahlung. In der folgenden Beispielantwort werden die minimal zu speichernden Felder hervorgehoben. Sie können jedoch die 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, um Zahlungsdetails zu erfassen und das Abo zu aktivieren. Sie können Elements an das Erscheinungsbild Ihrer Anwendung anpassen.

Das Payment Element unterstützt Link, Kreditkarten, SEPA-Lastschrift und BECS-Lastschriftverfahren für Abos. Sie können die aktivierten Zahlungsmethoden anzeigen und die auf der Kundenauswahl basierenden Zahlungsdetails sicher erfassen.

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/clover/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 zu 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>

Nachdem das Formular geladen wurde, erstellen Sie eine Instanz des Payment Element und verbinden es mit dem Container-DOM-Knoten. Beim Erstellen des Abos 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 the 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 stellt ein dynamisches Formular dar, mit dem Ihre Kundinnen und Kunden eine Zahlungsmethode auswählen können. Das Formular erfasst automatisch alle notwendigen Zahlungsdetails für die ausgewählte Zahlungsmethode.

Optionale Konfigurationen für das Payment Element

Optional können Sie Folgendes tun:

• Sie können das Payment Element an das Design Ihrer Website anpassen, indem Sie beim Erstellen einer Instanz von Elements das Appearance-Objekt an options übergeben.
• Konfigurieren Sie die Apple Pay-Schnittstelle so, dass ein Händler-Token zurückgegeben wird, um wiederkehrende Zahlungen, automatisches Neuladen und verzögerte Zahlungen zu unterstützen.

Zahlung abschließen

Verwenden Sie stripe.confirmPayment, um die Zahlung mit den Details aus dem Payment Element abzuschließen und das Abo zu aktivieren. Dadurch wird eine PaymentMethod erstellt und der erste PaymentIntent des unvollständigen Abos bestätigt, wodurch eine Abbuchung 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 an, um anzugeben, wohin Stripe die Nutzer/innen nach Durchführung der Zahlung weiterleitet. Ihre Nutzer/innen werden möglicherweise an eine zwischengeschaltete Seite weitergeleitet, wie z. B. eine Bankautorisierungsseite, bevor sie zur return_url weitergeleitet werden. Bei Kartenzahlungen werden sie sofort zur return_url weitergeleitet, wenn die Zahlung erfolgreich war.

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 is reached only if there's an immediate error when
    // confirming the payment. Show an error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer redirects to your `return_url`. For some payment
    // methods, such as iDEAL, your customer redirects to an intermediate
    // site first to authorize the payment, and then redirects 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 [immediately succeed or fail][0] upon
  // confirmation, while others 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 Abos neue Rechnungen erzeugt werden. Richten Sie in Ihrer Anwendung einen HTTP-Handler ein, der eine POST-Anfrage akzeptiert, die das Webhook-Ereignis enthält, und die Signatur des Ereignisses überprüft:

# 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, see 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 überwachen 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 einrichten oder die Webhook Endpoints API verwenden.

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

Nachdem das Abo nun aktiv ist, gewähren Sie Ihren Nutzer/innen Zugriff auf Ihren Dienst. Überwachen Sie dazu die Ereignisse customer.subscription.created, customer.subscription.updated und customer.subscription.deleted. Diese Ereignisse übergeben ein Abo-Objekt, das ein Status-Feld enthält, das anzeigt, ob das Abo aktiv oder überfällig ist oder gekündigt wurde. Eine vollständige Statusliste finden Sie unter Abo-Lebenszyklus.

In Ihrem Webhook-Handler:

1. Überprüfen Sie den Status des Abos. Wenn er aktiv ist, hat der/die Nutzer/in für Ihr Produkt bezahlt.
2. Prüfen Sie das Produkt, für 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 product.id, subscription.id und 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.

Der Status eines Abos kann sich während seiner Laufzeit jederzeit ändern, auch wenn Ihre Anwendung keine direkten Aufrufe an Stripe tätigt. So kann beispielsweise eine Verlängerung aufgrund einer abgelaufenen Karte fehlschlagen, wodurch das Abo in einen überfälligen Status versetzt wird. Oder, wenn Sie das Kundenportal implementieren, könnte ein/e Nutzer/in das Abo kündigen, ohne Ihre Anwendung direkt aufzurufen. Durch die korrekte Implementierung Ihres Handlers bleibt der Status Ihrer Anwendung mit Stripe synchronisiert.

Sie können Kund/innen die Möglichkeit bieten, ihre Abos zu kündigen. Im folgenden Beispiel wird eine Kündigungsoption zur Seite mit den Kontoeinstellungen hinzugefügt.

Kontoeinstellungen mit der Option, das Abo 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, den Ihr Frontend aufrufen soll.

# 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 empfängt 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 Abo 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 Abo 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 Abo-Änderungsereignisse wie Upgrades und Kündigungen zu überwachen. Erfahren Sie mehr über Abo-Webhooks. Sie können Ereignisse im Dashboard oder mit der Stripe CLI anzeigen.

Weitere Informationen finden Sie unter Billing-Integration testen.