Permettre aux entreprises qui utilisent votre plateforme d’accepter directement des paiements

Pour commencer, vous devez créer un compte Stripe.

Côté serveur

Cette intégration exige des endpoints sur votre serveur qui communiquent avec l’API Stripe. Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre serveur :

# Available as a gem
sudo gem install stripe

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

Côté client

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 { useState, useEffect } from 'react';
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>
  );
}

Lorsqu’un utilisateur (marchand ou fournisseur de services) s’inscrit sur votre plateforme, créez un compte d’utilisateur (appelé compte connecté) afin de pouvoir accepter des paiements de sa part et transférer des fonds vers son compte bancaire. Les comptes connectés représentent vos utilisateurs dans l’API de Stripe et permettent de collecter facilement les informations nécessaires pour vérifier leur identité. Dans notre exemple de création de boutique, le compte connecté représente l’entreprise qui configure sa boutique en ligne.

Étape 2.1 : créer un compte connecté et préremplir les informations Server-side

Utilisez l’API /v1/accounts pour créer un compte connecté. Vous pouvez le créer en utilisant les paramètres par défaut du compte connecté ou en spécifiant le type de compte.

curl -X POST https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Si vous avez déjà collecté des informations pour vos comptes connectés, vous pouvez préremplir ces informations dans l’objet Account. Vous pouvez préremplir n’importe quelle information de compte, y compris des informations personnelles et professionnelles, des informations de compte externe, etc.

Connect Onboarding ne demande pas les informations préremplies. Cependant, il demande au titulaire du compte de confirmer les informations préremplies avant d’accepter le contrat d’utilisation du service Connect.

Lorsque vous testez votre intégration, préremplissez les informations du compte à l’aide des données de test.

Étape 2.2 : Créer un lien de compte Côté serveur

Vous pouvez créer un lien de compte en appelant l’API Account Links avec les paramètres suivants :

• account
• refresh_url
• return_url
• type = account_onboarding

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding

Étape 2.3 : Rediriger votre utilisateur vers l’URL du lien de compte Côté client

La réponse à votre requête Account Links contient une valeur pour la clé url. Les liens de compte sont temporaires et à usage unique, car ils donnent accès aux informations personnelles du titulaire du compte connecté. Si vous souhaitez pré-remplir des informations, vous devez le faire avant de générer le lien de compte. Une fois le lien créé pour un compte Standard, les opérations de lecture comme d’écriture ne seront plus possibles pour ce compte. Envoyez cette URL à votre application et ouvrez-la dans le navigateur pour que l’utilisateur puisse achever le flux Connect Onboarding.

Étape 2.4 : Gérer le retour de l’utilisateur sur votre plateforme Côté client

Connect Onboarding vous demande de transmettre à la fois une return_url et une refresh_url pour gérer tous les cas de redirection de l’utilisateur vers votre plateforme. Il est important que vous implémentiez correctement ces URL afin de délivrer la meilleure expérience à vos utilisateurs. Vous pouvez configurer un lien profond pour permettre à la page Web Stripe de rediriger automatiquement vers votre application.

return_url

Stripe déclenche une redirection vers cette URL une fois que l’utilisateur a terminé son inscription Connect Onboarding. Ceci ne veut pas dire que toutes les informations ont été recueillies ni qu’il ne reste pas des conditions à remplir pour le compte, mais simplement que l’entrée de votre client dans le flux et sa sortie se sont déroulées correctement.

Aucun état n’est transmis par cette URL. Une fois que l’utilisateur est redirigé vers votre return_url, vérifiez l’état du paramètre details_submitted sur son compte de l’une des manières suivantes :

• Écoutez les webhooks account.updated.
• Appeler l’API Accounts et inspecter l’objet renvoyé

refresh_url

Votre utilisateur est redirigé vers l’URL refresh_url dans les cas suivants :

