# Configurer votre intégration Configurez un SDK Stripe Terminal ou une intégration pilotée par serveur pour accepter les paiements par TPE. # React Native > La bibliothèque React Native de Terminal est disponible en [version bêta publique](https://docs.stripe.com/release-phases.md) et en développement actif. Veuillez signaler tout problème rencontré sur notre [projet GitHub](https://github.com/stripe/stripe-terminal-react-native/issues/new/choose). Pour démarrer avec le SDK React Native, suivez ces quatre étapes : 1. [Installer le SDK](https://docs.stripe.com/terminal/payments/setup-integration.md#install) dans votre application. 2. [Configurer](https://docs.stripe.com/terminal/payments/setup-integration.md#configure) votre application. 3. [Configurer l’endpoint du token de connexion](https://docs.stripe.com/terminal/payments/setup-integration.md#connection-token) dans votre application et votre back-end. 4. [Initialiser le SDK](https://docs.stripe.com/terminal/payments/setup-integration.md#initialize) dans votre application. > Si vous créez une intégration **Applications sur des appareils** (exécutant votre application sur des lecteurs intelligents Stripe tels que le S700/S710), vous devrez effectuer des étapes supplémentaires de [configuration Android native](https://docs.stripe.com/terminal/features/apps-on-devices/build.md?terminal-sdk-platform=react-native#setup-app) après avoir suivi ce guide. ## Installer le SDK [Côté client] Le [SDK React Native](https://github.com/stripe/stripe-terminal-react-native) est disponible en open source et fait l’objet d’une documentation complète. En interne, il utilise les SDK iOS et Android natifs. Pour installer le SDK, veuillez exécuter : #### NPM ```bash npm install @stripe/stripe-terminal-react-native ``` #### Yarn ```bash yarn add @stripe/stripe-terminal-react-native ``` #### Expo ```bash npx expo install @stripe/stripe-terminal-react-native ``` ## Configurer votre application [Côté client] #### Interface de ligne de commande React Native #### iOS ### Pods Vous devez exécuter `pod install` dans votre répertoire `ios` pour installer les dépendances natives. ### Autorisations Pour que votre application puisse fonctionner avec le SDK Stripe Terminal, apportez quelques modifications à votre fichier **Info.plist** dans Xcode. 1. Activez les services de localisation avec la paire clé-valeur suivante. | Confidentialité – Description de l’utilisation de l’emplacement, le cas échéant | | ------------------------------------------------------------------------------- | | **Clé** | [NSLocationWhenInUseUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationwheninuseusagedescription) | | **Valeur** | **L’accès à l’emplacement est indispensable pour accepter des paiements.** | Afin de réduire les risques de fraude associés aux paiements et de limiter le nombre de litiges, Stripe a besoin de connaître le lieu où se déroulent les paiements. Si le SDK ne peut déterminer l’emplacement de l’appareil iOS, les paiements sont désactivés jusqu’à ce que l’accès à l’emplacement soit rétabli. 2. Assurez-vous que votre application fonctionne en arrière-plan et reste connectée aux lecteurs Bluetooth. | Modes d’arrière-plan requis pour les lecteurs Bluetooth | | ------------------------------------------------------- | | **Clé** | [UIBackgroundModes](https://developer.apple.com/documentation/bundleresources/information_property_list/uibackgroundmodes) | | **Valeur** | **bluetooth-central** (Utilise les accessoires Bluetooth LE) | La configuration du mode d’arrière-plan [bluetooth-central](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html#//apple_ref/doc/uid/TP40013257-CH7-SW6) permet au lecteur de rester en mode veille lorsque votre application est exécutée en arrière-plan, ou lorsque l’appareil iOS est verrouillé. Sans cette valeur, la mise en veille échoue. Lorsque votre application est exécutée en arrière-plan, le lecteur est susceptible de s’éteindre automatiquement afin d’économiser de l’énergie. 3. Autorisez votre application à afficher une boîte de dialogue d’autorisation Bluetooth. L’App Store exige l’intégration de cette option, même si votre application ne prend pas en charge la connexion aux lecteurs Bluetooth. | Confidentialité – Description de l’utilisation systématique du Bluetooth | | ------------------------------------------------------------------------ | | **Clé** | [NSBluetoothAlwaysUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/NSBluetoothAlwaysUsageDescription) | | **Valeur** | **Cette application utilise le Bluetooth pour se connecter aux lecteurs de cartes bancaires pris en charge.** | iOS 13 propose désormais des autorisations plus spécifiques concernant l’utilisation de périphériques Bluetooth par une application. Les applications associées à Core Bluetooth doivent inclure cette clé dans leur fichier Info.plist afin d’éviter que l’application ne plante lors de son premier lancement. 4. Passer les contrôles de validation de l’application lorsque vous la soumettez à l’App Store. À partir de la version 3.4.0 du SDK, cette exigence d’autorisation est supprimée. | Confidentialité – Description de l’utilisation du périphérique Bluetooth | | ------------------------------------------------------------------------ | | **Clé** | [NSBluetoothPeripheralUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothperipheralusagedescription) | | **Valeur** | **La connexion aux lecteurs de cartes pris en charge nécessite un accès au Bluetooth.** | Ceci est un exemple ; vous pouvez reformuler la demande d’autorisation de l’utilisateur dans votre application. 5. Sauvegardez le fichier **Info.plist** de votre application. Il est désormais correctement configuré et peut être utilisé avec le SDK Stripe Terminal. > Si vous utilisez Tap to Pay sur iPhone, vous devez [demander et configurer](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone) le droit de développement Tap to Pay sur iPhone à partir de votre compte Apple Developer. #### Android ### Autorisations Le SDK Stripe Terminal nécessite les autorisations Android suivantes pour fonctionner correctement : - `PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT` - `PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN` - `PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION` Utilisez la fonction utilitaire `requestNeededAndroidPermissions` pour demander automatiquement toutes les autorisations requises avant d’initialiser le SDK Terminal : ```js import { requestNeededAndroidPermissions } from '@stripe/stripe-terminal-react-native'; try { const granted = await requestNeededAndroidPermissions({ accessFineLocation: { title: 'Location Permission', message: 'Stripe Terminal needs access to your location', buttonPositive: 'Accept', }, }); if (granted) { // Initialize the SDK } else { console.error( 'Location and BT services are required to connect to a reader.' ); } } catch (e) { console.error(e); } ``` Sinon, si vous avez besoin d’un contrôle précis sur les demandes d’autorisation, vous pouvez demander manuellement chaque permission en utilisant `PermissionsAndroid.request` : ```js import { PermissionsAndroid } from 'react-native'; // Mobile readers using Bluetooth connection require BLUETOOTH_CONNECT, BLUETOOTH_SCAN, and ACCESS_FINE_LOCATION. // This example shows the pattern for requesting one permission. const granted = await PermissionsAndroid.request( PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION, { title: 'Location Permission', message: 'Stripe Terminal needs access to your location', buttonPositive: 'Accept', }, ); if (granted === PermissionsAndroid.RESULTS.GRANTED) { console.log('Location permission granted'); } else { console.error('Location permission denied'); } ``` ### Manifeste Pour garantir une compatibilité avec Android 12 et les versions ultérieures, veillez à ajouter `android:exported="true"` à `AndroidManifest.xml` : ```xml ``` Pour plus de contexte concernant les modifications apportées dans la version Android 12, consultez la [documentation Android relative à l’exportation de composants plus sécurisée](https://developer.android.com/about/versions/12/behavior-changes-12#exported). Pour les appareils sous Android 11 ou version antérieure, vous devez également activer les autorisations via le manifeste : ```xml ``` #### Expo > Ce package ne peut pas être utilisé dans l’application « Expo Go » car il nécessite un [code natif personnalisé](https://docs.expo.io/workflow/customizing/). Vous devez utiliser `npx expo prebuild` pour générer les projets natifs et exécuter votre application avec `npx expo run:ios` ou `npx expo run:android`. #### iOS ### Configuration du SDK Après l’[installation](https://docs.stripe.com/terminal/payments/setup-integration.md#installation) du SDK, ajoutez le [plugin de configuration](https://docs.expo.io/guides/config-plugins/) au tableau [plugins](https://docs.expo.io/versions/latest/config/app/#plugins) de votre `app.json` ou `app.config.js` : Définissez les options de configuration suivantes, en fonction de votre type de lecteur : - `localNetworkUsagePermission` - Obligatoire pour les lecteurs intelligents utilisant une connexion LAN - `appDelegate` - Obligatoire pour Tap to Pay sur Android - `tapToPayCheck` - Active la vérification de la compatibilité Tap to Pay ```json { "expo": { "plugins": [ [ "@stripe/stripe-terminal-react-native", { "bluetoothBackgroundMode": true, "locationWhenInUsePermission": "Location access is required to accept payments.", "bluetoothPeripheralPermission": "Bluetooth access is required to connect to supported bluetooth card readers.", "bluetoothAlwaysUsagePermission": "This app uses Bluetooth to connect to supported card readers.", "localNetworkUsagePermission": "This app uses the local WiFi network to connect to supported card readers.", "appDelegate": true, "tapToPayCheck": true } ] ] } } ``` ### Créer Ensuite, recréez votre application comme décrit dans le guide consacré à l’[ajout de code natif personnalisé](https://docs.expo.io/workflow/customizing/) avec : ```bash npx expo prebuild ``` puis : ```bash npx expo run:ios ``` > Si vous utilisez Tap to Pay sur iPhone, vous devez [demander et configurer](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone) le droit de développement Tap to Pay sur iPhone à partir de votre compte Apple Developer. #### Android ### Autorisations Le SDK Stripe Terminal nécessite les autorisations Android suivantes pour fonctionner correctement : - `PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT` - `PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN` - `PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION` Utilisez la fonction utilitaire `requestNeededAndroidPermissions` pour demander automatiquement toutes les autorisations requises avant d’initialiser le SDK Terminal : ```js import { requestNeededAndroidPermissions } from '@stripe/stripe-terminal-react-native'; try { const granted = await requestNeededAndroidPermissions({ accessFineLocation: { title: 'Location Permission', message: 'Stripe Terminal needs access to your location', buttonPositive: 'Accept', }, }); if (granted) { // Initialize the SDK } else { console.error( 'Location and BT services are required to connect to a reader.' ); } } catch (e) { console.error(e); } ``` Sinon, si vous avez besoin d’un contrôle précis sur les demandes d’autorisation, vous pouvez demander manuellement chaque permission en utilisant `PermissionsAndroid.request` : ```js import { PermissionsAndroid } from 'react-native'; // Mobile readers using Bluetooth connection require BLUETOOTH_CONNECT, BLUETOOTH_SCAN, and ACCESS_FINE_LOCATION. // This example shows the pattern for requesting one permission. const granted = await PermissionsAndroid.request( PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION, { title: 'Location Permission', message: 'Stripe Terminal needs access to your location', buttonPositive: 'Accept', }, ); if (granted === PermissionsAndroid.RESULTS.GRANTED) { console.log('Location permission granted'); } else { console.error('Location permission denied'); } ``` ### Configuration du SDK Après l’[installation](https://docs.stripe.com/terminal/payments/setup-integration.md#installation) du SDK, ajoutez le [plugin de configuration](https://docs.expo.io/guides/config-plugins/) au tableau [plugins](https://docs.expo.io/versions/latest/config/app/#plugins) de votre `app.json` ou `app.config.js` : Définissez les options de configuration suivantes, en fonction de votre type de lecteur : - `localNetworkUsagePermission` - Obligatoire pour les lecteurs intelligents utilisant une connexion LAN - `appDelegate` - Obligatoire pour Tap to Pay sur Android - `tapToPayCheck` - Active la vérification de la compatibilité Tap to Pay ```json { "expo": { "plugins": [ [ "@stripe/stripe-terminal-react-native", { "bluetoothBackgroundMode": true, "locationWhenInUsePermission": "Location access is required to accept payments.", "bluetoothPeripheralPermission": "Bluetooth access is required to connect to supported bluetooth card readers.", "bluetoothAlwaysUsagePermission": "This app uses Bluetooth to connect to supported card readers.", "localNetworkUsagePermission": "This app uses the local WiFi network to connect to supported card readers.", "appDelegate": true, "tapToPayCheck": true } ] ] } } ``` #### Créer Ensuite, recréez votre application comme décrit dans le guide consacré à l’[ajout de code natif personnalisé](https://docs.expo.io/workflow/customizing/) avec : ```bash npx expo prebuild ``` puis : ```bash npx expo run:android ``` ## Configurer l'endpoint du token de connexion [Côté serveur] [Côté client] ### Côté serveur Pour se connecter à un lecteur, votre back-end doit donner au SDK la permission d’utiliser le lecteur avec votre compte Stripe en lui fournissant la [clé secrète](https://docs.stripe.com/api/terminal/connection_tokens/object.md#terminal_connection_token_object-secret) d’un [ConnectionToken](https://docs.stripe.com/api/terminal/connection_tokens.md). Votre back-end doit créer des tokens de connexion uniquement pour les clients qu’il reconnaît comme fiables. #### curl ```bash curl https://api.stripe.com/v1/terminal/connection_tokens \ -u <>: \ -X "POST" ``` Obtenez la clé secrète à partir du `ConnectionToken` sur votre serveur et transmettez-la côté client. #### Ruby ```ruby post '/connection_token' do token = # ... Create or retrieve the ConnectionToken {secret: token.secret}.to_json end ``` > Le `secret` du `ConnectionToken` vous permet de vous connecter à n’importe quel lecteur Stripe Terminal et de traiter les paiements à l’aide de votre compte Stripe. Veillez à authentifier l’endpoint pour créer des tokens de connexion et à le protéger contre la falsification des requêtes intersites (CSRF). ### Côté client Pour permettre au SDK d’accéder à cet endpoint, créez une fonction de fournisseur de tokens qui demande un `ConnectionToken` à votre back-end. ```js import { StripeTerminalProvider } from '@stripe/stripe-terminal-react-native'; const fetchTokenProvider = async () => { const response = await fetch(`{YOUR BACKEND URL}/connection_token`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, }); const { secret } = await response.json(); return secret; }; ``` Cette fonction est appelée dès lors que le SDK doit s’authentifier auprès de Stripe ou du lecteur. Elle est également appelée lorsqu’un nouveau token est nécessaire pour se connecter à un lecteur (par exemple, lorsque votre application s’est déconnectée du lecteur). Si le SDK n’est pas en mesure de récupérer un nouveau jeton de connexion depuis votre backend, la connexion au lecteur échoue associée à une erreur de votre serveur. > Évitez de mettre en cache ou de coder en dur le token de connexion. Le SDK s’occupe de la gestion complète du cycle de vie du token de connexion. ## Initialiser le SDK [Côté client] Pour commencer, transmettez votre fournisseur de tokens implémenté à l’[étape 3](https://docs.stripe.com/terminal/payments/setup-integration.md#connection-token) à `StripeTerminalProvider` en tant que propriété. ```js import { StripeTerminalProvider } from '@stripe/stripe-terminal-react-native'; function Root() { const fetchTokenProvider = async () => { const response = await fetch(`${API_URL}/connection_token`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, }); const { secret } = await response.json(); return secret; }; return ( ); } ``` En dernière étape, appelez la méthode `initialize` depuis le hook `useStripeTerminal`. > Vous devez appeler la méthode `initialize` depuis un composant imbriqué dans `StripeTerminalProvider` et non depuis le composant qui contient `StripeTerminalProvider`. > > Une fois l’initialisation terminée, vous pouvez utiliser d’autres méthodes du SDK telles que `discoverReaders`, `connectReader` et `processPaymentIntent`. Si vous tentez d’appeler ces méthodes avant l’initialisation, vous recevrez le message d’erreur suivant : « Veuillez initialiser le SDK Stripe Terminal avant d’effectuer toute action. » ```js function App() { const { initialize } = useStripeTerminal(); useEffect(() => { initialize(); }, []); return ; } ``` ## Mises à jour du SDK Stripe publie régulièrement des mises à jour qui peuvent inclure de nouvelles fonctionnalités, des corrections de bugs et des mises à jour de sécurité. Mettez à jour votre SDK dès qu’une nouvelle version est disponible. Les SDK actuellement disponibles sont les suivants : - [SDK Stripe Terminal Android](https://github.com/stripe/stripe-terminal-android/releases) - [SDK Stripe Terminal iOS](https://github.com/stripe/stripe-terminal-ios/releases) - [SDK Stripe Terminal JavaScript](https://docs.stripe.com/terminal/references/api/js-sdk.md#changelog) - [SDK Stripe Terminal React Native](https://github.com/stripe/stripe-terminal-react-native) ## Prochaines étapes - [Se connecter à un lecteur](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=react-native&reader-type=internet)