Abonnement-Integration erstellen

Das React Native SDK ist Open Source und vollständig dokumentiert. Intern werden native iOS und Android SDKs verwendet. Um das React Native SDK von Stripe zu installieren, führen Sie einen der folgenden Befehle im Verzeichnis Ihres Projekts aus (je nachdem, welchen Paket-Manager Sie verwenden):

yarn add @stripe/stripe-react-native

Installieren Sie als Nächstes einige weitere erforderliche Abhängigkeiten:

• Navigieren Sie für iOS zum Verzeichnis ios und führen Sie pod install aus, um sicherzustellen, dass Sie auch die erforderlichen nativen Abhängigkeiten installieren.
• Für Android müssen keine Abhängigkeiten mehr installiert werden.

Stripe Initialisierung

Um Stripe in Ihrer React Native-App zu initialisieren, umschließen Sie entweder Ihren Zahlungsbildschirm mit der Komponente StripeProvider oder verwenden Sie die Initialisierungsmethode initStripe. Nur der veröffentlichbare API-Schlüssel in publishableKey ist erforderlich. Das folgende Beispiel zeigt, wie Stripe mithilfe der Komponente StripeProvider initialisiert wird.

import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      // Your app code here
    </StripeProvider>
  );
}

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/einen Kundin/Kunden. Erfassen Sie im Frontend Ihrer Anwendung alle von den Nutzerinnen/Nutzern 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.

import React from 'react';
import {View, TextInput, StyleSheet, Button, Platform} from 'react-native';

function RegisterView() {
  const [email, setEmail] = React.useState('');

  const createCustomer = async () => {
    const apiEndpoint =
      Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
    const response = await fetch(`${apiEndpoint}/create-customer`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email: email,
      }),
    });
    if (response.status === 200) {
      const customer = await response.json();
      console.log(customer);
    }
  };

  return (
    <View>
      <TextInput
        style={styles.input}
        placeholder="Email"
        value={email}
        onChangeText={setEmail}
      />
      <Button
        title="Register"
        onPress={async () => {
          await createCustomer();
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  input: {
    height: 40,
    margin: 12,
    borderWidth: 1,
    padding: 10,
  },
});

export default RegisterView;

Erstellen Sie das Stripe Customer-Objekt auf dem Server.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 neuen Kundinnen und Kunden einen Plan auswählen und dann ein Abonnement erstellen. In diesem Leitfaden stehen einen Basic- und ein Premium-Plan zur Auswahl.

Übergeben Sie in Ihrer App die ausgewählte Preis-ID und die ID des Kundendatensatzes an das Backend.

const createSubscription = async (priceId, customerId) => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/create-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      priceId: priceId,
      customerId: customerId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};

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

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_4eC39HqLyjWDarjtT1zdp7dc'

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 payment_intent
  # 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.payment_intent']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.payment_intent.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": {
    "enabled": false
  },
  "billing": "charge_automatically",
  "billing_cycle_anchor": 1623873347,
  "billing_thresholds": null,

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.

The Mobile Payment Element securely collects all necessary payment details for a wide variety of payments methods. You can visit this page to learn what payment methods are supported by both Mobile Payment Element and Subscriptions.

Payment Element zu Ihrer App hinzufügen

Initialisieren und präsentieren Sie das Mobile Payment Element mit der PaymentSheet-Klasse.

import React from 'react';
import {useStripe, PaymentSheetError} from '@stripe/stripe-react-native';
import {View, Button} from 'react-native';

function SubscribeView({clientSecret}) {
  const {initPaymentSheet, presentPaymentSheet} = useStripe();

  React.useEffect(() => {
    const initializePaymentSheet = async () => {
      const {error} = await initPaymentSheet({
        paymentIntentClientSecret: clientSecret,
        returnURL: 'stripe-example://payment-sheet',
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        allowsDelayedPaymentMethods: true,
      });
      if (error) {
        // Handle error
      }
    };

    initializePaymentSheet();
  }, [clientSecret, initPaymentSheet]);

  return (
    <View>
      <Button
        title="Subscribe"
        onPress={async () => {
          const {error} = await presentPaymentSheet();
          if (error) {
            if (error.code === PaymentSheetError.Failed) {
              // Handle failed
            } else if (error.code === PaymentSheetError.Canceled) {
              // Handle canceled
            }
          } else {
            // Payment succeeded
          }
        }}
      />
    </View>
  );
}

export default SubscribeView;

Das Mobile Payment Element stellt ein 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.

