Collecte des données saisies à l'écran

Pour collecter des saisies à l’aide des lecteurs intelligents Terminal, utilisez la commande collect_inputs. L’API communique avec le lecteur pour afficher une interface utilisateur prédéfinie.

curl https://api.stripe.com/v1/terminal/readers/
{{READER_ID}}
/collect_inputs \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][text]"=Email \
  -d "inputs[1][selection][choices][0][id]"=email_id \
  -d "inputs[1][selection][choices][1][style]"=primary \
  -d "inputs[1][selection][choices][1][text]"=Printed \
  -d "inputs[1][selection][choices][1][id]"=printed_id \
  -d "inputs[1][selection][choices][2][style]"=secondary \
  -d "inputs[1][selection][choices][2][text]"="No thanks" \
  -d "inputs[1][selection][choices][2][id]"=no_thanks_id \
  -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

Personnalisation

Vous pouvez personnaliser l’apparence et le comportement de tous les types de saisie :

• Définissez les entrées 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.

• Utilisez des sauts de ligne dans votre texte pour une meilleure mise en forme.
• 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

• Une personnalisation supplémentaire est disponible pour les entrées de sélection. Lorsque vous spécifiez les choix, vous pouvez mettre en évidence ou atténuer les choix à l’aide du paramètre style.

Styles des options principal et secondaire du type de saisie « selection »

Métadonnées

Vous pouvez inclure des métadonnées, comme un ID de client ou de commande, dans votre requête. La charge utile de la requête comprend les métadonnées spécifiées, qui apparaissent à la fois dans la réponse synchrone et dans les événements de réussite ou d’échec. En incluant un identifiant unique, vous pouvez identifier et gérer plus facilement l’événement entrant.

Lorsque le lecteur commence à collecter des données saisies, il affiche la première donnée de la liste. Le client doit faire une sélection, fournir une signature ou utiliser le clavier pour procéder aux saisies obligatoires. Si la saisie est facultative, le client peut passer à la prochaine donnée obligatoire.

Une fois que le client a terminé toutes les saisies, le lecteur passe à un état transitoire pendant 3 secondes, en attendant une nouvelle demande. Si aucune requête n’est effectuée après 3 secondes, le lecteur revient à l’écran d’accueil.

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 :

• 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, l’id et le text correspondent aux chaînes id et text 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.
• La valeur de chaque bouton d’activation est renseignée avec enabled ou disabled.

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_BQokikJOvBiI2HlWgH4olfQ2
: \
  --header "Stripe-Version: 2025-05-28.basil;" \
  --data-urlencode "url"="https://example.com/webhook/endpoint" \
  --data-urlencode "api_version"="2025-05-28.basil;" \
  --data-urlencode "enabled_events[]"="terminal.reader.action_succeeded" \
  --data-urlencode "enabled_events[]"="terminal.reader.action_failed"

Abonnez-vous aux événements pour recevoir les données collectées dès qu’elles sont disponibles. Vous pouvez également récupérer les événements à partir du lecteur afin d’utiliser les événements de secours si votre back-end ne parvient pas à utiliser l’événement. 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 télécharger l’image de la signature collectée, récupérez le fichier et utilisez votre clé secrète pour accéder à son url.