Créer une intégration pour les abonnements

Le SDK React Native est disponible en open source et fait l’objet d’une documentation complète. En interne, il utilise des SDK Android et iOS natifs. Pour installer le SDK React Native de Stripe, exécutez l’une des commandes suivantes dans le répertoire de votre projet (selon le gestionnaire de paquets que vous utilisez) :

yarn add @stripe/stripe-react-native

Ensuite, installez les autres dépendances nécessaires :

• Pour iOS, accédez au répertoire ** ios** et exécutez pod install pour vous assurer d’installer également les dépendances natives requises.
• Pour Android, il n’y a plus de dépendances à installer.

Initialisation de Stripe

Pour initialiser Stripe dans votre application React Native, wrappez votre écran de paiement avec le composant StripeProvider ou utilisez la méthode d’initialisation initStripe. Seule la clé publiable de l’API dans publishableKey est nécessaire. L’exemple suivant montre comment initialiser Stripe à l’aide du composant StripeProvider.

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>
  );
}

Installez ensuite l’interface de ligne de commande Stripe. Cette dernière vous permet d’exécuter les tests webhook dont vous avez besoin, et d’exécuter des appels à l’API vers Stripe. Ce guide vous explique dans une section ultérieure comment utiliser l’interface de ligne de commande pour définir un modèle tarifaire.

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

# Connect the CLI to your dashboard
stripe login

Pour davantage d’options d’installation, consultez la page consacrée à l’interface de ligne de commande Stripe.

Créez vos produits et leurs tarifs dans le Dashboard ou via l’interface de ligne de commande Stripe.

Cet exemple utilise un service à tarif fixe avec deux options de niveau de service différentes : Basic et Premium. Pour chaque option de niveau de service, vous devez créer un produit et un tarif récurrent. (Si vous souhaitez ajouter un paiement ponctuel, par exemple des frais d’installation, créez un troisième produit avec un tarif unique. Par souci de simplicité, cet exemple n’inclut pas de paiement ponctuels.)

Dans cet exemple, chaque produit est facturé mensuellement. Le tarif du produit de base est de 5 USD. Celui du produit premium est de 15 USD.

Stripe a besoin d’un objet Customer pour chaque abonnement. Sur le front-end de votre application, collectez toutes les informations nécessaires sur vos utilisateurs et transmettez-les à votre back-end.

Si vous avez besoin de recueillir une adresse, le composant Address Element vous permet de recueillir l’adresse de livraison ou de facturation de vos clients. Pour plus d’informations sur ce composant, consultez la page consacrée à 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;

Sur le serveur, créez l’objet Customer Stripe.

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

Laissez votre nouveau client choisir une offre, puis créez l’abonnement. Dans ce guide, le client a le choix entre l’option de base et l’option Premium.

Dans votre application, transmettez l’ID du tarif sélectionné et l’ID du dossier client à votre back-end.

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;
  }
};

Sur votre back-end, créez l’abonnement à l’état incomplete à l’aide de payment_behavior=default_incomplete. Renvoyez ensuite le client_secret du premier PaymentIntent de l’abonnement vers votre front-end pour finaliser le paiement.

Définissez save_default_payment_method sur on_subscription afin d’enregistrer un moyen de paiement comme moyen de paiement par défaut pour l’abonnement lorsque le paiement aboutit. L’enregistrement d’un moyen de paiement par défaut augmente le taux de réussite des paiements futurs.

# 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

À ce stade, l’abonnement est inactive et en attente de paiement. Voici un exemple de réponse. Les champs à sauvegarder impérativement sont en surbrillance, mais vous devez également sauvegarder tous les éléments auxquels votre application accède fréquemment.

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false
  },
  "billing": "charge_automatically",
  "billing_cycle_anchor": 1623873347,
  "billing_thresholds": null,

Utilisez Stripe Elements pour collecter les données de paiement du client et activer son abonnement. Vous pouvez personnaliser Elements aux couleurs de votre application.

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.

Ajouter le composant Payment Element à votre application

Initialiser et présenter le composant Mobile Payment Element à l’aide de la classe PaymentSheet.

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;

Le composant Mobile Payment Element affiche un formulaire qui permet à votre client de sélectionner un moyen de paiement. Le formulaire collecte automatiquement toutes les informations de paiement requises pour le moyen de paiement sélectionné.

Si vous définissez allowsDelayedPaymentMethods sur true, les moyens de paiement à notification différée, comme les comptes bancaires étasuniens, seront acceptés. Pour ces moyens de paiement, l’état final du paiement n’est pas connu une fois le processus du PaymentSheet achevé, et le paiement peut plus tard aboutir comme échouer. Si vous prenez en charge ces types de moyens de paiement, informez votre client que sa commande est confirmée et ne la traitez (en lui expédiant son produit, par exemple) qu’une fois le paiement reçu.

