Collecte des données saisies à l'écranBêta

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.
• Indiquez le contexte à votre client en spécifiant le texte que vous souhaitez 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.

Formulaire d’e-mail et de sélection avec option d’activation

Pour les saisies de type sélection, une personnalisation supplémentaire est disponible. Lorsque vous spécifiez les différentes options que vous souhaitez 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 comprend les métadonnées spécifiées, qui apparaissent 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.

curl https://api.stripe.com/v1/terminal/readers/
{{READER_ID}}
/collect_inputs \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Version: 2024-11-20.acacia; terminal_collect_inputs_beta=v1;" \
  -d "inputs[0][type]"=signature \
  -d "inputs[0][custom_text][title]"="Rental Agreement" \
  -d "inputs[0][custom_text][description]"="Please sign below to indicate that you agree to the rental agreement." \
  -d "inputs[0][custom_text][submit_button]"=Submit \
  -d "inputs[0][required]"=true \
  -d "inputs[1][type]"=selection \
  -d "inputs[1][selection][choices][0][style]"=primary \
  -d "inputs[1][selection][choices][0][value]"=Email \
  -d "inputs[1][selection][choices][1][style]"=primary \
  -d "inputs[1][selection][choices][1][value]"=Printed \
  -d "inputs[1][selection][choices][2][style]"=secondary \
  -d "inputs[1][selection][choices][2][value]"="No thanks" \
  -d "inputs[1][custom_text][title]"=Receipt \
  --data-urlencode "inputs[1][custom_text][description]"="How would you like your receipt?" \
  -d "inputs[1][required]"=true \
  -d "inputs[2][type]"=email \
  -d "inputs[2][custom_text][title]"="Enter your email" \
  --data-urlencode "inputs[2][custom_text][description]"="We'll send updates on your order and occasional deals" \
  -d "inputs[2][required]"=true \
  -d "inputs[2][toggles][0][title]"="Opt-in for marketing emails" \
  -d "inputs[2][toggles][0][default_value]"=enabled \
  -d "metadata[order_number]"=12345

Lorsque le lecteur commence à recueillir des données saisies, il affiche la première donnée de la liste que vous avez indiquée au client. Le client doit faire une sélection, fournir une signature ou utiliser le clavier pour procéder aux saisies obligatoires. Toutefois, pour les saisies facultatives, le client a la possibilité de passer à la saisie suivante demandée.

Une fois que le client a soumis ou ignoré toutes les saisies, Stripe met à jour l’objet lecteur et envoie le webhook terminal.reader.action_succeeded. Le lecteur passe à un état interstitiel pendant 3 secondes, au cours desquelles il peut accéder à une autre demande. Après ces trois secondes, le lecteur revient à l’écran d’accueil.

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 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  --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"

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 du choix sélectionné.
  • 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 ou disabled.

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 action collect_inputs réussit.
• terminal.reader.action_failed : envoyé lorsqu’une action collect_inputs échoue. Cela inclut les expirations, qui surviennent après 2 minutes d’inactivité sur l’écran du lecteur.

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.