Collecter les données saisiesBêta
Disponible dans : 🌎 pour le Stripe S700 et le BBPOS WisePOS E qui utilisent l’intégration pilotée par serveur, le Javascript SDK, le SDK iOS ou le SDK Android.
Note
Pour demander l’accès à la version bêta de Collect Inputs pour l’intégration pilotée par serveur, le SDK Javascript, le SDK iOS ou le SDK Android, contactez-nous à l’adresse stripe-terminal-betas@stripe.com.
Collecter les données saisies
Outre l’encaissement des paiements, les lecteurs intelligents Terminal vous permettent d’afficher des formulaires et de collecter des informations auprès de vos clients. Vous envoyez des requêtes à l’API Stripe, et celle-ci communique avec le lecteur afin d’afficher une interface utilisateur préconfigurée pour recueillir les commentaires de vos clients. Stripe notifie votre back-end des réponses du client à l’aide de webhooks.
Pour collecter des saisies à l’aide des lecteurs intelligents Terminal, utilisez la commande collect_inputs. Vous pouvez spécifier jusqu’à 5 saisies à la fois, et le lecteur les collecte dans l’ordre. Les lecteurs intelligents Stripe prennent actuellement en charge 6 types de saisie :
- Le type de saisie
selection
vous permet de présenter jusqu’à 4 options à votre clientèle. - Le type de saisie
signature
vous permet de collecter une signature à l’aide de l’écran tactile du lecteur. - Le type de saisie
email
vous permet de recueillir l’adresse e-mail d’un client. - Le type de saisie
phone
vous permet de recueillir le numéro de téléphone d’un client. - Le type de saisie
text
vous permet de recueillir des informations supplémentaires auprès de vos clients. - Le type de saisie
numeric
vous permet de recueillir des informations supplémentaires auprès de vos clients.
Types de saisie pris en charge.
Vous pouvez personnaliser l’apparence et le comportement de tous les types de saisie :
- Définissez les saisies importantes comme obligatoires pour vous assurer qu’elles sont collectées. Le bouton Ignorer est masqué lorsque la saisie est obligatoire.
- Fournissez des explications à votre client en spécifiant le texte à afficher sur l’écran du lecteur pour chaque saisie à l’aide de custom_text.
- Ajoutez jusqu’à 4 boutons d’activation que les clients peuvent activer ou désactiver pour les options booléennes, les consentements ou les adhésions.
Nom du champ | Field location | Maximum characters |
title | 40 | |
description | 280 | |
when used with the selection form | ||
description | 100 | |
when used with any other form type | ||
submit_button | 30 | |
skip_button | 14 | |
title | 50 | |
description | 50 | |
Formulaire d’e-mail et de sélection avec option d’activation
Une personnalisation supplémentaire est disponible pour les saisies de type sélection. Lorsque vous spécifiez les différentes options à présenter à votre clientèle, vous pouvez mettre en évidence ou atténuer certaines des options proposées en définissant le paramètre style.
Styles des options principal et secondaire du type de saisie « selection »
Outre la liste des saisies, vous pouvez inclure des métadonnées dans votre requête. La charge utile de la requête inclut les métadonnées spécifiées, qui apparaissent à la fois dans la réponse synchrone et dans les webhooks de réussite ou d’échec. En incluant un identifiant unique, comme un ID de client ou un ID de commande, vous pouvez identifier et gérer plus facilement le webhook entrant.
Bêta
Vous devez inclure l’en-tête terminal_collect_inputs_beta=v1
pour utiliser la fonction d’aperçu collect_inputs
. L’objet reader n’inclura pas l’objet collect_inputs dans les réponses de l’API si vous omettez l’en-tête.
Note
N’utilisez pas collect_inputs
pour collecter des informations sensibles (notamment des données de santé relevant du secret médical et les coordonnées de carte bancaire du client), ou des informations protégées par la loi.
Interaction avec le client
Lorsque le lecteur commence à collecter les données saisies, la première donnée à saisir de la liste que vous avez spécifiée s’affiche. Si la saisie est obligatoire, le client doit sélectionner une option ou signer pour continuer. Si la saisie est facultative, il peut passer à la prochaine donnée demandée.
Une fois que le client a soumis ou ignoré toutes les saisies, Stripe met à jour l’objet Reader et envoie le webhook terminal.reader.action_succeeded
.
Note
Il vous incombe de connaître et de respecter toutes les lois et réglementations applicables régissant votre utilisation de cette fonctionnalité, et vous devez, dans le cadre d’une telle utilisation, obtenir, le cas échéant, tous les consentements, licences, droits et autorisations nécessaires. Si vous utilisez les données collectées par un lecteur intelligent Terminal ou les résultats affichés pour conclure des contrats avec vos clients ou leur envoyer des avis, il vous incombe de garantir la validité juridique et le caractère exécutoire de ces contrats ou avis.
Recevoir les données saisies
Utilisez la commande curl ci-dessous comme exemple pour créer un endpoint de webhook et recevoir les données collectées.
curl https://api.stripe.com/v1/webhook_endpoints \ -u
: \ --header "Stripe-Version: 2023-10-16; terminal_collect_inputs_beta=v1" \ --data-urlencode "url"="https://example.com/webhook/endpoint" \ --data-urlencode "api_version"="2023-10-16;terminal_collect_inputs_beta=v1" \ --data-urlencode "enabled_events[]"="terminal.reader.action_succeeded" \ --data-urlencode "enabled_events[]"="terminal.reader.action_failed"sk_test_4eC39HqLyjWDarjtT1zdp7dc
Mise en garde
Vous devez créer l’endpoint de webhook directement avec l’API /v1/webhook_endpoints Stripe. L’objet collect_inputs ne renverra pas de résultats complets si vous créez l’endpoint de webhook avec la CLI Stripe ou des SDK côté serveur. Pour assurer la présence de l’objet collect_inputs
dans la charge utile du webhook, incluez terminal_collect_inputs_beta=v1
dans l’en-tête de la requête et définissez la propriété api_version
quand vous créez l’endpoint de webhook.
Pour commencer à écouter les entrées collectées, vous ne pouvez pas mettre à jour un webhook existant, vous devez en créer un nouveau.
Lorsque toutes les entrées ont été collectées ou ignorées, Stripe envoie une requête à votre endpoint de webhook. La charge utile de la requête est identique à la réponse lors de l’appel de collect_inputs, mais elle ajoute quelques paramètres supplémentaires :
- Le paramètre
value
est renseigné pour chaque donnée collectée.- Pour les saisies de type signature, la valeur est un ID de fichier qui récupère l’image de la signature au format SVG.
- Pour les saisies de type sélection, la valeur est la chaîne de la
value
de l’option sélectionnée. - Pour les saisies de type numéro de téléphone, adresse e-mail, texte et chiffres, la valeur est la chaîne de la réponse du client.
- Si une saisie facultative est ignorée par le client, le paramètre skipped est défini sur
true
. - Chaque option d’activation a pour
value
enabled
oudisabled
.
Abonnez-vous aux webhooks pour recevoir les entrées collectées dès qu’elles sont disponibles. Vous pouvez récupérer le lecteur avec l’en-tête de requête terminal_collect_inputs_beta=v1
comme solution de secours si votre back-end ne parvient pas à utiliser le webhook.
Stripe envoie deux webhooks pour informer votre back-end de l’état du lecteur :
terminal.reader.action_succeeded
: envoyé lorsqu’une actioncollect_inputs
réussit.terminal.reader.action_failed
: envoyé lorsqu’une actioncollect_inputs
échoue. Cela inclut les expirations, qui surviennent après 2 minutes d’inactivité sur l’écran du lecteur.
Télécharger les images des signatures
Pour recevoir l’image de la signature collectée, récupérez le fichier et utilisez votre clé secrète pour accéder à son URL.
Note
Stripe conserve les images de signature que vous collectez pendant 7 jours. Si vous devez utiliser des images de signature plus de 7 jours après les avoir collectées, téléchargez le fichier et conservez-le. Il vous incombe de connaître et de respecter toutes les lois applicables à l’utilisation, à la conservation et à la divulgation des signatures de vos clients.
SDK bêta
Si vous utilisez l’un des SDK de Stripe côté serveur, vous devez installer une version bêta. Vous trouverez les instructions d’installation sur la page GitHub correspondant au SDK de serveur que vous souhaitez utiliser.
Vous devez également configurer la version de l’API de votre SDK pour inclure l’en-tête bêta mentionné ci-dessus. Consultez des exemples spécifiques à chaque langage.
Note
Les boutons d’activation nécessitent la version 2.21
du lecteur (ou ultérieure).