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 aufrufen. In einem späteren Abschnitt dieses Leitfadens 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 Kund/in. Erfassen Sie im Frontend Ihrer Anwendung alle von den Nutzer/innen benötigten Informationen und übergeben Sie diese ans Backend.

Wenn Sie Adressdaten erfassen müssen, können Sie mit dem Address Element Versand- und Rechnungsadressen Ihrer Kundinnen/Kunden erfassen. Weitere Informationen zu dem Thema finden Sie auf der Seite Address Element.

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

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'},
    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 erfasst alle erforderlichen Zahlungsdaten für verschiedenste Zahlungsmethoden auf sichere Weise. Die Zahlungsmethoden, die derzeit sowohl vom Payment Element als auch von den Abonnements unterstützt werden, sind Kreditkarten, Link, SEPA-Lastschrift und BECS-Lastschrift.

Stripe Elements einrichten

Das Payment Element ist ein Feature von Stripe.js und steht damit automatisch zur Verfügung. Fügen Sie das Stripe.js-Skript auf Ihrer Bezahlseite ein, indem Sie es in den head Ihrer HTML-Datei einbinden. Laden Sie Stripe.js immer direkt von js.stripe.com, um die PCI-Konformität zu gewährleisten. Fügen Sie das Skript nicht in ein Paket ein und hosten Sie selbst keine Kopie davon.

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

Erstellen Sie auf Ihrer Bezahlseite eine Instanz von Stripe mit dem folgenden JavaScript:

// 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 checkout 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` state.
  //
  // [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 Ihre Integration abzuschließen, müssen Sie von Stripe gesendete Webhooks verarbeiten. Dies sind Ereignisse, die ausgelöst werden, wenn sich ein Status innerhalb von Stripe ändert, z. B. wenn Abonnements neue Rechnungen erstellen. Richten Sie in Ihrer Anwendung einen HTTP-Handler ein, um eine POST-Anfrage mit dem Webhook-Ereignis zu akzeptieren und verifizieren Sie die Unterschrift 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 eine Webhook-Endpoint-URL über das Dashboard oder mit der Webhook Endpoints API einrichten.

Um die verbleibenden Schritte dieses Leitfadens abzuschließen, müssen Sie einige Ereignisse beobachten. Weitere Details zu Abonnement-spezifischen 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. Überprüfen Sie das Produkt, das die Kundin/der Kunde abonniert hat, und gewähren Sie Zugang zu Ihrer Dienstleistung. Bei der Überprüfung des Produkts sind Sie im Vergleich zur Überprüfung des Preises flexibler, falls Sie den Preis oder das Abrechnungsintervall ä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.

Der Status eines Abonnements kann sich während seiner Laufzeit jederzeit ändern, auch wenn Ihre Anwendung Stripe nicht direkt aufruft. Beispielsweise kann eine Verlängerung aufgrund einer abgelaufenen Kreditkarte fehlschlagen, wodurch das Abonnement in einen überfälligen Status versetzt wird. Oder wenn Sie das Kundenportal implementieren, können Nutzer/innen ihr Abonnement kündigen, ohne Ihre Anwendung direkt aufzurufen. Durch die korrekte Implementierung Ihres Handlers wird der Anwendungsstatus mit Stripe synchronisiert.

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.