Configurer votre intégration
Note
Pour les lecteurs intelligents, tels que le lecteur BBPOS WisePOS E reader ou le lecteur Stripe S700, nous vous recommandons d’utiliser l’intégration pilotée par serveur plutôt que le SDK JavaScript. L’intégration pilotée par serveur utilise l’API Stripe au lieu de s’appuyer sur les communications locales pour collecter les paiements. Le SDK JavaScript et le SDI ne prennent pas en charge le fonctionnement en mode hors ligne. Consultez notre comparaison des plateformes pour choisir plateforme la mieux adaptée à vos besoins.
Configuration requise pour le SDK Terminal JavaScript
Lorsque vous intégrez des lecteurs intelligents à l’aide du SDK JavaScript, assurez-vous que votre configuration réseau répond aux exigences ci-dessous, sinon votre intégration Terminal risque de ne pas fonctionner comme prévu.
- Le lecteur intelligent et l’application exécutant le SDK Terminal JavaScript sont connectés au même réseau local.
- Votre réseau autorise la résolution DNS des adresses IP locales. Si nécessaire, mettez à jour les paramètres DNS.
- Votre réseau Wi-Fi est protégé par un mot de passe et utilise le chiffrement WPA-Personal ou WPA2-Personal.
Pour démarrer avec le SDK JavaScript, suivez ces trois étapes :
- Installer le SDK et la bibliothèque client sur votre page de paiement
- Configurer l’endpoint du token de connexion sur votre back-end et votre application Web
- Initialiser le SDK sur votre application Web
Note
Si vous intégrez votre application web à l’aide du SDK JavaScript, vous pouvez l’exécuter sur le navigateur d’un appareil mobile dès lors que cet appareil est connecté au même réseau local que le lecteur et que les appareils de ce réseau peuvent communiquer directement les uns avec les autres.
Installer le SDK et la bibliothèque clientCôté clientCôté serveur
Côté client
Pour commencer, intégrez ce script à votre page de paiement. Ce script doit toujours être chargé directement à partir du site https://js.stripe.com pour des raisons de compatibilité avec les derniers logiciels du lecteur. Abstenez-vous d’intégrer le script dans un lot et d’héberger sur votre propre serveur, car cela risquerait de causer des dysfonctionnements dans votre intégration.
<script src="https://js.stripe.com/terminal/v1/"></script>
Utiliser le SDK JS Terminal comme un module
Nous proposons également un paquet npm pour charger et utiliser SDK JS Terminal en tant que module. Pour en savoir plus, consultez le projet sur GitHub.
Note
Pour en savoir plus sur la migration depuis une version bêta antérieure du SDK JavaScript, consultez le Guide de migration vers Stripe Terminal Bêta.
Côté serveur
Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application :
Configurer l'endpoint ConnectionTokenCôté serveurCô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 d’un ConnectionToken. Votre back-end doit uniquement créer des tokens de connexion pour les clients qu’il reconnaît comme fiables.
Obtenez la clé secrète du ConnectionToken sur votre serveur et communiquez-la au client.
Mise en garde
La clé secrète 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 dans votre application Web qui demande un ConnectionToken à votre back-end et renvoie la clé secrète, secret
, pour l’objet ConnectionToken.
async function fetchConnectionToken() { // Your backend should call /v1/terminal/connection_tokens and return the JSON response from Stripe const response = await fetch('https://{{YOUR_BACKEND_URL}}/connection_token', { method: "POST" }); const data = await response.json(); return data.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.
Mise en garde
Ne mettez pas en cache ni ne codez en dur le token de connexion. Le SDK gère le cycle de vie du token.
Initialiser le SDKCôté client
L’objet StripeTerminal
fourni par le SDK présente une interface générique permettant de rechercher un lecteur, de se connecter à un lecteur et de créer des paiements. Afin de lancer une instance StripeTerminal
sur votre application JavaScript, renseignez la fonction ConnectionToken mise en œuvre à l’étape 2.
Vous devez également fournir une fonction pour traiter les déconnexions intempestives du lecteur, onUnexpectedReaderDisconnect
. Dans le cadre de cette fonction, votre application doit informer l’utilisateur de la déconnexion du lecteur. Vous pouvez également inclure un moyen de tenter une reconnexion à un lecteur. Pour en savoir plus, consultez la page Traitement des déconnexions.
const terminal = StripeTerminal.create({ onFetchConnectionToken: fetchConnectionToken, onUnexpectedReaderDisconnect: unexpectedDisconnect, }); function unexpectedDisconnect() { // You might want to display UI to notify the user and start re-discovering readers }
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
- SDK Stripe Terminal iOS
- SDK Stripe Terminal JavaScript
- SDK Stripe Terminal React Native
Étapes suivantes
Navigateurs pris en charge
Nous mettons tout en œuvre pour que le SDK JavaScript Stripe Terminal prenne en charge toutes les versions récentes des principaux navigateurs. Nous prenons en charge :
- Edge sur Windows.
- Firefox pour ordinateur de bureau.
- Chrome et Safari, toutes plateformes.
- Le navigateur natif Android sur Android 4.4 et versions ultérieures.
Si vous rencontrez des problèmes avec le SDK JavaScript Stripe Terminal sur un navigateur donné, veuillez envoyer un e-mail à support-terminal@stripe.com.
Mise en garde
Remarque : l’utilisation du SDK JavaScript de Stripe Terminal avec React Native n’est pas prise en charge. Pour intégrer Stripe Terminal à votre application mobile avec React Native, utilisez le SDK Stripe Terminal React Native.