• Le lien a expiré (quelques minutes se sont écoulées depuis la création du lien)
• L’utilisateur a déjà fait usage du lien (il a actualisé la page ou cliqué sur le bouton Précédent ou Suivant de son navigateur)
• Votre plateforme n’est plus en mesure d’accéder au compte
• Le compte a été rejeté

Pour une expérience optimale, votre URL refresh_url doit déclencher une méthode permettant à votre serveur d’appeler à nouveau Account Links avec les mêmes paramètres, et de rediriger l’utilisateur vers le flux Connect Onboarding.

Étape 2.5 : Gérer les utilisateurs dont l’inscription n’est pas terminée

Un utilisateur qui est redirigé vers votre return_url peut ne pas avoir terminé son inscription. Utilisez l’endpoint /v1/accounts pour récupérer ses données de compte et vérifier le paramètre charges_enabled. Si l’inscription du compte n’a pas été finalisée, affichez des invites pour encourager l’utilisateur à poursuivre son inscription. Il pourra achever l’activation de son compte grâce à un nouveau lien de compte (généré par votre intégration). Vous pourrez vérifier l’état du paramètre details_submitted sur son compte pour voir s’il a complété son inscription.

Accédez aux paramètres des moyens de paiement et activez ceux que vous souhaitez prendre en charge. Les paiements par carte bancaire sont activés par défaut, mais vous pouvez activer et désactiver les moyens de paiement de votre choix en fonction de vos besoins.

Cette intégration utilise trois objets de l’API Stripe :

1. PaymentIntent : pour représenter votre intention d’encaisser le paiement d’un client, Stripe utilise un objet PaymentIntent qui suit vos tentatives de débit et les changements d’état du paiement tout au long du processus.

2. (Facultatif) Customer : pour configurer un moyen de paiement en vue de paiements futurs, vous devez l’associer à un objet Customer. Créez un objet Customer lorsque votre client ouvre un compte chez vous. Si votre client effectue un paiement en tant qu’invité, vous pouvez créer un objet Customer avant le paiement, puis l’associer ultérieurement à votre représentation interne du compte client.

3. (Facultatif) Customer Ephemeral Key : l’objet Customer contient des informations sensibles qu’il n’est pas possible de récupérer directement depuis une application. Une clé éphémère permet d’accorder au SDK un accès temporaire à l’objet Customer.

Pour des raisons de sécurité, votre application ne peut pas créer ces objets. À la place, ajoutez sur votre serveur un endpoint qui :

1. Récupère l’objet Customer ou en crée un nouveau.
2. Crée une clé éphémère pour le client.
3. Crée un PaymentIntent comportant les paramètres amount, currency, customer. Vous pouvez également inclure le paramètre automatic_payment_methods (facultatif). Stripe l’active par défaut dans la dernière version de l’API.
4. Renvoie la clé secrète du client du Payment Intent, le secret de la clé éphémère, l’id du client et votre clé publiable à votre application.

Les moyens de paiement présentés à votre client lors du processus de paiement sont également inclus dans le PaymentIntent. Vous pouvez laisser Stripe extraire (depuis les paramètres de votre Dashboard) les moyens de paiement à présenter, ou les répertorier manuellement. Quelle que soit l’option que vous choisissez, sachez que la devise transmise dans le PaymentIntent filtre les moyens de paiement présentés au client. Par exemple, si vous transmettez eur dans le PaymentIntent et que vous avez activé OXXO dans votre Dashboard, votre client ne verra pas ce moyen de paiement étant donné qu’OXXO ne prend pas en charge les paiements en eur.

À moins que votre intégration ne nécessite du code pour la présentation des moyens de paiement, Stripe vous recommande l’option automatisée. En effet, Stripe évalue la devise, les restrictions en matière de moyens de paiement ainsi que d’autres paramètres pour dresser la liste des moyens de paiement pris en charge. Ceux qui augmentent le taux de conversion et qui sont les plus pertinents pour la devise et le lieu de résidence du client sont priorisés.

# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-06-30.basil" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \

Avant d’afficher le composant Element Payment pour mobile, vous devez, sur votre écran de paiement :

• Présenter les produits commandés et le montant total des achats
• Collecter les éventuelles informations de livraison requises
• Inclure un bouton de règlement pour afficher l’interface utilisateur de Stripe

Au cours du processus de paiement de votre application, effectuez une demande réseau auprès du endpoint du back-end que vous avez créé à l’étape précédente, puis appelez initPaymentSheet depuis le hook useStripe.

export default function CheckoutScreen() {
  const { initPaymentSheet, presentPaymentSheet } = useStripe();
  const [loading, setLoading] = useState(false);

  const fetchPaymentSheetParams = async () => {
    const response = await fetch(`${API_URL}/payment-sheet`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    const { paymentIntent, ephemeralKey, customer } = await response.json();

    return {
      paymentIntent,
      ephemeralKey,
      customer,
    };
  };

  const initializePaymentSheet = async () => {
    const {
      paymentIntent,
      ephemeralKey,
      customer,
    } = await fetchPaymentSheetParams();

    const { error } = await initPaymentSheet({
      merchantDisplayName: "Example, Inc.",
      customerId: customer,
      customerEphemeralKeySecret: ephemeralKey,
      paymentIntentClientSecret: paymentIntent,
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment
      //methods that complete payment after a delay, like SEPA Debit and Sofort.
      allowsDelayedPaymentMethods: true,
      defaultBillingDetails: {
        name: 'Jane Doe',
      }
    });
    if (!error) {
      setLoading(true);
    }
  };

  const openPaymentSheet = async () => {
    // see below
  };

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

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Lorsque votre client touche le bouton Paiement, appelez presentPaymentSheet() pour ouvrir le formulaire de paiement. Une fois la transaction finalisée, le formulaire se ferme et la promesse aboutit avec le résultat facultatif StripeError<PaymentSheetError>.

export default function CheckoutScreen() {
  // continued from above

  const openPaymentSheet = async () => {
    const { error } = await presentPaymentSheet();

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else {
      Alert.alert('Success', 'Your order is confirmed!');
    }
  };

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

En l’absence d’erreur, informez l’utilisateur que l’opération est terminée (par exemple, en affichant un écran de confirmation de commande).

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.

Le client peut quitter votre application pour s’authentifier (par exemple, dans Safari ou dans son application bancaire). Pour lui permettre de revenir automatiquement sur votre application après s’être authentifié, configurez un schéma d’URL personnalisé et configurez votre délégué d’application pour qu’il transmette l’URL au SDK. Stripe ne prend pas en charge les liens universels.

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

Définissez également le paramètre returnURL correspondant à votre objet PaymentSheet.Configuration sur l’URL de votre application.

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

Stripe envoie un événement payment_intent.succeeded à l’issue du paiement. Utilisez l’outil de webhook du Dashboard ou suivez le guide consacré aux webhooks pour recevoir ces événements et exécuter des actions, comme envoyer une confirmation de commande par e-mail à votre client, enregistrer la vente dans une base de données ou lancer un flux de livraison.

Plutôt que d’attendre un rappel de votre client, écoutez ces événements. Côté client, il arrive en effet que l’utilisateur ferme la fenêtre de son navigateur ou quitte l’application avant l’exécution du rappel. Certains clients malintentionnés peuvent d’autre part tenter de manipuler la réponse. En configurant votre intégration de manière à ce qu’elle écoute les événements asynchrones, vous pourrez accepter plusieurs types de moyens de paiement avec une seule et même intégration.

En plus de l’événement payment_intent.succeeded, nous vous recommandons de gérer ces autres événements lorsque vous encaissez des paiements à l’aide de l’Element Payment :

Consultez la section consacrée aux tests pour obtenir des informations supplémentaires sur la manière de tester votre intégration.