Wenn Sie allowsDelayedPaymentMethods auf true festlegen, werden Zahlungsmethoden mit verzögerter Benachrichtigung wie US-Bankkonten zugelassen. Für diese Zahlungsmethoden ist der endgültige Zahlungsstatus nicht bekannt, wenn das PaymentSheet abgeschlossen wird. Stattdessen ist sie erfolgreich oder schlägt fehl. Wenn Sie diese Art von Zahlungsmethoden unterstützen, informieren Sie den Kunden/die Kundin darüber, dass seine/ihre Bestellung bestätigt ist, und führen seine/ihre Bestellung erst aus (z. B. das Produkt versenden), wenn die Zahlung erfolgreich ist.

Sie können das Payment Element an das Design Ihrer App anpassen, indem Sie für Ihr PaymentSheet.Configuration-Objekt die appearance-Eigenschaft verwenden.

Zahlung bestätigen

Das Mobile Payment Element erstellt eine PaymentMethod und bestätigt den ersten PaymentIntent des unvollständigen Abonnements, wodurch eine Zahlung ausgeführt wird. Wenn die Zahlung die starke Kundenauthentifizierung (SCA) erfordert, übernimmt das Payment Element den Authentifizierungsprozess, bevor der PaymentIntent bestätigt wird.

Wenn ein Kunde/eine Kundin Ihre App verlässt, um sich beispielsweise bei Safari oder seiner Banking-App zu authentifizieren, bieten Sie ihm die Möglichkeit, danach automatisch zu Ihrer App zurückzukehren. Viele Arten von Zahlungsmethoden erfordern eine Rückgabe-URL. Wenn Sie diese also nicht angeben, können wir diese Zahlungsmethoden Ihrem Nutzer/Ihrer Nutzerin nicht anbieten, auch dann nicht, wenn Sie sie aktiviert haben.

To provide a return URL:

1. Register a custom URL. Universal links aren’t supported.
2. Configure your custom URL.
3. Set up your root component to forward the URL to the Stripe SDK as shown below.

import React, { useEffect, useCallback } from 'react';
import { Linking } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';

export default function MyApp() {
  const { handleURLCallback } = useStripe();

  const handleDeepLink = useCallback(
    async (url: string | null) => {
      if (url) {
        const stripeHandled = await handleURLCallback(url);
        if (stripeHandled) {
          // This was a Stripe URL - you can return or add extra handling here as you see fit
        } else {
          // This was NOT a Stripe URL – handle as you normally would
        }
      }
    },
    [handleURLCallback]
  );

  useEffect(() => {
    const getUrlAsync = async () => {
      const initialUrl = await Linking.getInitialURL();
      handleDeepLink(initialUrl);
    };

    getUrlAsync();

    const deepLinkListener = Linking.addEventListener(
      'url',
      (event: { url: string }) => {
        handleDeepLink(event.url);
      }
    );

    return () => deepLinkListener.remove();
  }, [handleDeepLink]);

  return (
    <View>
      <AwesomeAppComponent />
    </View>
  );
}

Legen Sie beim Aufrufen der Methode initPaymentSheet außerdem die returnURL fest:

await initPaymentSheet({
  ...
  returnURL: 'your-app://stripe-redirect',
  ...
});

Weitere Informationen zu nativen URL-Schemen finden Sie in der Dokumentation für Android und iOS.

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 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_4eC39HqLyjWDarjtT1zdp7dc'

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 überwachen. Weitere Details zu Abonnement-spezifischen Webhooks finden Sie unter Abonnement-Ereignisse.

Nachdem das Abonnement nun aktiv ist, gewähren Sie Ihren Nutzern und Nutzerinnen Zugriff auf Ihre Dienstleistung. Überwachen 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, das 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 er active ist, hat Ihre Nutzerin/Ihr Nutzer 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.

In diesem Beispiel wird die Abonnement-ID im Frontend erfasst. Im Produktionsbetrieb kann Ihre Anwendung diese Information für Ihre angemeldeten Nutzer/innen aus Ihrer Datenbank abrufen.

Kontoeinstellungen mit der Option, das Abonnement zu kündigen

const cancelSubscription = async subscriptionId => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/cancel-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};

Definieren Sie im Backend den Endpoint für den Aufruf durch Ihre App.

# 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_4eC39HqLyjWDarjtT1zdp7dc'

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

Ihr Backend 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

Set up webhooks to listen to subscription change events like upgrades and cancellations. Read the guide to learn more about subscription webhooks. You can view events in the Dashboard or with the Stripe CLI.

Weitere Informationen finden Sie unter Billing-Integration testen.