Vous pouvez personnaliser le composant Payment Element afin qu’il corresponde au design de votre application en utilisant la propriété appearance de votre objet PaymentSheet.Configuration.

Confirmer le paiement

Le composant Mobile Payment Element crée un PaymentMethod et le premier PaymentIntent de l’abonnement incomplet est confirmé, ce qui déclenche le processus de paiement. Si une authentication forte du client (SCA) est requise pour le paiement, le composant Payment Element gère le processus d’authentification avant de confirmer le PaymentIntent.

Lorsqu’un client quitte votre application, par exemple pour s’identifier sur Safari ou dans son application bancaire, faites en sorte qu’il puisse revenir automatiquement à votre application par la suite. De nombreux types de moyens de paiement imposent une URL de redirection. Si vous ne la fournissez pas, ces moyens de paiement ne seront pas présentés à votre utilisateur, même si vous les avez activés.

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>
  );
}

Définissez aussi la returnURL lorsque vous appelez la méthode initPaymentSheet :

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

Pour plus d’informations sur les schémas d’URL natifs, consultez la documentation Android et iOS.

Afin de compléter votre intégration, vous devez traiter les webhooks envoyés par Stripe. Les webhooks sont des événements qui se déclenchent lorsqu’un état change dans Stripe, par exemple lorsque des abonnements créent de nouvelles factures. Dans votre application, configurez un gestionnaire HTTP de sorte qu’il accepte les requêtes POST contenant l’événement de webhook, et vérifiez la signature de l’événement :

# 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?

Pendant le développement, utilisez l’interface de ligne de commande de Stripe pour observer les webhooks et les transférer vers votre application. Exécutez la commande suivante dans un nouveau terminal pendant que votre application de développement est en cours d’exécution :

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

Pour le mode production, définissez une URL d’endpoint de webhook dans le Dashboard, ou utilisez l’API Webhook Endpoints.

Les étapes restantes de ce guide vont vous amener à écouter quelques événements. Pour plus d’informations sur les webhooks spécifiques aux abonnements, consultez notre documentation consacrée aux événements Subscription.

Maintenant que l’abonnement est actif, fournissez à votre client l’accès à votre service. Pour ce faire, écoutez les événements customer.subscription.created, customer.subscription.updated et customer.subscription.deleted. Ces événements transmettent un objet Subscription, dans lequel un champ status indique si l’abonnement est actif, en retard de paiement ou annulé. Consultez la documentation consacrée au cycle de vie des abonnements pour prendre connaissance de la liste complète des états.

Dans votre gestionnaire de webhooks :

1. Vérifiez l’état de l’abonnement. S’il est active, cela signifie que votre client a payé son abonnement.
2. Vérifiez le produit auquel le client s’est abonné et fournissez l’accès à votre service. Le fait de vérifier le produit plutôt que le tarif vous assure une plus grande souplesse si vous devez modifier la tarification ou la fréquence de facturation.
3. Sauvegardez les product.id, subscription.id et subscription.status dans votre base de données avec le customer.id déjà stocké. Vérifiez ce dossier au moment de décider des fonctionnalités à activer pour l’utilisateur dans votre application.

L’état d’un abonnement peut changer à tout moment de son cycle de vie, même si votre application n’appelle pas directement Stripe. Par exemple, un renouvellement peut échouer en raison d’une carte expirée, ce qui fait passer l’abonnement à l’état « past due ». Ou, si vous implémentez le portail client, un utilisateur peut choisir d’annuler son abonnement sans accéder directement à votre application. L’implémentation correcte de votre gestionnaire permet de synchroniser l’état de votre application avec celui de Stripe.

Il est courant de laisser aux clients la possibilité d’annuler leur abonnement. Cet exemple vous explique comment ajouter une option d’annulation sur la page des paramètres du compte.

Dans cet exemple, l’ID de l’abonnement est collecté sur votre front-end, mais votre application peut obtenir cette information depuis votre base de données pour votre utilisateur connecté.

Paramètres d’un compte ayant la possibilité d’annuler son abonnement

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;
  }
};

Sur votre back-end, définissez l’endpoint que votre application appellera.

# 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

Votre back-end reçoit un événement customer.subscription.deleted.

Après l’annulation de l’abonnement, mettez à jour votre base de données pour supprimer l’ID de l’abonnement Stripe précédemment sauvegardé, et limitez l’accès à votre service.

Une fois un abonnement annulé, il ne peut plus être réactivé. Collectez dès lors les informations de facturation actualisées de votre client, mettez à jour son moyen de paiement par défaut et créez un nouvel abonnement à partir du dossier client existant.

Tester les moyens de paiement

Utilisez le tableau suivant pour tester différents scénarios et moyens de paiement.

Écouter des événements

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.

Pour en savoir plus, consultez la page Tester votre intégration Billing.